Skip to content

taskrabbit/tests_doc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

40 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

TestsDoc

This library allow to output requests specs into readable markdown files. It can link the markdown file to the spec ran.

This library supports RSpec 2 and RSpec 3

Install

gem install tests_doc

Example Output

GET users

Rspec description: Users GET /users renders users

spec/requests/users_spec.rb:5

Parameters

{
}

Response

HTTP CODE = 200
[
  {
    "id": 298486374,
    "email": "MyString",
    "first_name": "MyString",
    "last_name": "MyString",
    "created_at": "2015-11-19T01:11:08.000Z",
    "updated_at": "2015-11-19T01:11:08.000Z"
  },
]

Example App

You can see a Rails 4 example app with the recorded markdown inside the tests-doc folder

Usage

In your spec_helper.rb RSpec file:

require 'tests_doc'

config.include ::TestsDoc::RecordSpecHelper, type: :request

TestsDoc.configure do |config|
  # The regexes allow you to by pass run time object updated_at and other ids
  # run time object between each execution
  config.changes_whitelist_regex      = /(.*\"((id)|([\w]+((_id)|(_at))))\":.*\n)|(.*_ids":\s\[\s*\w+\s*\])/ # default: ""

  # OR
  config.changes_whitelist_regexes = [
    /\"id\":.*\n/,
    /_id\":.*\n/,
    /_at\":.*\n/,
    /.*_ids":\s\[\s*\w+\s*\]/
  ]

  # Folder location where the tests doc will be stored
  config.root_folder = Rails.root.join("api_interactions")  # default: tests-doc

  # Folder name where the tests doc will be stored
  config.doc_folder  = 'api' # default: api

  # Key separator between the path and the key
  config.key_separator = '@' # default: @

  # Add RSpec line number to the test doc
  config.add_spec_file_number = false # default: true

  # tests-doc file will save the timestamps of the last modification
  config.add_index_timestamps = false # default: true

  # Will output the diff debug of recorded test docs
  config.debug = true # default: false
end

Recording interactions in your tests

In your request spec file simply wrap your request with recording_api_interaction:

recording_api_interaction do
  get users_path
end

You can also set options for the recording:

  • The key option allows to record a test doc and append to the file name the key:
recording_api_interaction do |options|
  options.key = 'with-filter'
  get posts_path(published: true)
end

Will generate a markdown file named [email protected].

  • The path option allows to specify the path you want, a good reason for that is that you want to extract the id of you ActiveRecord object.
recording_api_interaction do |options|
  options.path = 'users/@id/posts'
  get user_posts_path(User.first)
end

Will generate here a markdown file named posts.md in the users/@id folder.

  • the whitelist option allow you to add on the global regex whitelist:
recording_api_interaction do |options|
  options.whitelist = /\"token\":.*\n/
  get users_path(User.first)
end

Generating the Index file

You can generate the index file that list all endpoint using the following rake command.

rake tests_doc:index:build

If you want to only build it if there is a git changes on your file:

rake tests_doc:index:build_if_changed

You could also specify which folder to use for the index file:

rake "tests_doc:index:build_if_changed[api_interactions]"

It's also possible to rewrite the index after the RSpec suite:

config.after :suite do |test|
  # block executed when there is any api interactions were recorded during the RSpec
  TestsDoc.with_api_interaction do
    require 'rake'
    require 'tests_doc/tasks'

    Rake::Task["tests_doc:index:build_if_changed"].invoke(TestsDoc.configuration.root_folder)
  end
end

TODO

  • Add tests
  • Publish gem
  • Fix warnings

About

Rspec request specs recorded as Markdown files

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages