goodall 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+test.rb
+api_docs.txt

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm --create use 1.9.3@goodall
+#rvm --create use ree@goodall

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - rbx-18mode
+  - rbx-19mode
+  - 1.8.7
+  - ree
+  - jruby-19mode
+  - jruby-18mode

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in goodall.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Matthew Nielsen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,311 @@
+[![Build Status](https://travis-ci.org/xunker/Goodall.png?branch=master)](https://travis-ci.org/xunker/Goodall)
+# Goodall
+
+Goodall provides an easy interface for documenting your API while you
+write your integration tests.
+
+It is compatible with Rspec, Cucumber and test-unit, as well as others. It
+currently supports JSON and XML APIs, but modules can be easily written to
+handler other types.
+
+Goodall is named after researcher Jane Goodall, who has spent her life observing and
+documenting the behviour of chimpanzees.
+
+## Purpose
+
+Goodall is a gemified version of the ideas in outlined a few years ago in
+this blog post: http://n4k3d.com/blog/2011/08/19/generate-easy-up-to-date-rails-api-docs-with-cucumber/
+
+The basic idea is that you are writing integration tests anyway, you are 90%
+there. All that was left was to record the requests and responses to a text
+file.  For example, the following cucumber test:
+
+```cucumber
+  Feature: /widgets
+    Scenario: Get a list of all widgets
+      Given the following widget exists:
+        | name             | job         |
+        | Billy the Widget | Be a widget |
+        | Sally the Widget | Be a widget |
+      When I GET "/widgets"
+      Then I should get a successful response
+      And the response should include 2 widgets
+      And the response should include the Widget data for "Billy the Widget"
+      And the response should include the Widget data for "Sally the Widget"
+
+    Scenario: Create a new widget
+      Given I have a JSON request for "widget"
+        | name | Bob the Widget |
+        | job  | Be a widget    |
+      And I POST that JSON to "/widgets.json"
+      Then I should get a successful response
+      And the response should include the Widget data for "Bob the Widget"
+```
+
+.. would then generate the following documentation:
+
+```
+  ——————————————————————————–
+  Feature: /widgets
+
+  Scenario: Get a list of all widgets
+  GET /widgets.json
+  RESPONSE:
+  {
+    "widgets" : [
+      {
+        "name" : "Billy the Widget",
+        "job" : "Be a widget"
+      },
+      {
+        "name" : "Sally the Widget",
+        "job" : "Be a widget"
+      }
+    ]
+  }
+
+  Scenario: Create a new widget
+  POST /widgets.json:
+  {
+    "widget" : {
+      "name" : "Bob the Widget",
+      "job" : "Be a widget"
+    }
+  }
+  RESPONSE:
+  {
+    "widget" : {
+      "name" : "Billy the Widget",
+      "job" : "Be a widget"
+    }
+  }
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+  gem 'goodall'
+
+And then execute:
+
+  $ bundle
+
+Or install it yourself as:
+
+  $ gem install goodall
+
+## Usage
+
+### Cucumber
+
+In your *env.rv* file, require 'goodall/cucumber' and either of the JSON
+or XML handlers. Or both, if you need them.
+
+```ruby
+  # env.rb
+  require 'goodall/cucumber'
+  require 'goodall/handler/json' # or/and 'goodall/handler/xml'
+```
+
+In your features, where you want to log a request or response, call either
+*Goodall.document_request* or *Goodall.document_response*.
+
+For cucumber, the best way is to have often-reused methods in each scenario, and then put the Goodall methods call in those. Take this example feature:
+
+```Cucumber
+  # something.feature
+  Given I get "/some/api.json"
+  Then the response should be valid json
+  And the response should should be successful
+
+  # something_steps.rb
+
+  Given /^I get \"(.+)\"$/ do |path|
+    get(path)
+    Goodall.document_request(:get, path)
+  end
+
+  Given /^the response should be valid json$/ do
+    Goodall.document_response(last_response.body)
+    @json_response = MultiJson.load(last_response.body)
+  end
+
+  Given /^the response should be successul$/ do
+    @last_response['success'].should be_true
+  end
+```
+
+The steps "I get (.+)" and "the response should be valid json" are steps I
+will use in almost every scenario, so it is the perfect place for the Goodall
+calls. Using Goodall in these frequently used steps is key for ease-of-use.
+
+_IMPORTANT NOTE_: Using the cucumber helpers, Goodall will NOT log unless
+executed via the rake task "rake cucumber:document". To force Goodall to
+log, please set the environment variable 'ENABLE_GOODALL' to a non-nil
+value. For example:
+
+```
+  ENABLE_GOODALL=true cucumber features/
+```
+
+### Rspec
+
+In your *spec_helper.rb* file, require 'goodall/rspec' and either of the
+JSON or XML handlers. Or both, if you need them.
+
+```ruby
+  # spec_helper.rb
+  require 'goodall/rspec'
+  require 'goodall/handler/json' # or/and 'goodall/handler/xml'
+```
+
+For controller specs, re-use can be acheived by making a delegation method
+for the get/post/put/delete/patch verbs:
+
+```ruby
+  # spec_helper.rb
+
+  def documented_get(*args)
+    Goodall.document_request(:get, args[0])
+    get_response = get(args)
+    Goodall.document_response(response.body)
+    get_response
+  end
+
+  # some_controller_spec.rb
+  describe SomeController do
+    describe "GET foo" do
+      it "should return a body containing 'blah'" do
+
+        documented_get(:foo) # replaces get(:foo)
+        expect(response.body).to include?('blah')
+
+      end
+    end
+  end
+```
+
+_IMPORTANT NOTE_: Using the rspec helpers, Goodall will NOT log unless
+executed via the rake task "rake rspec:document". To force Goodall to
+log, please set the environment variable 'ENABLE_GOODALL' to a non-nil
+value. For example:
+
+```shell
+  ENABLE_GOODALL=true rspec spec/
+```
+
+### Test Unit and derivatives, and others
+
+If you are not using any of the convenience wrappers for rspec or cucumber,
+there is more work to be done when using Goodall.
+
+First, like others, require the files:
+
+```ruby
+  require 'goodall'
+  require 'goodall/handler/json' # or/and 'goodall/handler/xml'
+```  
+
+You will also need to set the path of the file for output. If you choose
+not the set this, the default will be used which is "./api_docs.txt".
+You can override this by:
+
+```ruby
+  Goodall.output_path = "./some/path/file.txt"
+```
+
+Enabing the logging process involves setting the *enabled* property. It is
+disabled by default, which means that Goodall will not document unless
+explicity told to do so. You can enable logging with
+
+```ruby
+  Goodall.enabled = true
+```
+
+### Rake task
+
+To automate the creation of documentation, a rake task can be added that
+automatically set the output file and triggers the tests.
+
+```ruby
+  # Rakefile
+  require 'goodall/rake_task'
+```
+
+This unlocks the following rake commands:
+
+```shell
+  rake cucumber:document   # Run cucumber and write Goodall documentation
+  rake spec:document       # Run rspec tests and write Goodall documentation
+  rake goodall:output_path # Show current Goodall documentation output path
+```
+
+By default, the output path will be 'doc/api_docs.txt' when run with this
+rake task.
+
+## Handlers
+
+By default, Goodall includes handlers for XML and JSON. This means that the
+logged output can be parsed from these formats and pretty-printed correctly
+to the documention file.
+
+If only one handler is required in your config, Goodall assumes you want to
+use that one all the time.  For example:
+
+```ruby
+  require 'goodall'
+  require 'goodall/handler/json'
+
+  Goodall.document_reponse(response.body)
+```
+
+..will assume *response.body* is JSON and will parse it as such. If you were
+to swap "goodall/handler/json" with "goodall/handler/xml" then the response
+would be assumed to be XML.
+
+If you need to use both formats at the same time, you can include both
+handlers and set the actuve handler by name.
+
+```ruby
+  require 'goodall'
+  require 'goodall/handler/json'
+  require 'goodall/handler/xml'
+
+  Goodall.set_handler(:json)
+  Goodall.document_response(response.body) # json response
+
+  Goodall.set_handler(:xml)
+  Goodall.document_response(response.body) # xml response
+```
+
+In the above case, the default handler would be XML since it was required
+last.
+
+### Writing new handlers
+
+Please see *lib/goodall/handler/json.rb* for a good example. A handler will
+need to do two things:
+
+**Implement #parse_payload**: accepts a data structure and is expected to
+return a pretty-printed string representing that data.
+
+**Register itself as a handler**: This is done by calling:
+  
+  ```ruby
+    Goodall.register_handler(:handler_name, self)
+  ```
+..where *:handler_name* is a **symbol** for what type of data is being
+handled, and self is the **class** of the handler.
+
+## Methods
+
+Documented with rdoc.
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+require "rspec/core/version"
+
+task :default => :spec
+
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec, :default) do |t|
+  t.ruby_opts = %w[-w]
+end

data/goodall.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'goodall/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "goodall"
+  spec.version       = Goodall::VERSION
+  spec.authors       = ["Matthew Nielsen"]
+  spec.email         = ["xunker@pyxidis.org"]
+  spec.description   = %q{An easy interface for documenting your API while you
+write your tests.}
+  spec.summary       = %q{Goodall provides an easy interface for documenting your API while you write your tests. It is compatible with Rspec, Cucumber and test-unit, as well as others. Goodall is named after Jane Goodall who has spent her life observing and documenting the behviour of chimpanzees.}
+  spec.homepage      = "http://github.com/xunker/goodall"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "multi_json", ">= 1.6"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", ">= 2.10"
+end

data/lib/goodall.rb

@@ -0,0 +1,142 @@
+require 'singleton'
+require "goodall/version"
+require "goodall/errors"
+require "goodall/writer"
+
+require 'goodall/rake_task' if defined?(Rails)
+
+class Goodall
+  include Singleton
+
+  @@enabled = false                #:nodoc:
+  @@output_path = './api_docs.txt' #:nodoc:
+  @@registered_handlers = {}       #:nodoc:
+  
+  # Get the current documentation output path
+  def self.output_path
+    @@output_path
+  end
+
+  # Set the current documentation output path
+  def self.output_path=(val)
+    @@output_path = val
+  end
+
+  # Is Goodall logging enabled?
+  def self.enabled
+    @@enabled
+  end
+
+  # alias unreliable on class methods, use this instead.
+  def self.enabled?
+    enabled
+  end
+
+  # Explicity set the enabled state, true or false
+  def self.enabled=(val)
+    @@enabled=!!val
+  end
+
+  # Enable Goodall, which is disabled by default.
+  def self.enable
+    self.enabled=true
+  end
+
+  # Enable Goodall, which is the default by default.
+  def self.disable
+    self.enabled = false
+  end
+
+  # write to the currently open output file
+  def self.write(str)
+    writer.write(str) if enabled?
+  end
+
+  # Document a request.
+  #
+  # * +:method+ - a symbol of the verb: :get, :post, :put, :delete, :patch
+  # * +:path+   - a string of the path (URL/URI) of the request
+  # * +:payload+ - the parameters sent, e.g. post body. Usually a hash.
+  def self.document_request(method, path, payload=nil)
+    return unless enabled?
+
+    str = "#{method.to_s.upcase}: #{path}"
+
+    if payload && payload.to_s.size > 0
+      str << "\n" + current_handler.parse_payload(payload)
+    end
+
+    str << "\n"
+  
+    writer.write(str)
+  end
+
+  # Document a response.
+  #
+  # * +:payload - the data returned from the request, e.g. response.body. `payload` will be run through the current handler and be pretty-printed to the output file.
+  def self.document_response(payload)
+    return unless enabled?
+
+    if payload
+      payload = current_handler.parse_payload(payload)
+    end
+
+    str = "RESPONSE:\n#{payload}\n"
+
+    writer.write(str)
+  end
+
+  at_exit do
+    if enabled? && writer
+      writer.close
+    end
+  end
+
+  # When writing a custom hander, it must register itself with Goodall using
+  # this method.
+  #
+  # * +:payload_type+ - The name of the kind of content that this handler will be processing, e.g. JSON, XML, HTML etc.
+  # * +:handler_class+ - The class of the handler itself (not the class name).
+  def self.register_handler(payload_type, handler_class)
+    @@registered_handlers[payload_type.to_sym] = handler_class
+  end
+
+  # Set the currently active handler. By default, if only one handler is
+  # registered then it will be made active by default. If you hanve multiple
+  # handlers registered and wish to switch between them, use this.
+  #
+  # * +:handler_name+ - Handler name as a symbol, e.g. :json, :xml.
+  def self.set_handler(handler_name)
+    handler_name = handler_name.to_sym
+    if handler_class = @@registered_handlers[handler_name]
+      @current_handler = handler_class.new
+    else
+      raise HandlerNotRegisteredError, "No handler registered for for #{handler_name}"
+    end
+  end
+
+  # returns an array of arrays of the currently registered handlers.
+  #
+  # [ [ :identifier, class ], [ :identifier, class ] ]
+  def self.registered_handlers
+    @@registered_handlers.map{|k,v| [k,v]}
+  end
+
+private
+
+  def self.current_handler
+    @current_handler ||= if default_handler = @@registered_handlers.first
+      default_handler[1].new
+    else
+      raise(
+        Goodall::NoHandlersRegisteredError,
+        "There are no handlers registered, please require at least one."
+      )
+    end
+  end
+  
+  def self.writer
+    @writer ||= Goodall::Writer.new(@@output_path)
+  end
+
+end

data/lib/goodall/command_line_enable.rb

@@ -0,0 +1,8 @@
+if (ENV["ENABLE_GOODALL"].to_s.size > 0) && (ENV["ENABLE_GOODALL"].to_s.upcase != 'FALSE')
+  Goodall.enable
+end 
+
+if (ENV["GOODALL_OUTPUT_PATH"].to_s.size > 0)
+  Goodall.output_path = ENV["GOODALL_OUTPUT_PATH"]
+end 
+

data/lib/goodall/cucumber.rb

@@ -0,0 +1,13 @@
+require 'goodall'
+require 'goodall/command_line_enable'
+
+Before do |scenario|
+  if scenario.feature != $current_feature
+    $current_feature = scenario.feature
+    Goodall.write("\n")
+    Goodall.write("#{'-'*80}\nFeature: #{$current_feature.name}")
+  end
+  Goodall.write("\n")
+  Goodall.write("Scenario: #{scenario.name}")
+  Goodall.write("\n")
+end

data/lib/goodall/errors.rb

@@ -0,0 +1,4 @@
+class Goodall
+  class NoHandlersRegisteredError < StandardError; end
+  class HandlerNotRegisteredError < StandardError; end
+end

data/lib/goodall/handler/base.rb

@@ -0,0 +1,9 @@
+class Goodall
+  module Handler
+    class Base
+      def parse_payload(payload_string)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/goodall/handler/json.rb

@@ -0,0 +1,64 @@
+require 'multi_json'
+require "goodall/handler/base"
+
+class Goodall
+  module Handler
+    class Json < Base
+      Goodall.register_handler :json, self
+
+      def parse_payload(payload)
+        payload = if payload.class == String
+          # assue it's a string of json
+          begin
+            MultiJson.load(payload)
+          rescue MultiJson::LoadError
+            # probably not JSON, return as-is
+            return payload+"\n"
+          end
+        else
+          payload
+        end
+  
+        # detect "pretty" json by seeing if there are CRs in here
+        if (json = MultiJson.dump(payload)) =~ /\n/
+          json
+        else
+          pretty_print(json)
+          # json
+        end
+      end
+    
+
+    private
+
+      # We're doing this outselves because it's too unreliable detecting which parsers support pretty-print and whoch one don't. If this method is broken, at least it will be *consitently* broken.
+      def pretty_print(json)
+        return json if json.to_s.size < 1
+
+        str = json.to_s.gsub("},", "},\n").gsub("],", "],\n").gsub("{[", "{\n[").gsub("}]", "}\n]").gsub("[{", "[\n{").gsub("]}", "]\n}").gsub("{\"", "{\n\"").gsub("\"}", "\"\n}").gsub("\",\"", "\",\n\"")
+
+        if str.match(/[^\n]\}$/)
+          str.gsub!(/\}$/, "\n}")
+        end
+
+        output = []
+
+        indent_level = 0
+        str.split("\n").each do |s|
+          indent_level -= 1 if ["]", "}"].include?(s.split('').first) && indent_level > 0
+          output << ("  "*indent_level) + s
+          if ["{", "["].include?(s.split('').last)
+            indent_level += 1 
+            next
+          end
+
+          if ["{", "["].include?(s.split('').first)
+            indent_level += 1 
+            next
+          end
+        end
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/goodall/handler/xml.rb

@@ -0,0 +1,26 @@
+require "goodall/handler/base"
+
+# This sucks.
+# It needs love from someone who knows xml. That's not me.
+
+class Goodall
+  module Handler
+    class Xml < Base
+      Goodall.register_handler :xml, self
+
+      def parse_payload(payload)
+        if payload.class == String
+          # assue it's a string of xml
+          return payload
+        else
+          begin
+            return payload.to_xml
+          rescue Exception => e
+            puts "!!! Just tried to call to_xml on your response, but an error was returned. Your object may not support this."
+            raise e
+          end
+        end
+      end
+    end
+  end
+end

data/lib/goodall/rake_task.rb

@@ -0,0 +1,11 @@
+require 'goodall'
+require 'rails'
+class Goodall
+  class Railtie < Rails::Railtie
+    railtie_name :goodall
+
+    rake_tasks do
+      load "tasks/goodall.rake"
+    end
+  end
+end

data/lib/goodall/rspec.rb

@@ -0,0 +1,2 @@
+require 'goodall'
+require 'goodall/command_line_enable'

data/lib/goodall/version.rb

@@ -0,0 +1,3 @@
+class Goodall
+  VERSION = "0.0.1"
+end

data/lib/goodall/writer.rb

@@ -0,0 +1,15 @@
+class Goodall
+  class Writer
+    def initialize(file_path)
+      @documentation_file = File.new(file_path, "w")
+    end
+
+    def close
+      @documentation_file.close
+    end
+
+    def write(str)
+      @documentation_file.puts str
+    end
+  end
+end

data/lib/tasks/goodall.rake

@@ -0,0 +1,60 @@
+def goodall_installed?
+  begin
+    gem 'goodall'
+  rescue Gem::LoadError
+    false
+  end
+end
+
+def running_under_rails?
+  defined?(Rails)
+end
+
+def goodall_not_installed
+  raise "the Goodall gem is not installed or not enabled. `bundle exec` may fix this."
+end
+
+def goodall_output_path
+  if running_under_rails?
+    "#{Rails.root}/doc/api_docs.txt"
+  else
+    Goodall.output_path
+  end
+end
+
+def set_goodall_putput_path
+  ENV['GOODALL_OUTPUT_PATH'] = goodall_output_path
+end
+
+def enable_goodall
+  ENV['ENABLE_GOODALL'] = 'true'
+end
+
+namespace :cucumber do
+  desc "Run cucumber and write Goodall documentation"
+  goodall_not_installed unless goodall_installed?
+  task :document => :environment do
+    set_goodall_putput_path
+    enable_goodall 
+    Rake::Task["cucumber"].invoke
+  end
+end
+
+namespace :spec do
+  desc "Run rspec tests and write Goodall documentation"
+  goodall_not_installed unless goodall_installed?
+  task :document => :environment do
+    set_goodall_putput_path
+    enable_goodall 
+    Rake::Task["spec"].invoke
+  end
+end
+
+namespace :goodall do
+  desc "Show current Goodall documentation output path"
+  goodall_not_installed unless goodall_installed?
+  task :output_path => :environment do
+    puts "Goodall output path: #{goodall_output_path}"
+  end
+end
+

data/spec/lib/goodall/handler/json_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+require 'goodall'
+require 'goodall/handler/json'
+
+describe Goodall::Handler::Json do
+  describe '#parse_payload' do
+    context 'payload is a string' do
+      context 'string is valid json' do
+
+        let(:valid_json_string) { '{"foo":"bar"}' }
+        
+        it 'should return it as pretty-printed json' do
+          expect(
+            subject.parse_payload(valid_json_string)
+          ).to eq("{\n  \"foo\":\"bar\"\n}")
+        end        
+      end
+      context 'the string not valid json' do
+
+        let(:invalid_json_string) { 'BLAHBLAH' }
+
+        it 'should return the string with CR added' do
+          expect(
+            subject.parse_payload(invalid_json_string)
+          ).to eq("#{invalid_json_string}\n")
+        end
+      end
+    end
+
+    context 'payload is not a string' do
+
+      let(:payload) { { :foo => :bar } }
+
+      it 'should return it as pretty-printed json' do
+        expect(
+            subject.parse_payload(payload)
+          ).to eq("{\n  \"foo\":\"bar\"\n}")
+      end
+    end
+  end
+end

data/spec/lib/goodall_spec.rb

@@ -0,0 +1,209 @@
+require 'spec_helper'
+require 'goodall'
+
+describe Goodall do
+  let(:klass) { Goodall }
+
+  let(:mock_writer) { double(:writer, :close => nil) }
+
+  let(:mock_handler) { double(:mock_handler) }
+
+  let(:mock_new_handler) { double(:mock_new_handler) }
+
+  before(:each) do
+    Goodall.stub(:writer).and_return(mock_writer)
+  end
+
+  after(:each) do
+    Goodall.disable
+  end
+
+  describe ".output_path" do
+    it "must return the current output file path" do
+       # default
+      expect(klass.output_path).to eq('./api_docs.txt')
+
+      # setting
+      klass.output_path = 'foo/bar.txt'
+      expect(klass.output_path).to eq('foo/bar.txt')
+    end
+  end
+
+  describe ".enabled" do
+    it "must be true if goodall is enabled" do
+      klass.enable
+
+      expect(klass.enabled).to be_true
+    end
+    it "must be false if goodall is not enabled" do
+      klass.disable
+
+      expect(klass.enabled).to be_false
+    end
+  end
+
+  describe ".write" do
+    context "Goodall is enabled" do
+      before(:each) { klass.enable; }
+      it "must deleage to the writer" do
+        expect(mock_writer).to receive(:write).with('string')
+      
+        Goodall.write('string')
+      end
+    end
+
+    context "Goodall is not enabled" do
+      before(:each) { klass.disable }
+      it "must silently return and not touch the writer" do
+        expect(mock_writer).not_to receive(:write)
+
+        Goodall.write('string')
+      end
+    end
+  end
+
+  describe ".document_request" do
+    context "Goodall is enabled" do
+
+      context "post with payload" do
+
+        let(:mock_payload) { '{ "foo" : "bar" }' }
+
+        let(:formatted_payload) do
+          "{\n  \"foo\" : \"bar\"\n}\n"
+        end
+
+        before(:each) do
+          klass.enable
+
+          mock_handler.stub(
+            :parse_payload
+          ).with(
+            mock_payload
+          ).and_return(
+            formatted_payload
+          )
+
+          klass.stub(:current_handler).and_return(mock_handler)
+          klass.stub(:writer).and_return(mock_writer)
+        end
+
+        let(:expected_write) do
+          "POST: /foo/bar\n#{formatted_payload}\n"
+        end
+
+        it "must send a formatted response to the writer" do
+          expect(mock_writer).to receive(:write).with(expected_write)
+
+          klass.document_request(:post, '/foo/bar', mock_payload)
+        end
+      end
+
+      context "get without payload" do
+        before(:each) do
+          klass.enable
+        end
+
+        let(:expected_write) do
+          "GET: /foo/bar\n"
+        end
+
+        it "must send a formatted request to the writer" do
+          expect(mock_writer).to receive(:write).with(expected_write)
+
+          klass.document_request(:get, '/foo/bar')
+        end
+      end
+
+    end
+
+    context "Goodall is not enabled" do
+      before(:each) { klass.disable }
+      it "must silently return without writing" do
+        mock_writer.should_not_receive(:write)
+
+        klass.document_request(:foo, 'bar', { :baz => :baz })
+      end
+    end
+  end
+
+  describe ".document_response" do
+    context "Goodall is enabled" do
+
+      let(:mock_payload) { '{ "foo" : "bar" }' }
+
+      let(:formatted_payload) do
+        "{\n  \"foo\" : \"bar\"\n}\n"
+      end
+
+      before(:each) do
+        klass.enable
+
+        mock_handler.stub(
+          :parse_payload
+        ).with(
+          mock_payload
+        ).and_return(
+          formatted_payload
+        )
+
+        klass.stub(:current_handler).and_return(mock_handler)
+        klass.stub(:writer).and_return(mock_writer)
+      end
+
+      let(:expected_write) do
+        "RESPONSE:\n#{formatted_payload}\n"
+      end
+
+      it "must send a formatted response to the writer" do
+        expect(mock_writer).to receive(:write).with(expected_write)
+
+        klass.document_response(mock_payload)
+      end
+    end
+
+    context "Goodall is not enabled" do
+      before(:each) { klass.disable }
+      it "must silently return without writing" do
+        mock_writer.should_not_receive(:write)
+
+        klass.document_response({ :baz => :baz })
+      end
+    end
+  end
+
+  describe ".register_handler" do
+    it "should add a handler class to the list of registered handlers" do
+      klass.register_handler(:foo_register_test, mock_new_handler)
+
+      expect(klass.registered_handlers).to include([:foo_register_test, mock_new_handler])
+    end
+  end
+
+  describe ".set_handler" do
+    context "handler is registered" do
+      it "should set that handler as the current active handler" do
+        foo_handler_instance = double(:foo_handler_instance)
+        foo_handler_class = double(:foo_handler_class, :new => foo_handler_instance)
+        bar_handler_instance = double(:bar_handler_instance)
+        bar_handler_class = double(:bar_handler_class, :new => bar_handler_instance)
+        
+        klass.register_handler(:foo, foo_handler_class)
+        klass.register_handler(:bar, bar_handler_class)
+
+        klass.set_handler(:foo)
+        expect(klass.send(:current_handler)).to eq(foo_handler_instance)
+
+        klass.set_handler(:bar)
+        expect(klass.send(:current_handler)).to eq(bar_handler_instance)
+      end
+    end
+    context "handler is not registered" do
+      it "should raise HandlerNotRegisteredError" do
+        expect{
+          klass.set_handler(:invalid)
+        }.to raise_error(Goodall::HandlerNotRegisteredError)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification 
+name: goodall
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Matthew Nielsen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-08-30 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: multi_json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 1
+        - 6
+        version: "1.6"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 1
+        - 3
+        version: "1.3"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 10
+        version: "2.10"
+  type: :development
+  version_requirements: *id004
+description: |-
+  An easy interface for documenting your API while you
+  write your tests.
+email: 
+- xunker@pyxidis.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- .rvmrc
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- goodall.gemspec
+- lib/goodall.rb
+- lib/goodall/command_line_enable.rb
+- lib/goodall/cucumber.rb
+- lib/goodall/errors.rb
+- lib/goodall/handler/base.rb
+- lib/goodall/handler/json.rb
+- lib/goodall/handler/xml.rb
+- lib/goodall/rake_task.rb
+- lib/goodall/rspec.rb
+- lib/goodall/version.rb
+- lib/goodall/writer.rb
+- lib/tasks/goodall.rake
+- spec/lib/goodall/handler/json_spec.rb
+- spec/lib/goodall_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/xunker/goodall
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Goodall provides an easy interface for documenting your API while you write your tests. It is compatible with Rspec, Cucumber and test-unit, as well as others. Goodall is named after Jane Goodall who has spent her life observing and documenting the behviour of chimpanzees.
+test_files: 
+- spec/lib/goodall/handler/json_spec.rb
+- spec/lib/goodall_spec.rb
+- spec/spec_helper.rb