dredd-rack 0.3.0

data/README.md

@@ -0,0 +1,102 @@
+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)
+[![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.
+
+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.
+
+  [dredd]: https://github.com/apiaryio/dredd
+  [blueprint]: https://apiblueprint.org/
+  [rspec-book]: https://pragprog.com/book/achbd/the-rspec-book
+  [apiary]: http://apiary.io
+
+Installation
+------------
+
+Add the gem to your `Gemfile`:
+
+```ruby
+# Gemfile
+
+gem 'dredd-rack', '~> 1.0' # see semver.org
+```
+
+Getting Started
+---------------
+
+### Dredd::Rack::Runner
+
+_To do._
+
+
+### Rake task
+
+Use the `dredd` rake task from 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!
+
+# Optionally add the API blueprint verification to the default test suite
+# task :default => [:spec, :dredd]
+```
+
+Run the API blueprint verification locally:
+
+```bash
+rake dredd
+
+# or specify a remote server:
+#API_HOST=http://api.example.com rake blueprint:verify
+```
+
+Usage
+-----
+
+### Custom rake task name or description
+
+You can also define a custom rake task name or description:
+
+```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)
+end
+```
+
+License
+-------
+
+    Dredd::Rack provides convenient API blueprint testing to Rack applications.
+    Copyright (C) 2015  Gonzalo Bulnes Guilpain
+
+    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
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,41 @@
+begin
+  require 'inch/rake'
+
+  Inch::Rake::Suggest.new(:inch) do |suggest|
+    suggest.args << "--private"
+    suggest.args << "--pedantic"
+  end
+rescue LoadError
+  desc 'Inch rake task not available'
+  task :inch do
+  abort 'Inch rake task is not available. Be sure to install inch as a gem or plugin'
+  end
+end
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc 'Provide private interfaces documentation'
+  RSpec::Core::RakeTask.new(:spec)
+
+  namespace :spec do
+    desc 'Provide public interfaces documentation'
+      RSpec::Core::RakeTask.new(:public) do |t|
+      t.rspec_opts = "--tag public"
+    end
+  end
+
+  namespace :spec do
+    desc 'Provide private interfaces documentation for development purpose'
+      RSpec::Core::RakeTask.new(:development) do |t|
+      t.rspec_opts = "--tag protected --tag private"
+    end
+  end
+rescue LoadError
+  desc 'RSpec rake task not available'
+  task :spec do
+    abort 'RSpec rake task is not available. Be sure to install rspec-core as a gem or plugin'
+  end
+end
+
+task :default => ['spec:public', 'spec:development', :inch]

data/lib/dredd/rack.rb

@@ -0,0 +1,10 @@
+require 'dredd/rack/configuration'
+require 'dredd/rack/rake_task'
+require 'dredd/rack/runner'
+require 'dredd/rack/version'
+
+module Dredd
+  module Rack
+    extend Configuration
+  end
+end

data/lib/dredd/rack/configuration.rb

@@ -0,0 +1,27 @@
+module Dredd
+  module Rack
+
+    # Hold the Dredd::Rack global configuration.
+    module Configuration
+
+      # Return the application to be tested locally
+      def app
+        @@app
+      end
+
+      # Set the application to be tested locally
+      #
+      # Any Dredd::Rack::Runner configured to run locally will serve
+      # this application from a Capybara::Server instance.
+      #
+      # object - the application Constant
+      def app=(object)
+        @@app = object
+      end
+
+      # Default configuration
+      @@app = nil
+
+    end
+  end
+end

data/lib/dredd/rack/rake_task.rb

@@ -0,0 +1,111 @@
+require 'capybara'
+require 'rainbow'
+require 'rake'
+require 'rake/tasklib'
+
+module Dredd
+  module Rack
+
+    # A clonable Rake task powered by a Dredd::Rack::Runner
+    #
+    # Examples:
+    #
+    #    require 'dredd/rack'
+    #    Dredd::Rack::RakeTask.new # run it with `rake dredd`
+    #
+    #    # Customize the name or description of the Rake task:
+    #    namespace :blueprint do
+    #      desc 'Verify an API complies with its blueprint'
+    #      Dredd::Rack::RakeTask.new(:verify)
+    #    end
+    #    # run it with `rake blueprint:verify`
+    #
+    class RakeTask < ::Rake::TaskLib
+
+      # Return the task's name
+      attr_reader :name
+
+      # Return the task's description
+      attr_reader :description
+
+      # Return the Dredd::Rack::Runner instance
+      attr_reader :runner
+
+      # Define a task with a custom name, arguments and description
+      def initialize(*args)
+        @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
+          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?
+          `which dredd`
+          $?.exitstatus == 0
+        end
+
+        def dredd_connection_error?(exit_status)
+          exit_status == 8
+        end
+
+        def command_message(runner)
+          <<-eos.gsub /^( |\t)+/, ""
+            #{runner.command}
+
+          eos
+        end
+
+        def connection_error_message(runner)
+          <<-eos.gsub /^( |\t)+/, ""
+
+            #{Rainbow("Something went wrong.").red}
+            Maybe your API is not being served at #{runner.api_endpoint}?
+
+            Note that specifying a different host is easy:
+            #{Rainbow('`rake blueprint:verify API_HOST=http://localhost:4567`').yellow}
+
+          eos
+        end
+
+        def dredd_not_available_message
+          <<-eos.gsub /^( |\t)+/, ""
+
+            The #{Rainbow('dredd').red} blueprint testing tool is not available.
+            You may want to install it in order to validate the API blueprints.
+
+            Try #{Rainbow('`npm install dredd --global`').yellow} (use `sudo` if necessary)
+            or see https://github.com/apiaryio/dredd for instructions.
+
+          eos
+        end
+
+        def starting_message
+          <<-eos.gsub /^( |\t)+/, ""
+
+            #{Rainbow('Verify the API conformance against its blueprint.').blue}
+          eos
+        end
+    end
+  end
+end

data/lib/dredd/rack/runner.rb

@@ -0,0 +1,166 @@
+require 'capybara'
+
+module Dredd
+  module Rack
+
+    # A Ruby wrapper around the Dredd API blueprint validation tool
+    #
+    # Usage:
+    #
+    #    # run `dredd doc/*.apib doc/*.apib.md http://localhost:XXXX --level warning --dry-run`
+    #    # You don't need to start any server, Dredd::Rack does it for you.
+    #    dredd = Dredd::Rack::Runner.new
+    #    dredd.level(:warning).dry_run!.run
+    #
+    #    # You can specify an API endpoint to perform a remote validation.
+    #    # Do not forget to serve the API at the given URL!
+    #    #
+    #    # runs `dredd blueprints/*.md doc/*.md https://api.example.com --no-color`
+    #    anderson = Anderson::Rack::Runner.new 'https://api.example.com' do |options|
+    #      options.paths_to_blueprints 'blueprints/*.md', 'doc/*.md'
+    #      options.no_color!
+    #    end
+    #    anderson.run
+    #
+    class Runner
+
+      undef_method :method
+
+      NEGATABLE_BOOLEAN_OPTIONS = [:dry_run!, :names!, :sorted!, :inline_errors!,
+                                   :details!, :color!, :timestamp!, :silent!]
+      META_OPTIONS              = [:help, :version]
+      BOOLEAN_OPTIONS           = NEGATABLE_BOOLEAN_OPTIONS + META_OPTIONS
+
+      SINGLE_ARGUMENT_OPTIONS   = [:hookfiles, :only, :reporter, :output, :header,
+                                   :user, :method, :level, :path]
+      OPTIONS                   = BOOLEAN_OPTIONS + SINGLE_ARGUMENT_OPTIONS
+
+      # 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.
+      #
+      # api_endpoint - the API URL as a String
+      #
+      def initialize(api_endpoint=nil)
+        @dredd_command = 'dredd'
+        @paths_to_blueprints = 'doc/*.apib doc/*.apib.md'
+        @api_endpoint = api_endpoint || ''
+        @command_parts = []
+
+        yield self if block_given?
+      end
+
+      # Return the Dredd command line
+      def command
+        ([@dredd_command, @paths_to_blueprints, @api_endpoint] + @command_parts).join(' ')
+      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 == ['']
+
+        @paths_to_blueprints = paths_to_blueprints.join(' ')
+        self
+      end
+
+      # Run Dredd
+      #
+      # Returns true if the Dredd exit status is zero, false instead.
+      def run
+
+        if command_valid?
+          start_server! unless api_remote?
+          Kernel.system(command)
+        end
+      end
+
+      # Ensure that the runner does respond_to? its option methods
+      #
+      # See http://ruby-doc.org/core-2.2.0/Object.html#method-i-respond_to_missing-3F
+      def respond_to_missing?(method, include_private=false)
+        OPTIONS.include?(method.to_sym ) ||
+        NEGATABLE_BOOLEAN_OPTIONS.include?(method.to_s.gsub(/\Ano_/, '').to_sym) ||
+        super
+      end
+
+      private
+
+        def api_remote?
+          !@api_endpoint.empty?
+        end
+
+        def command_valid?
+          command.has_at_least_two_arguments?
+        end
+
+        def start_server!
+          server = Capybara::Server.new(Dredd::Rack.app)
+          server.boot
+          @api_endpoint = "http://#{server.host}:#{server.port.to_s}"
+        end
+
+        # Private: Define as many setter methods as there are Dredd options
+        #
+        # The behaviour of Object#method_missing is not modified unless
+        # the called method name matches one of the Dredd options.
+        #
+        # name - Symbol for the method called
+        # args - arguments of the called method
+        #
+        # See also: http://ruby-doc.org/core-2.2.0/BasicObject.html#method-i-method_missing
+        def method_missing(name, *args)
+          super unless OPTIONS.include?(name.to_sym ) ||
+                       NEGATABLE_BOOLEAN_OPTIONS.include?(name.to_s.gsub(/\Ano_/, '').to_sym)
+
+          option_flag = name.to_s.gsub('_', '-').gsub('!', '').prepend('--')
+          command_parts = self.command_parts.push option_flag
+          command_parts = self.command_parts.push args.slice(0).to_s if SINGLE_ARGUMENT_OPTIONS.include? name
+          self
+        end
+
+    end
+  end
+end
+
+class String
+
+  # Verify that a command has at least two arguments (excluding options)
+  #
+  # Examples:
+  #
+  #    "dredd doc/*.apib http://api.example.com".valid? # => true
+  #    "dredd doc/*.apib doc/*apib.md http://api.example.com".valid? # => true
+  #    "dredd doc/*.apib http://api.example.com --level verbose".valid? # => true
+  #    "dredd http://api.example.com".valid? # => false
+  #    "dredd doc/*.apib --dry-run".valid? # => false
+  #    "dredd --dry-run --level verbose".valid? # => false
+  #
+  # Known limitations:
+  #
+  # Does not support short flags. (e.g. using `-l` instead of `--level`).
+  # Requires options to be specified after the last argument.
+  #
+  # Note:
+  #
+  # The known limitations imply that there may be false negatives: this method
+  # can return false for commands that do have two arguments or more. But there
+  # should not be false positives: if the method returns true, then the command
+  # does have at least two arguments.
+  #
+  # Returns true if the command String has at least two arguments, false otherwise.
+  def has_at_least_two_arguments?
+    split('--').first.split(' ').length >= 3
+  end
+end
+
+Anderson = Dredd # Anderson::Rack::Runner.new runs just as fast as Dredd