Generates API schemas, validates code against them and creates a handy web interface for testing the API. Tested on on Rails 4, 5, 6 and Ruby >= 2.6
Wrap your integration 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!
it "lists users", :lurker do get "/api/v1/users.json" end
NOTE: If you use
rspec-rails, it should be required first
require 'rspec/rails' require 'lurker/spec_helper'
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.
Please, commit your files under
Feel free to edit them according to json-schema standard.
It can be very strict and flexible if you wish: see an 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 of examples.
Now, every test run lurker will look into your requests and validate 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#
The generation of live-documentation is pretty simple:
bin/lurker convert # builds html under `Rails.root/public/lurker` to be served under `/lurker` url bin/lurker convert -f pdf # builds `Rails.root/public/lurker/snake_cased_name.pdf`
For different document root or serving URL prefix use
-u options accordingly.
If you want to provide additional documentation for your API (and you probably should), you can use separate Markdown files in the schema folder. To generate documentation stubs for the current schema:
bin/lurker init_docs # generate documentation stubs for the current schema
Now, you can test your API on-line (for real)
Custom domain static + demo api production endpoint (in
You can run this to get the demo running locally:
git clone https://github.com/razum2um/lurker.git cd lurker export BUNDLE_GEMFILE=gemfiles/rails_6.gemfile bundle install rake build_example_docs cd tmp/lurker_app_rails_6 bin/rails s
Lurker supports multiple domains (usually
production) and can be deployed
statically everywhere as well as be served by the current
gem 'pdfkit'to Gemfile)
:lurker => '...')
gem 'kramdown'to Gemfile)
gem 'execjs'to Gemfile)
Lurker::Server.to_rackserves cached digested assets
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 PostgreSQL are increasing notwithstanding ROLLBACK is called. As such:
Lurker::Sandboxand the recorded examples should be ok to submit again
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
export BUNDLE_GEMFILE=gemfiles/rails_6.gemfile 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 the
lurker_app directory to be deployed as a demo. Please, write
features in a way to generate new relevant
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
Currently, the testing application is using PostgreSQL because the same testing app is deployed to serve demo purposes.
This is also the reason not to delete anything under
lurker directory between feature tests
and using different API endpoints of the testing app. To run cucumber with clean
public/lurker directories run:
CLEAN=1 export BUNDLE_GEMFILE=gemfiles/rails_6.gemfile bundle exec cucumber features
Beware while writing your feature tests for PRs.
Also thanks to