dredd-rack 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83f6608237e6187d0936c756c484d5523815f6b7
-  data.tar.gz: 6b907927501c14d0d5a2d0c25d83c820f662508a
+  metadata.gz: df87b935a638c2038e83e801e28641077a711fbe
+  data.tar.gz: 642d5c8ddc31c41e3770b8523b54c35b0ba800ba
 SHA512:
-  metadata.gz: 3d87acb28bce3bd82cc6fbba7c32672c199f33468c3acd7cc44ad651def388320347b6cb14d16cb7cc427f4f71de2ed3ce78cc3ef9d484da4cb520adabed627a
-  data.tar.gz: 5fc2365b87c9ee272d3f1e93a0baeab87658ec908fc840bec504d3c6d5c79d05e07350d4528416118c6097f6f9941a581d9a381b18cbb7789e6682c458fd5f70
+  metadata.gz: 558870fb92e474692d10b01955ec8ff012ad5b461b9ed3605a24d9c0edb154ea9ece9e2c5a165bad76269e81277797fafe6033c7635472f1690d8a37bf65c5f0
+  data.tar.gz: c591fcba3305d303b20fe08052727ad998400ea09795fa4d6fea2d98814b5fbc9e0a9acfb66d360d575c40e3235435bb73b6189f40d6124fd3820bebe1cfb381

data/README.md

@@ -1,12 +1,15 @@
 Dredd::Rack
 ===========
 
