watchdocs-rails

Watchdocs Rails JSON API requests watcher.

It captures every JSON response, stores request and response details in temporary storage. Provides methods to send recorded calls to Watchdocs which checks them agains the documentation or create docs for new calls.

Installation

Add to your Gemfile. It is recommended to add to :test, :development group.

gem 'watchdocs-rails'

and run

bundle

Configuration

Create config/initializers/watchdocs.rb and configure the gem with your project credentials:

  Watchdocs::Rails.configure do |c|
    c.app_id = 'YourAPPid'
    c.app_secret = 'YourAPPsecret'
  end

You can get them from your project's Settings page. All configuration settings are listed below.

buffer_size

Default: 50

Buffer is a place where the gem stores recorderd requests. Buffer size is maximum number of requests that can be stored in a buffer. When limit is reached, buffer content is being exported and cleared. In other words: Buffer is being exported and cleared every buffer_size reqests.

While executing specs buffer is a memory, otherwise it's a temporary file stored in temp_directory.

temp_directory

Default: tmp

Directory to store temporary file with recordings.

export_url

Default: https://watchdocs-api.herokuapp.com/api/v1/reports

URL for exporting recorgings to your Watchdocs project.

app_id

No default value

AppID key which you can get for your Watchdocs project in settings section.

app_secret

No default value

App Secret key which you can get for your Watchdocs project in settings section.

Usage

You can enable Watchdocs to record request while executing specs or making manual tests. You can of course do both at the same time if you want.

Tests

If you have some requests specs or features specs that call JSON API then add this line to your config/environments/test.rb.

config.middleware.insert(0, Watchdocs::Rails::Middleware)

Update/create your spec hooks:

RSpec

In specs/rails_helper.rb:

  config.before(:suite) do
    ....
    Watchdocs::Rails::Recordings.clear!
  end

  config.after(:suite) do
    ....
    Watchdocs::Rails::Recordings.export
  end

Minitest

Minitest.after_run do
  Watchdocs::Rails::Recordings.export
end

Configuring with WebMock

If you are using WebMock and it complains about real HTTP call please disable it for when exporting data to our API.

config.after(:suite) do .... WebMock.disable! Watchdocs::Rails::Recordings.export WebMock.enable! end

Configuring with VCR

If you are using VCR add this line to your VCR.configure block:

VCR.configure do |c|
  config.ignore_request do |req|
    req.uri == Watchdocs::Rails.configuration.export_url
  end
end

Development (manual tests)

If you don't have any request specs yet, you can add the following line to config/environments/development.rb.

config.middleware.insert(0, Watchdocs::Rails::Middleware)

To make sure we will receive all recorded request please add this worker command to your Procfile or run it manually:

watchdocs --every 60.seconds

Watchdocs will be recording all requests in your development environment during manual tests and export them every buffer_size requests and every 60 seconds (you can adjust the frequency to your needs).

You can of course enable the middleware in any other environment like dev or staging.

Versioning

Semantic versioning (http://semver.org/spec/v2.0.0.html) is used.

For a version number MAJOR.MINOR.PATCH, unless MAJOR is 0:

  1. MAJOR version is incremented when incompatible API changes are made,
  2. MINOR version is incremented when functionality is added in a backwards-compatible manner,
  3. PATCH version is incremented when backwards-compatible bug fixes are made.

Major version "zero" (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable. Furthermore, version "double-zero" (0.0.x) is not intended for public use, as even minimal functionality is not guaranteed to be implemented yet.

Dependencies

  • httparty
  • configurations
  • recurrent

Contributing

  1. Fork it ( https://github.com///fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request