Fakeit
Fukuoka Ruby Award - Special Award
Create mock server from Openapi specification
Motivation
Openapi mock server is one of core components to support contract based development and testing. As part of our journal, several key requirements for such mock server have been identified:
- Control response generation in non intrusive manner. i.e. without modifying example in contract
- Randomly generated response to support property based testing
- Fulfill property reference in response generation to support development against contract. i.e. regarding the following response, guarantee the
selectedId
property is always a validid
in the items
{
"selectedId": 1,
"items": [
{ "id": 1 },
{ "id": 2 }
]
}
After tried several existing options, we cannot find a best solution to meet all the requirements. So we end up with Fakeit.
Features
- Randomly or statically generated response (
application/.*json
) - Request validation (
application/.*json
,multipart/form-data
) - Load specification from local or remote
- Support hot reload local specification
- Support specification in yaml or json format
- [Experimental] Support plain text and binary response, e.g.
application/pdf
Installation
Install it with:
$ gem install fakeit
Or use the docker image
Usage
$ fakeit --spec <Local file or remote url>
Command line options
$ fakeit --help
usage:
--spec spec file uri (required)
-p, --port custom port
-q, --quiet mute request and response log
-l, --log-file redirect log to a file
--permissive log validation error as warning instead of denying request
--use-example use example provided in spec if exists
--static generate static response
--static-types generate static value for specified types, e.g. --static-types integer,string
--static-properties generate static value for specified properties, e.g. --static-properties id,uuid
--base-path mounts the mock server at the given path, e.g. --base-path /api
other options:
-v, --version
-h, --help
Notes:
- See here for Openapi properties supported in random response generation
- See here for default value in static response generation
- Regarding
--use-example
mode, property without example specified will still be randomly or statically generated - Random response generation can not handle recursive schema reference. If you do need it in your spec file, please provide
example
property for the recursive part of schema and specify--use-example
option.
Configuration endpoint
Mock server behaviour can be changed on the fly
Retrieve current config:
GET /__fakeit_config__
Update config:
PUT /__fakeit_config__
Request and response:
{
"permissive": false,
"use_example": true,
"static": false,
"static_types": [
"integer"
],
"static_properties": [
"id"
],
"base_path": "/api"
}
Development
After checking out the repo, run bundle install
to install dependencies. Then, run rake
to run the tests.
To install this gem onto your local machine, run bundle exec rake install
.
To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/JustinFeng/fakeit.
License
The gem is available as open source under the terms of the MIT License.