+[![Gem Version](https://badge.fury.io/rb/dredd-rack.svg)](http://badge.fury.io/rb/dredd-rack)
 [![Build Status](https://travis-ci.org/gonzalo-bulnes/dredd-rack.svg?branch=master)](https://travis-ci.org/gonzalo-bulnes/dredd-rack)
 [![Code Climate](https://codeclimate.com/github/gonzalo-bulnes/dredd-rack.svg)](https://codeclimate.com/github/gonzalo-bulnes/dredd-rack)
-[![Dredd Reference Version](https://img.shields.io/badge/dredd_reference_version-0.4.1-green.svg)](https://github.com/apiaryio/dredd)
+[![Dredd Reference Version](https://img.shields.io/badge/dredd_reference_version-0.4.8-brightgreen.svg)](https://github.com/apiaryio/dredd)
 [![Inline docs](http://inch-ci.org/github/gonzalo-bulnes/dredd-rack.svg?branch=master)](http://inch-ci.org/github/gonzalo-bulnes/dredd-rack)
 
-This gem provides a [Dredd][dredd] runner and a `blueprint:verify` rake task to make [API blueprint][blueprint] testing convenient for Rack applications. When verifying blueprints locally, an application server is automatically set up, without need of any manual intervention.
+> **DISCLAIMER**: This is an early version of Dredd::Rack, please be aware that it will not be stable until `v1.0.0`. At any moment, [feedback][issues] is more than welcome! : ) -- [GB][gonzalo-bulnes]
+
+This gem provides a [Dredd][dredd] runner and a `dredd` rake task to make [API blueprint][blueprint] testing convenient for Rack applications. When verifying blueprints locally, an application server is automatically set up, without need of any manual intervention.
 
 Besides being convenient, that allows to use the API blueprints as acceptance test suites to practice [BDD][rspec-book] with Dredd and RSpec, for example, while clients developers use [Apiary][apiary] as a mock server.
 
@@ -14,6 +17,8 @@ Besides being convenient, that allows to use the API blueprints as acceptance te
   [blueprint]: https://apiblueprint.org/
   [rspec-book]: https://pragprog.com/book/achbd/the-rspec-book
   [apiary]: http://apiary.io
+  [issues]: https://github.com/gonzalo-bulnes/dredd-rack/issues
+  [gonzalo-bulnes]: https://github.com/gonzalo-bulnes
 
 Installation
 ------------
@@ -23,71 +28,117 @@ Add the gem to your `Gemfile`:
 ```ruby
 # Gemfile
 
-gem 'dredd-rack', '~> 1.0' # see semver.org
+gem 'dredd-rack', '~> 0.4.0' # see semver.org
 ```
 
-Getting Started
----------------
+Define which application Dredd::Rack must serve automatically:
+
+```ruby
+# config/initializers/dredd-rack.rb or app.rb or Rakefile
 
-### Dredd::Rack::Runner
+require 'dredd/rack'
 
-_To do._
+# Allow the automatic setup of a local application server when necessary
+#
+# Find the name of your application in its `config.ru` file.
+Dredd::Rack.app = Example::Application # or Rails.application, Sinatra::Application...
+```
 
+Usage
+-----
 
-### Rake task
+### Getting started
 
-Use the `dredd` rake task from your `Rakefile`:
+Define the `dredd` rake task in your `Rakefile`:
 
 ```ruby
 # Rakefile
 
 require 'dredd/rack'
 
-# Configure Dredd::Rack to automatically set a server up for your application
-Dredd::Rack.app Sinatra::Application # or the name of your modular-style app, or Rails app
+# ...
 
-# That's all!
+# Define the :dredd task
+Dredd::Rack::RakeTask.new # run: `dredd doc/*.apib doc/*.apib.md <local or remote URL>`
 
 # Optionally add the API blueprint verification to the default test suite
 # task :default => [:spec, :dredd]
 ```
 
-Run the API blueprint verification locally:
+Run the API blueprint verification:
 
 ```bash
+# locally
 rake dredd
 
 # or specify a remote server:
-#API_HOST=http://api.example.com rake blueprint:verify
+#API_HOST=http://api.example.com rake dredd
 ```
 
-Usage
------
+The `:dredd` rake task requires no further configuration. However, it relies on the following convention: API blueprints must be stored in the `doc` directory with either the `.apib` or the `.apib.md` extension.
 
-### Custom rake task name or description
+### Further usage
 
-You can also define a custom rake task name or description:
+Of course you can define your own rake tasks with custom runners!
+
+Each Dredd::Rack runner stores a specific Dredd configuration. In order to manage different runners, you can define multiple rake tasks with custom names or descriptions:
 
 ```ruby
 # Rakefile
 
-require 'dredd/rack'
-
-# Configure Dredd::Rack to automatically set a server up for your application
-Dredd::Rack.app Sinatra::Application # or the name of your modular-style app, or Rails app
+# ...
 
 namespace :blueprint do
-  desc 'Verify an API complies with its blueprint'
-  Dredd::Rack::RakeTask.new(:verify)
+  namespace :verify do
+
+    desc 'Verify the whole API compliance with its blueprint'
+    Dredd::Rack::RakeTask.new(:all)
+
+    desc 'Verify the Machines API compliance with its blueprint'
+    Dredd::Rack::RakeTask.new(:machines) do |task|
+      task.runner.configure do |dredd|
+        dredd.only 'Machines > Machines Collection > List all Machines',
+                   'Machines > Machine > Retrieve a Machine' # etc.
+        dredd.sorted!.details!
+      end
+    end
+
+    # ...
+  end
 end
+
+# run with `rake blueprint:verify:all` and `rake blueprint:verify:machines`
 ```
 
+Both the [rake task documentation][rake-task-doc] and the [runner documentation][runner-doc] contain more examples, and the runner documentation does also contain a comprehensive list of the [configuration methods][conf] that can be used to customize runners. Take a look at them!
+
+  [rake-task-doc]: doc/rake_task.md
+  [runner-doc]: doc/runner.md
+  [conf]: doc/runner.md#configuration-methods-reference
+
+
+#### Remote API testing
+
+Configuring a runner for remote API blueprint compliance testing is as easy as setting its **api_endpoint** option (see the [runner documentation][conf]). Please remember that you must ensure that the API is being served at the specified URI when performing remote API blueprint validation.
+
+Credits
+-------
+
+The `Dredd::Rack::RakeTask` is heavily inspired in the [`RSpec::Core::RakeTask`][rspec-core-raketask]. Let the corresponding credits go to the RSpec team.
+
+  [rspec-core-raketask]: https://github.com/rspec/rspec-core/blob/v3.2.1/lib/rspec/core/rake_task.rb
+
 License
 -------
 
     Dredd::Rack provides convenient API blueprint testing to Rack applications.
     Copyright (C) 2015  Gonzalo Bulnes Guilpain
 
+    Copyright (C) 2012 Chad Humphries, David Chelimsky, Myron Marston
+    Copyright (C) 2009 Chad Humphries, David Chelimsky
+    Copyright (C) 2006 David Chelimsky, The RSpec Development Team
+    Copyright (C) 2005 Steven Baker
+
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or

data/doc/rake_task.md

@@ -0,0 +1,119 @@
+See also: [Dredd::Rack::Runner](runner.md)
+
+Dredd::Rack::RakeTask
+=====================
+
+**Table of Contents**
+
+1. [Example](#example)
+1. [Custom name, description](#custom-rake-task-name-description)
+1. [Custom runner](#custom-rake-task-runner)
+1. [Fully custom rake tasks](#fully-custom-rake-tasks)
+
+----
+
+Example
+-------
+
+Use the `dredd` rake task from your `Rakefile`:
+
+```ruby
+# Rakefile
+
+require 'dredd/rack'
+Dredd::Rack.app = Example::Application
+
+Dredd::Rack::RakeTask.new
+# That's all! Dredd::Rack will serve the app automatically,
+# and the :dredd task is defined.
+
+# Optionally add the API blueprint verification to the default test suite
+# task :default => [:spec, :dredd]
+```
+
+Run the API blueprint verification:
+
+```bash
+# locally
+rake dredd
+
+# or specify a remote server:
+#API_HOST=http://api.example.com rake dredd
+```
+
+Custom rake task name, description
+----------------------------------
+
+You can define a custom task name or description:
+
+```ruby
+# Rakefile
+
+# ...
+
+require 'dredd/rack'
+Dredd::Rack.app = Example::Application
+
+namespace :blueprint do
+  desc 'Verify the API blueprint accuracy'
+  Dredd::Rack::RakeTask.new(:verify)
+end
+
+# run with: `rake blueprint:verify`
+```
+
+Custom rake task runner
+-----------------------
+
+You can also configure the Dredd::Rack runner:
+
+```ruby
+# Rakefile
+
+# ...
+
+require 'dredd/rack'
+Dredd::Rack.app Example::Application
+
+Dredd::Rack::RakeTask.new(:dredd) do |task|
+  task.runner.configure do |dredd|
+    dredd.paths_to_blueprints 'blueprints/*.md', 'blueprints/*.apib'
+    dredd.level(:silly).no_color!
+  end
+end
+
+# run with: `rake dredd`
+```
+
+Fully custom rake tasks
+-----------------------
+
+In fact, you can define as many tasks as you need, with custom names, descriptions or runners:
+
+```ruby
+# Rakefile
+
+require 'dredd/rack'
+Dredd::Rack.app RobotsFactory::API
+
+namespace :blueprint do
+  namespace :verify do
+
+    desc 'Verify the whole API compliance with its blueprint'
+    Dredd::Rack::RakeTask.new(:all)
+
+    desc 'Verify the Machines API compliance with its blueprint'
+    Dredd::Rack::RakeTask.new(:machines) do |task|
+      task.runner.configure do |dredd|
+        dredd.only 'Machines > Machines Collection > List all Machines',
+                   'Machines > Machine > Retrieve a Machine' # etc.
+        dredd.sorted!.details!
+      end
+    end
+
+    # ...
+  end
+end
+
+# run with `rake blueprint:verify:all` and `rake blueprint:verify:machines`
+```

data/doc/runner.md

@@ -0,0 +1,95 @@
+See also: [Dredd::Rack::RakeTask](rake_task.md)
+
+Dredd::Rack::Runner
+===================
+
+**Table of Contents**
+
+1. [Example](#example)
+1. [Runner configuration](#runner-configuration)
+1. [Configuration methods reference](#configuration-methods-reference)
+
+----
+
+Example
+-------
+
+```ruby
+
+# Dredd command to run:
+# `dredd *.apib *.md <local API endpoint> --level "warning" --no-color`
+
+dredd = Dredd::Rack::Runner.new do |options|
+  options.paths_to_blueprints '*.apib', '*.md'
+  options.level(:warning).no_color!
+end
+
+# run Dredd (a server will be started and stopped automatically)
+dredd.run
+```
+
+Runner configuration
+--------------------
+
+Runners can be configured immediately after being created (see example above), or at any moment using the `configure` method:
+
+```ruby
+dredd = Dredd::Rack::Runner.new
+
+dredd.configure do |options|
+  options.api_endpoint 'https://api.example.com'
+  options.details!
+end
+```
+
+Please note that configuration methods can be chained for convenience:
+
+```ruby
+dredd.configure { |options| options.level(:info).sorted!.no_color! }
+```
+
+Configuration methods reference
+-------------------------------
+
+```ruby
+# See https://github.com/apiaryio/dredd#command-line-options for Dredd commands usage
+
+dredd = Dredd::Rack::Runner.new do |options|
+
+  options.api_endpoint 'https://api.example.com' # allows to validate remote API
+
+  options.hookfiles 'doc/hooks/*_hooks.coffee'
+
+  options.only 'Machines > Machines Collection > List all Machines',
+               'Machines > Machine > Retrieve a Machine'
+
+  options.reporter(:markdown)
+  options.reporter(:html).output('doc/report.html')
+
+  options.header 'X-User-Email: alice@example.com'
+  options.header 'X-User-Token: 1G8_s7P-V-4MGojaKD7a'
+
+  options.user 'username:password'
+
+  options.level(:info)
+
+  options.path('doc/*.md').path('doc/*.apib.md')
+
+  options.method('POST').method('PUT')
+
+  options.dry_run!            # no_dry_run!
+  options.names!              # no_names!
+  options.sorted!             # no_sorted!
+  options.inline_errors!      # no_inline_errors!
+  options.details!            # no_details!
+  options.color!              # no_color!
+  options.timestamp!          # no_timestamp!
+  options.silent!             # no_silent!
+
+  options.help
+  options.version
+end
+
+# run Dredd (you don't have to worry about the server unless the API is remote)
+dredd.run
+```

data/lib/dredd/rack/rake_task.rb

@@ -3,6 +3,21 @@ require 'rainbow'
 require 'rake'
 require 'rake/tasklib'
 
+# This class is heavily inspired in the RSpec::Core::RakeTask, which
+# was published under the MIT license by:
+#
+# Copyright (C) 2009 Chad Humphries, David Chelimsky
+# Copyright (C) 2006 David Chelimsky, The RSpec Development Team
+# Copyright (C) 2005 Steven Baker
+#
+# See https://github.com/rspec/rspec-core/blob/v3.2.2/lib/rspec/core/rake_task.rb
+#
+# Modifications are part of Dredd::Rack, published under the GNU GPLv3 ot later by:
+#
+# Copyright (C) 2015 Gonzalo Bulnes Guilpain
+#
+# See https://github.com/gonzalo-bulnes/dredd-rack/blob/v0.3.0/lib/dredd/rack/rake_task.rb
+
 module Dredd
   module Rack
 
@@ -32,32 +47,18 @@ module Dredd
       attr_reader :runner
 
       # Define a task with a custom name, arguments and description
-      def initialize(*args)
+      def initialize(*args, &task_block)
         @name = args.shift || :dredd
         @description = 'Run Dredd::Rack API blueprint verification'
         @runner = Dredd::Rack::Runner.new(ENV['API_HOST'])
 
         desc description unless ::Rake.application.last_comment
-        task name, args do
+        task name, *args do |task_args|
+          task_block.call(*[self, task_args].slice(0, task_block.arity)) if task_block
           run_task(runner)
         end
       end
 
-      def run_task(runner)
-        abort dredd_not_available_message unless dredd_available?
-
-        puts starting_message
-
-        puts command_message(runner)
-
-        success = runner.run
-        exit_status = $?.exitstatus
-
-        puts connection_error_message(runner) unless success if dredd_connection_error?(exit_status)
-
-        abort unless exit_status == 0
-      end
-
       private
 
         def dredd_available?
@@ -100,6 +101,21 @@ module Dredd
           eos
         end
 
+        def run_task(runner)
+          abort dredd_not_available_message unless dredd_available?
+
+          puts starting_message
+
+          puts command_message(runner)
+
+          success = runner.run
+          exit_status = $?.exitstatus
+
+          puts connection_error_message(runner) unless success if dredd_connection_error?(exit_status)
+
+          abort unless exit_status == 0
+        end
+
         def starting_message
           <<-eos.gsub /^( |\t)+/, ""
 

data/lib/dredd/rack/runner.rb

@@ -38,9 +38,6 @@ module Dredd
       # Store the Dredd command line options
       attr_accessor :command_parts
 
-      # Return the API endpoint
-      attr_reader :api_endpoint
-
       # Initialize a runner instance
       #
       # The API endpoint can be local or remote.
@@ -56,18 +53,36 @@ module Dredd
         yield self if block_given?
       end
 
+      # Set or return the runner API endpoint
+      #
+      # Use with no arguments to read the runner API endpoint,
+      # provide an API endpoint to set it.
+      #
+      # api_endpoint - String URL of the API endpoint to validate
+      #
+      # Returns the String URL of the runner API endpoint.
+      def api_endpoint(api_endpoint=nil)
+        @api_endpoint = api_endpoint unless api_endpoint.nil?
+        @api_endpoint
+      end
+
       # Return the Dredd command line
       def command
         ([@dredd_command, @paths_to_blueprints, @api_endpoint] + @command_parts).join(' ')
       end
 
+      # Configure the runner instance
+      def configure
+        yield self if block_given?
+      end
+
       # Define custom paths to blueprints
       #
       # paths_to_blueprints - as many Strings as paths where blueprints are located
       #
       # Returns self.
       def paths_to_blueprints(*paths_to_blueprints)
-        raise ArgumentError, 'invalid path to blueprints' if paths_to_blueprints == ['']
+        raise ArgumentError, 'invalid path to blueprints' if paths_to_blueprints == [''] || paths_to_blueprints.empty?
 
         @paths_to_blueprints = paths_to_blueprints.join(' ')
         self

data/lib/dredd/rack/version.rb

@@ -1,5 +1,5 @@
 module Dredd
   module Rack
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

data/spec/lib/dredd/rack/runner_spec.rb

@@ -18,6 +18,10 @@ describe Dredd::Rack::Runner do
     expect(subject).to respond_to :command_parts=
   end
 
+  it 'responds to :configure', public: true do
+    expect(subject).to respond_to :configure
+  end
+
   it 'respond_to :paths_to_blueprints', public: true do
     expect(subject).to respond_to :paths_to_blueprints
   end
@@ -48,6 +52,26 @@ describe Dredd::Rack::Runner do
     end
   end
 
+  describe '#api_endpoint', public: true do
+
+    let(:subject) { Dredd::Rack::Runner.new('https://example.com') }
+
+    it 'returns the runner api_endpoint' do
+      expect(subject.api_endpoint).to eq 'https://example.com'
+    end
+
+    context 'when given an argument' do
+
+      it 'returns the runner api_endpoint' do
+        expect(subject.api_endpoint('https://another.example.com')).to eq 'https://another.example.com'
+      end
+
+      it 'sets the runner api_endpoint' do
+        expect(subject.api_endpoint('https://another.example.com')).to eq 'https://another.example.com'
+      end
+    end
+  end
+
   describe '#command_valid?', private: true do
 
     context 'when the generated command has less than two arguments' do
@@ -59,6 +83,24 @@ describe Dredd::Rack::Runner do
     end
   end
 
+  describe '#configure', public: true do
+
+    context 'when the generated command has less than two arguments' do
+
+      it 'executes a configration block in the context of the runner' do
+        allow(subject).to receive_message_chain(:command, :has_at_least_two_arguments?).and_return(false)
+
+        expect(subject).to receive_message_chain(:dry_run!, :color!)
+        expect(subject).to receive(:level).with(:warning)
+
+        subject.configure do |s|
+          s.dry_run!.color!
+          s.level(:warning)
+        end
+      end
+    end
+  end
+
   describe '#initialize', public: true do
 
     context 'with an API endpoint as argument' do
@@ -96,6 +138,7 @@ describe Dredd::Rack::Runner do
       expect(subject.paths_to_blueprints('some/path/*.apib')).to eq subject
     end
 
+
     context 'with one or more paths to blueprints as arguments' do
 
       it 'defines custom paths to blueprints' do
@@ -104,6 +147,13 @@ describe Dredd::Rack::Runner do
       end
     end
 
+    context 'with no arguments' do
+
+      it 'raises ArgumentError' do
+        expect{ subject.paths_to_blueprints() }.to raise_error ArgumentError, 'invalid path to blueprints'
+      end
+    end
+
     context 'with a blank path as argument', public: true do
 
       it 'raises ArgumentError' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dredd-rack
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Gonzalo Bulnes Guilpain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-16 00:00:00.000000000 Z
+date: 2015-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -91,6 +91,8 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- doc/rake_task.md
+- doc/runner.md
 - lib/dredd/rack.rb
 - lib/dredd/rack/configuration.rb
 - lib/dredd/rack/rake_task.rb