Dredd::Rack should allow to write Dredd hooks in Ruby

[gonzalo-bulnes]

As a developer
In order to be able to take profit of my habitual testing tools (e.g. FactoryGirl) to setup documentation and testing scenarios
I want to be able to write Dredd hooks in Ruby

See also: the original discussions and this proof of concept.

[gonzalo-bulnes]

The Apiary team did a great work on this! See the newly released Ruby Hook Handlers and the corresponding Dredd feature! :D

This Dredd::Rack feature should definitely be built on the DreddHooks::Methods module!

[gottfrois]

Hey @gonzalo-bulnes any news on this ? Do you have any starting point I can look at ?

[gonzalo-bulnes]

Hi @gottfrois,

News: the Dredd Hooks gem is pretty much ready to be used as a library (it was primarily built to provide a CLI). Which means that Dredd::Rack can depend on it to manage the communication with Dredd and provide hooks support.

The API of the DreddHooks library is so far (source):

# So far the Dredd Hooks library is only used by the Dredd Hooks CLI.

require 'dredd_hooks'

out = STDOUT
error = STDERR

# Load the hook files
DreddHooks::FileLoader.load(hook_files)

# Run the server
out.puts 'Starting Ruby Dredd Hooks Worker...'
server = DreddHooks::Server.new(error, out)
server.run

Some context to get started

I've been gathering a few thoughts and a first attempt of raodmap on a Trello card. Reflecting on that, I should probably have gathered them in this issue instead - they would have been publicly accessible.

Anyway, I'm reproducing them here (chronological order):

---

Ideas

I think following the RSpec example would be fine: spec directory + spec_helper.rb

For the default directory:

• blueprint/ sounds fine
• api_blueprint/ might be redundant, and may be longer than desirable... but would be specific
• apib/ would be short, but might be cryptic, would stay before app
• doc/blueprint/ or doc/api/blueprint/ wouldn't be bad either

For the default config file:

• blueprint_helper sounds fine, but it would suggest moving the *.apib files out of doc/
• api_blueprint_helper may be a bit longer than desirable, but is quite specific which is nice
• apib_helper is short, maybe a bit cryptic
• considering that the requirement in hook files would be relative (we require spec_helper, not spec/spec_helper):
• blueprint_helper doesn't look bad
• api/blueprint_helper might be a bit more complex than desirable, particularly considering that this is not a standard Ruby require beacuse there is no api/ directory

Roadmap

• Review DreddHooks
• Update dependencies + add Gemnasium badge
• Draft support using DreddHooks
• Allow the use of FactoryGirl
• Define a default path for hook files - see comments
• And pick a default name for the default config file - see Add FactoryGirl support in hook files
• Testing should probably include a Rails app
• Announce in apiaryio/dredd-hooks-ruby: Issue Minor add Travis CI configuration #3
• Keep an eye on https://github.com/apiaryio/dredd-test-rails
• Don't forget Fix outdated runner documentation
• Add files to the gemspec if necessary (dummy app for example)
• Update CHANGELOG
• Release (see the previous one, there are quite a few thing to check) - v1.0.0-beta1?
• Add dredd-hooks as dependency, or peer dependency

---

Out of that, I think it's worth first defining how Dredd::Rack would be used once it supports running hooks, what the directories layout would look like (default values) - in a README-driven development spirit - so that we can then write specs and test-drive it easily.

Does it make sense to you?
Do you want to help me picking reasonable defaults? (If it sounds reasonable to two of us it is more likely to be actually reasonable than if I pick them by myself, what do you think?)

That could be done in this issue, I think, or editing the README in a PR. How does all that sound to you?

By the way, it is worth mentioning that I don't have a schedule on this, so no pressure. I'm happy to spend more time on it if you're interested though. : )

Let me know!

[gottfrois]

Thanks for the detailed answer!

I'll be happy to help you get to speed on that project. I'm using is in the company I work for and for now the main bottleneck is the lack of hooks support for creating objects in databases based on our Rails models.

Today I cheat by doing the following:

namespace :api do
  desc "Launch dredd test suits against all api blueprint files define in doc folder"
  task :test => :environment do

    raise 'must run in test env' unless Rails.env.test?

    # Purge database
    Rake::Task["db:purge"].invoke
    # Populate database with dummy data
    Rake::Task["db:seed"].invoke
    # Start dredd tests
    Dredd::Rack.app = Rails.application
    dredd = Dredd::Rack::Runner.new do |config|
      config.paths_to_blueprints 'apiary.apib'
      config.language :ruby
      config.level :info
      config.sorted!
    end
    dredd.run

    # Exit task with correct status inherited from dredd command.
    exit $?.exitstatus || 1
  end
end

And create some object before test suits in db/seeds.rb.

As I said, I'll be glad to help define standards that make sense to both of us. Maybe you could create a github "project" for that repository with your trello like cards?

[gonzalo-bulnes]

Hi @gottfrois,

I'm glad to hear that! :D

I'm exploring the Projects documentation... I'm not sure there is need for that much, but I created a first project to see how it goes. First question: can you see it, use it? I didn't find any way to add collaborators to the project itself, but I expect it to behave like the wiki.

To discuss how Dredd::Rack should behave / be used once support for Dredd hooks is implemented, I think an issue is probably enough. However, I'm adding doc/README.md to hold the ideas that we think are good. (I did this experimentally in another project and I'd like to see how it goes.)

The idea is making the upcoming changes visible while we make progress on the implementation. See #38. Comments welcome of course.

Next step

I'll start moving the ideas I mentioned in my previous comment to the draft README (doc/README.md).

What do you think about directory names, the helper name? I'm following the RSpec pattern here, I can explain the idea a bit further if you want.

Note: Travis CI seems to be a bit unstable at the moment (I've never see this error before at least). I'll give it some time before re-trying.

[gottfrois]

Regarding folder names, I like the following doc/blueprint/ because

1. Blueprints aren't spec on their own, they are doc files
2. The gem should be responsible for glueing together the blueprints and do whatever is needed to turn them into test definitions

I can imagine the following structure:

.
├── app
├── doc
│   ├── api.apib
├── spec
│   ├── rails_helper.rb
│   ├── spec_helper.rb
│   ├── dredd_helper.rb

Of course I would strongly advice an option in dredd_helper.rb that allows one to change the default doc/ blueprint directory to something else. I'm thinking about Apiary which put the blueprint in the root of the git repo for example.

[pelted]

I just started using Dredd and quickly realized I was going to need to use hooks. After getting everything running I stumbled across this project this morning. I guess my question is what am I missing with using dredd-hooks-ruby, having my *hooks.rb files and then calling this with rails dredd? Fixtures takes care of loading test data, and it seems to work out-of-the-box.