apiaryio / dredd-hooks-ruby Goto Github PK

View Code? Open in Web Editor NEW

15.0 16.0 7.0 114 KB

Ruby Hooks Worker for Dredd API Testing Framework

Home Page: http://dredd.rtfd.org/en/latest/hooks-ruby/

License: MIT License

Ruby 70.53% Gherkin 29.47%

dredd ruby dredd-hooks sjs-team

dredd-hooks-ruby's Introduction

Ruby Hooks Handler for Dredd API Testing Framework

Test your API with the Dredd HTTP API testing framework and write hooks in Ruby!

DISCLAIMER: This is an early version of dred-hooks-ruby, please be aware that it will not be stable until v1.0.0. At any moment, feedback is welcome! : )

Installation

Add the gem to your Gemfile:

# Gemfile

gem 'dredd_hooks', '0.1.2' # see semver.org

Usage

Create a hook file (the file name is arbitrary):

# ./hooks.rb

require 'dredd_hooks/methods'

include DreddHooks::Methods

before "Machines > Machines collection > Get Machines" do |transaction|
  transaction['skip'] = "true"
end

Run it with Dredd:

# note that the hooks file was named ./hooks.rb
dredd apiary.apib localhost:3000 --language ruby --hookfiles ./hooks.rb

Documentation

API

The DreddHooks::Methods module provides the following methods to be used with transaction names:

before
after
before_validation

And these ones to be used without them:

before_all
after_all
before_each
after_each
before_each_validation

See also the official Hooks documentation.

Change log

Releases are commented to provide a brief change log, details can be found in the CHANGELOG file.

Development

Testing

# Run the test suite
rake

A set of RSpec specs provide both a granular documentation and a unit test harness. RSpec tags are used to categorize the spec examples.

Spec examples that are tagged as public describe aspects of the gem public API, and MAY be considered as its documentation.

The private or protected specs are written for development purpose only. Because they describe internal behaviour which may change at any moment without notice, they are only executed as a secondary task by the continuous integration service and SHOULD be ignored.

Run rake spec:public to print the gem public documentation.

Behavioral Spec

A few Cucumber features from the dredd-hooks-template provide an end-to-end test harness. The test suite is provided as a Node.js package and needs to be installed by npm:

npm install

Then the tests can be ran using the npm test command, but for the Ruby paths to be correctly set, an environment variable BUNDLE_GEMFILE needs to be set to the path to the Gemfile. An example how running the end-to-end tests can look like on macOS:

BUNDLE_GEMFILE=$(pwd)/Gemfile npm test

Maintenance

Extending the DSL to support new hooks is meant to be easy, see the maintenance documentation for details. : )

Refactored with love, internet style.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Update the CHANGELOG
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

License

See LICENSE.

dredd-hooks-ruby's People

Contributors

Stargazers

Watchers

Forkers

gonzalo-bulnes jeffdeville nelyj petejohansonxo ourfabriq

dredd-hooks-ruby's Issues

Merge of gonzalo-bulnes/dredd-hooks-ruby

Hey @gonzalo-bulnes,

I noticed you did a huge amount of amazing work in your fork. I'm sorry we didn't have much time to merge your pull requests, but it doesn't mean we're not interested in your contributions!

We have this Aruba/Cucumber based integration test-suite so I feel very confident and I'm more than happy to give you maintainer rights to this repository. You could continue your work here and kind of help yourself when needed. We will do our best on our part. What do you think? Would you be interested?

Adam

Your .dependabot/config.yml contained invalid details

Dependabot encountered the following error when parsing your .dependabot/config.yml:

The property '#/update_configs/1/package_manager' value "ruby" did not match one of the following values: javascript, ruby:bundler, php:composer, java:maven, elixir:hex, rust:cargo, java:gradle, dotnet:nuget, go:dep, go:modules, docker, elm, submodules, python, terraform

Please update the config file to conform with Dependabot's specification using our docs and online validator.

You can mention @dependabot in the comments below to contact the Dependabot team.

Coordination - ensuring the gem is production-ready

Hello,

I decided to tackle gonzalo-bulnes/dredd-rack#7, and to implement it using this gem in order to keep concerns separated. Before making dredd-hooks-ruby a dependency of Dredd::Rack, however, I'd like to refactor/improve it a bit so:

