Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/softwaremill/livestub
The HTTP server stub you always wanted!
https://github.com/softwaremill/livestub
http http-server mocking-server scala stub-server
Last synced: 2 days ago
JSON representation
The HTTP server stub you always wanted!
- Host: GitHub
- URL: https://github.com/softwaremill/livestub
- Owner: softwaremill
- Created: 2020-03-20T11:10:05.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-12-12T00:24:50.000Z (10 days ago)
- Last Synced: 2024-12-13T06:50:21.091Z (9 days ago)
- Topics: http, http-server, mocking-server, scala, stub-server
- Language: Scala
- Homepage:
- Size: 776 KB
- Stars: 53
- Watchers: 28
- Forks: 8
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# livestub
[](https://travis-ci.org/softwaremill/livestub)
[](https://hub.docker.com/r/softwaremill/sttp.livestub/)
[](https://scala-steward.org)
[](https://search.maven.org/search?q=g:com.softwaremill.sttp.livestub)
With livestub you can easly setup http server that behaves exactly as you would like it to. That makes livestub a perfect solution for faking arbitrary services which might be very useful in development/testing.
## Usage
### launch
- **coursier**
`coursier launch com.softwaremill.sttp.livestub:livestub-app_2.13:0.2.1 -- -p 7070`
- **docker**
`docker run -p 7070:7070 softwaremill/sttp.livestub`
- **code**
```scala
import sttp.livestub.app.LiveStubServer
import sttp.livestub.app.LiveStubServer.Config
LiveStubServer.resource(Config(port = 7070))
```
### stub
```bash
curl -X POST 'localhost:7070/__set' \
-d '{"when":{"method":"GET", "url":"animals/1/status"}, "then": {"statusCode":200, "body":{"status": "happy"} }}'
```
### invoke
```bash
curl 'localhost:7070/animals/1/status'
{"status":"happy"}
```
### swagger
Swagger is available under `/__admin/docs`
### advanced stubbing
Livestub supports wildcard http methods as well as wildcard path parameters.
wildcard method:
```bash
curl -X POST 'localhost:7070/__set' \
-d '{"when":{"method":"*", "url":"dogs"}, "then": {"statusCode":200, "body":{"status": "OK"} }}'
```
wildcard path param:
```bash
curl -X POST 'localhost:7070/__set' \
-d '{"when":{"method":"GET", "url":"dogs/*/status"}, "then": {"statusCode":200, "body":{"status": "happy"} }}'
```
multiwildcard path param: (this one catches all routes which originate from `/dogs`)
```bash
curl -X POST 'localhost:7070/__set' \
-d '{"when":{"method":"GET", "url":"dogs/**"}, "then": {"statusCode":200, "body":{"status": "cheerful"} }}'
```
wildcard query param: (this one catches all the query parameters for `/dogs`, example: `/dogs?id=1&breed=bulldog`)
```bash
curl -X POST 'localhost:7070/__set' \
-d '{"when":{"method":"GET", "url":"dogs?*"}, "then": {"statusCode":200, "body":{"status": "cheerful"} }}'
```
### additional methods
clear stubbed routes
```bash
curl -X POST 'localhost:7070/__clear'
```
show stubbed routes
```bash
curl 'localhost:7070/__routes'
```
set many responses which will be cycled through
```bash
curl -X POST 'localhost:7070/__set_many' \
-d '{"when":{"method":"GET", "url":"animals/1/status"}, "then": [
{"statusCode":200, "body":{"status": "happy"} },
{"statusCode":200, "body":{"status": "unhappy"} }
]
}'
```
### stubbing from code - sdk
```scala
libraryDependencies += "com.softwaremill.sttp.livestub" % "livestub-sdk" % "0.2.1"
```
Given a bunch of imports
```scala
import sttp.client3.asynchttpclient.cats.AsyncHttpClientCatsBackend
import sttp.client3.SttpBackend
import sttp.livestub.sdk._
import sttp.livestub.api._
import sttp.client3.{Response => _, _}
import sttp.model._
import io.circe.Json
```
you can stub an arbitrary request:
```scala
AsyncHttpClientCatsBackend[IO]().flatMap { backend: SttpBackend[IO, Any] =>
val livestub = new LiveStubSdk[IO](uri"http://mock:7070", backend)
livestub
.when(RequestStubIn(MethodStub.Wildcard, "/user/*/status"))
.thenRespond(Response.emptyBody(StatusCode.Ok, List(Header("X-App", "123"))))
}
```
stub given [sttp](https://github.com/softwaremill/sttp) request:
```scala
AsyncHttpClientCatsBackend[IO]().flatMap { backend: SttpBackend[IO, Any] =>
val request = basicRequest
.body(Map("name" -> "John", "surname" -> "doe"))
.post(uri"https://httpbin.org/post?signup=123")
val livestub = new LiveStubSdk[IO](uri"http://mock:7070", backend)
livestub.when(request).thenRespond(Response(Some(Json.fromString("OK")), StatusCode.Ok))
}
```
or stub given [tapir](https://github.com/softwaremill/tapir) endpoint:
```scala
import sttp.tapir._
AsyncHttpClientCatsBackend[IO]().flatMap { backend: SttpBackend[IO, Any] =>
val myEndpoint = endpoint.get.in("/status").out(stringBody)
val livestub = new LiveStubSdk[IO](uri"http://mock:7070", backend)
livestub.when(myEndpoint)
.thenRespond(Response.emptyBody(StatusCode.Ok, List(Header("X-App", "123"))))
}
```
## OpenApi integration
OpenApi specification can be provided to bootstrap livestub server with auto generated endpoints.
For each given path a request-response stub will be generated matching particular url. Both path parameters and required query parameters will be
replaced by wildcard matches. That means that neither optional query parameters, request body nor headers are going to be checked when matching
stubbed endpoint.
Response structure will follow openapi schema. Response data will be created
based on openapi respective example parameters if provided, otherwise random data will be used(whenever it is possible).
For endpoints, which are defined in openapi specification but for which responses
couldn't be generated empty response body will be returned.
Usage:
`--openapi-spec `
In addition, seed value for random data generator can be passed via:
`--seed 1234`
## Development
Documentation is generated during every release from `docs-sources` directory.
It can be manually regenerated when needed by calling `sbt docs/mdoc`.
To release new version use `sbt release`.