Lurker
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.
Installation
Add this line to your application's Gemfile:
gem 'lurker'
Add to test_helper.rb
or spec_helper.rb
:
require 'lurker/spec_helper'
Usage
Wrap your intergation test code, which does request like this
Lurker::Spy.on do
get "/api/v1/users.json"
end
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"
end
Minitest usage
You can use minitest-around to wrap your test classes like this:
class DestroyRepoTest < ActionDispatch::IntegrationTest
def around(&block)
Lurker::Spy.on(&block)
end
end
You also can wrap any block with api requests manually.
Schemas
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.
Profit!
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#
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
Features
- 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
api/v1/:user_id/repos
) - JSON-Schema partials, also in YAML format (demo)
- Generation PDF documentation
- Multiple docs for many usecases (e.g
:lurker => '...'
) - ERB support inside
.json.yml.erb
- 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_rack
serves 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 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
Contributions
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
Acknoledgements
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
- Andrey Deryabin for advice
- React.js for two-way binding
- highlight.js for syntax highlighting