The new de-facto for API testing your Rails application. Works on Rails 3.2, 4.0, 4.1 & Ruby 1.9.3, 2.0.0, 2.1.1.
Add this line to your application's Gemfile:
Wrap your intergation test code, which does request like this
::. do get "/api/v1/users.json" end
And run the specs and commit your schemas. That's all, easy!
it "lists users", :lurker do get "/api/v1/users.json" end
You can use minitest-around to wrap your test classes like this:
class DestroyRepoTest < ActionDispatch::IntegrationTest def around(&block) ::.(&block) end end
You also can wrap any block with api requests manually.
Please, commit your files under
Feel free to edit them according to json-schema standart.
It can be very strict and flexible if you wish: see example,
but scaffolded schemas are pretty good by default.
A lurker/ExampleApp.service.yml A lurker/api/v1/users-GET.json.yml A lurker/api/v1/users/__user_id/repos-GET.json.yml
I also advise you to look on Understanding JSON Schema book, it is up-to-date with draft4 and contains lot's of examples.
Now, every test run lurker will look into your requests and vaditate them and it fails if your code changes the api!
Failure/Error: post :create [...] Lurker::ValidationError: Request - The property '#/' contains additional properties ["social_network"] outside of the schema when none are allowed in schema file:///.../lurker/api/v1/users-POST.json.yml# Response - The property '#/user/last_sign_in_at' of type String did not match the following type: null in schema file:///.../lurker/api/v1/users-POST.json.yml#
Now, you can test your API on-line (for real)
You can clone the repo & run
rake build_example_docs && cd tmp/lurker_app && bin/rails s
to get your running demo.
Lurker supports multiple domains (usually
production) and can be deployed
statically everywhere as well as be served by current
- Github Pages is deployed statically; no api endpoint
- Custom domain html deployed under nginx; passenger serves demo api production endpoint
- Heroku html is served by unicorn as well as staging api endpoint in
- Autoscaffolding for non-covered API endpoints
- Autotesting for covered endpoint once written (both request & response!)
- Pretty HTML documentation based on your schemas
- Pretty submit form to test API endpoints (live) based on schemas (enter a name & press "Submit")
- Handling URLs with dynamic segments (such as
- JSON-Schema partials, also in YAML format (demo)
- Generation PDF documentation
- Multiple docs for many usecases (e.g
:lurker => '...')
- ERB support inside
- HTTP-Auth authorization for your online docs
- Separate API-services generated within one test suite
- Capistrano integration
- JSON-Schema draft-v4 support
- Static site deploy and milti-domain support
- Builtin Rack middlware
Lurker::Server.to_rackserves cached digested assets
- RSpec & Minitest support
Token authentication with sandbox
Lurker::Sandbox allows you to test services with token authentication:
# make sure it's not production! # e.g. config/environtents/staging.rb config.middleware.use ::
E.g. demo application on Heroku runs with it: when creating, updating repos or users ids getting increased, but if you look into GET #index, new items are NOT showing up. This is NOT a bug! - sequences in postgres are increasing notwithstanding ROLLBACK is called. As such:
- run all your specs with the same testing token
- ensure the same token to be accepted on your demo application
Lurker::Sandboxand the recorded examples should be ok to submit again
I try to use Waffle to develop this gem, if you want to help:
- look on "Ready" section
- drag an issue to "In Progress" and assign to yourself
- have fun!
NOTE: to get new version of bundled
bootstrap or update js/css,
don't touch files under
lib/lurker/templates/public - they are autogenerated
and copied to static generated site while
rake assets:precompile # to build them
lib/lurker/templates/public/**/* to avoid conflicts.
NOTE: if you write features keep in mind to generate different files with aruba,
because they are kept in
lurker_app directory to be deployed as a demo. Please, write
features in a way to generate new relevant
To run cucumber in a clean
html directories run:
CLEAN=1 cucumber features
NOTE: template partial
submit_form.html.erb and it's partials is a big
jsx script for
so there are
<label htmlFor instead of
<label for> and
<div className instead of
Sponsored by Evil Martians, thanks!
Also thanks to