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.

Gem Version Build Status Dependency Status alpha


Add this line to your application's Gemfile:

gem 'lurker'

Add to test_helper.rb or spec_helper.rb:

require 'lurker/spec_helper'


Wrap your intergation test code, which does request like this

Lurker::Spy.on do
  get "/api/v1/users.json"

And run the specs and commit your schemas. That's all, easy!

RSpec usage

Write your RSpec controller or request specs as usual, but add :lurker mark (like documented controller example or request spec example).

it "lists users", :lurker do
  get "/api/v1/users.json"

Minitest usage

You can use minitest-around to wrap your test classes like this:

class DestroyRepoTest < ActionDispatch::IntegrationTest
  def around(&block)

You also can wrap any block with api requests manually.


Please, commit your files under Rails.root/lurker directory. 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 [...]
  - 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#
  - 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#

Let's run your rails s and visit http://localhost:3000/lurker/ (or see demo for example)

Now, you can test your API on-line (for real)

Demo application

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 staging and production) and can be deployed statically everywhere as well as be served by current Rails instance.

For example:

  • 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 Sandbox mode


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 Lurker::Sandbox

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
  • insert Lurker::Sandbox and the recorded examples should be ok to submit again


Code Climate Coverage Status Inline docs Stories in Ready

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 bin/lurker convert

rake assets:precompile # to build them

Don't commit 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 lurker/**/*.json.yml files

To run cucumber in a clean lurker & html directories run:

CLEAN=1 cucumber features

NOTE: template partial submit_form.html.erb and it's partials is a big jsx script for React so there are <label htmlFor instead of <label for> and <div className instead of <div class


Sponsored by Evil Martians, thanks!

This gem is quite opinionated and relies on rails - if you're interested in anything else, please take a look at api_taster or fdoc, This gem is heavily inspirated by them. Thanks, @square & @fredwu

Also thanks to