Mull

mull

verb

think about (a fact, proposal, or request) deeply and at length. "she began to mull over the various possibilities" synonyms: ponder, consider, think over/about, reflect on, contemplate, turn over in one's mind, chew over, cogitate on, give some thought to "I'll have to mull it over before making a final decision"

mull is a tool for thinking over an api service you are consuming.

It has two jobs:

  • execute pre-defined requests against an api server you are consuming and save the results to a fixtures directory
  • mirror those requests with the fixture content

Installation

Add this line to your application's Gemfile:

gem 'mull'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mull

Usage

Define all your requests in a mull.yml file. It has the following format:

root_url: http://jsonplaceholder.typicode.com
path_prefix: fixtures
requests:
- url: /posts/1
  matcher: /posts/\d+
  method: POST
  status: 200
  file: foobar.json
  headers:
    test-header: 1
  post_body:
    thing: ^\d$

Valid keys

Top level keys

  • root_url: The root url of the api server you are consuming
  • path_prefix: The directory where you want the fixture files to go

Per request keys

  • url: The exact path of the request on the server, eg. /posts/1. If matcher: is not present, this value is also used to route incoming requests. The outgoing request won't be made if this key is missing.
  • matcher: A regex that matches the exact path. mull server will use this to map incoming requests
  • matcher_headers: Hash of headers to use. If present, mull server will use this to map incoming requests. If not, no header checking will occur against incoming requests.
  • headers: Hash of headers to use. If present, mull fetch_all requests will this for outgoing requests. If not, no headers will be used for outgoing requests.
  • post_body: Hash of multipart form body values. Will both be submitted with the mull fetch_all requests and matched against incoming requests to mull server
  • method: HTTP method of the request. Incoming and outgoing
  • status: HTTP status
  • file: Path to fixture file to use
  • body: Hard-coded response for this endpoint. It is an error to use both the body key and the file key. The outgoing request will not be made if this key is present.

Once your mull file is good to go, you can execute all the defined requests and save the results by running

mull fetch_all

Then with the fixtures in place, start up a local server with

mull server

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Bug reports and pull requests are welcome.

License

mull is BSD licensed.