its versions are named following the Semantic Versioning conventions
it has a change log (example)
its code "feels more like Ruby" - follows the usual naming conventions, is a bit more idiomatic, a bit DRYer...
its maintenance is easier for a Ruby dev. - add a few Rake tasks for testing, eventually add a unit test suite

I'm happy to do that as a contribution to dredd-hooks-ruby, and opened this issue for coordination purpose.

More details

Some of that will be refactoring, but some will also introduce changes in the API (following the naming conventions may change the include DreddHooks::Methods statement for example), but to make it more familiar to Ruby developers.

What I see as the API:

the binary name, and default URL, ports [can't be changed because Dredd relies on them - correct me if I'm wrong]
the DSL [I see no reason to change it]
the DSL inclusion statement [if I change it I'll make the change explicit - that's the point of semantic versioning]
the hook names [no reason to change them, I mean it's a Dredd concern not a dredd-hooks-ruby one]

Questions / Ideas

I've forked the project, and will start working on it. I have a few questions:

I could formalize my TO DO list as a series of issues here (I can't open them against my fork), and close them from the corresponding commits. IMO it would allow to set a roadmap and they could be tagged accordingly or assigned to myself, but I want to be sure it's OK before flooding you with issues and PR
I'm assuming the current version being 0.0.1 makes changing the versioning scheme and slightly modifying the API not a big deal, but again, you are the maintainers and I don't want these changes to sound scary

What do you think?

Edit: I removed the third question because I was mistaken: Travis CI is installing the gem locally, and there is no inconvenient in bumping the version number without releasing the corresponding gem. I'll just start working in my fork, and am willing to PR the result as soon as you want. : )

The gem code should follow the most common Ruby practices and idioms

As a Ruby developer
In order to make the gem maintenance easier

I want its README to display build, dependencies, code climate and inline doc badges
See gonzalo-bulnes#4

I want its code to be as simple as possible
And as idiomatic as possible
See gonzalo-bulnes#1, gonzalo-bulnes#5, gonzalo-bulnes#7 and gonzalo-bulnes#9

And I want the addition of new hooks to be as simple as possible
See gonzalo-bulnes#6 and gonzalo-bulnes#8

Aruba should be up to date

Please see this comment and the few next ones.

Support Ruby 2.5

In #35 I'm unable to get 2.5 working for some reason and I'm getting cryptic errors about bundler versions and missing binaries. I'm filing this issue to do investigation in the future and to support 2.5 as a next step.

The gem should have a change log

As a developer who considers updating Dredd Hooks Ruby
In order to have a clear idea of which changes I should expect
I want them described in a CHANGELOG

As an Apiary developer
In order to make it consistent and easy to maintain
I want the Dredd Hooks Ruby to be similar to other Apiary change logs

See gonzalo-bulnes#2 and #5 (comment)

There is some way we do create Changelog for Dredd. It would be nice to have the process unified. Please note I don't think the current state is completely ideal - apiaryio/dredd#440, suggestions on improvements welcome.

The gem should use Semantic Versioning

As a developer
In order to be able to update my dependencies automatically
And to be sure their maintainers care about their API
I want their version numbers to convey meaning

See gonzalo-bulnes#3
See also #5

Raising NoMethodError inside a hook block causes a hard-to-debug error message

If you raise, for example, a StandardError inside of a before_each block:

require "dredd_hooks/methods"
include DreddHooks::Methods

before_each do |transaction|
  raise StandardError
end

When you run Dredd you will see the expected error message:

$ info: Hooks handler stderr: /Users/nicolasiensen/.../dredd_hooks.rb:5:in `block in <top (required)>': StandardError (StandardError)

However, if the exception being raised inside of the before_each block is a NoMethodError:

require "dredd_hooks/methods"
include DreddHooks::Methods

before_each do |transaction|
  raise NoMethodError
end

Then the error message is completely misleading:

$ info: Hooks handler stderr: /Users/nicolasiensen...dredd_hooks/server/events_handler.rb:24:in `rescue in block in handle': Unknown hook: before_each (DreddHooks::UnknownHookError)

I've spent hours debugging dredd-hooks-ruby code trying to understand why before_each was not a valid hook, only to discover later that my code was raising NoMethodError inside of the hook block 🤦‍♂️

The cross-language test suite should be up-to-date

The template was recently updated with minor changes. As a synchronization exercise all the Dredd hooks implementations are currently being updated and this one should too.

See for reference apiaryio/dredd-hooks-template#16