approvals 0.0.1

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.received.txt
+.approvals
+tmp/

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in rspec-approvals.gemspec
+gemspec

data/License.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2011 Katrina Owen
+
+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,133 @@
+# Approvals
+
+Approvals are based on the idea of the *_golden master_*.
+
+You take a snapshot of an object, and then compare all future
+versions of the object to the snapshot.
+
+Big hat tip to Llewellyn Falco who developed the approvals concept, as
+well as the original approvals libraries (.NET, Java, Ruby, PHP,
+probably others).
+
+See [ApprovalTests](http://www.approvaltests.com) for videos and additional documentation about the general concept.
+
+Also, check out  Herding Code's [podcast #117](http://t.co/GLn88R5) in
+which Llewellyn Falco is interviewed about approvals.
+
+[![Build Status](https://secure.travis-ci.org/kytrinyx/rspec-approvals.png?branch=master)](http://travis-ci.org/kytrinyx/rspec-approvals)
+
+## Configuration
+
+    Approvals.configure do |c|
+      c.approvals_path = 'output/goes/here/'
+    end
+
+The default location for the output files is
+
+    approvals/
+
+## Usage
+
+    Approvals.verify(your_subject, :format => :json)
+
+This will raise an `ApprovalError` in the case of a failure.
+
+The `:inspect` method on the subject will be used to generate the output for
+the `received` file. For custom complex objects you will need to override
+`:to_s` or `:inspect` to get helpful output, rather than the default:
+
+    #<Object:0x0000010105ea40> # or whatever the object id is
+
+Note: `:inspect` uses `:to_s` unless it has been specifically defined to do something else.
+
+The first time the approval is run, a file will be created with the contents of the subject of your approval:
+
+    the_name_of_the_approval.received.txt # or .json, .html, .xml as appropriate
+
+Since you have not yet approved anything, the `*.approved` file does not exist, and the comparison will fail.
+
+### RSpec
+
+For the moment the only direct integration is with RSpec.
+
+The default directory for output files when using RSpec is
+
+    spec/fixtures/approvals/
+
+You can override this:
+
+    RSpec.configure do |c|
+      c.approvals_path = 'some/other/path'
+    end
+
+The basic format of the approval is modeled after RSpec's `it`:
+
+    verify "something" do
+      "this is the the thing you want to verify"
+    end
+
+### Naming
+
+Currently there is only an RSpecNamer that takes an example (or any object that responds to `:full_description`).
+
+    namer = Approvals::Namers::RSpecNamer.new(example)
+
+    Approvals.verify(thing, :namer => namer, :format => :html)
+
+When using RSpec, the namer is set for you.
+
+### Formatting
+
+You can pass a format for your output before it gets written to the file.
+At the moment, only xml, html, and json are supported.
+
+Simply add a `:format => :xml`, `:format => :html`, or `:format => :json` option to the example:
+
+    verify "some html", :format => :html do
+      "<html><head></head><body><h1>ZOMG</h1></body></html>"
+    end
+
+    verify "some json", :format => :json do
+      "{\"beverage\":\"coffee\"}"
+    end
+
+### Approving a spec
+
+If the contents of the received file is to your liking, you can approve
+the file by renaming it.
+
+For an example who's full description is `My Spec`:
+
+    mv my_spec.received.txt my_spec.approved.txt
+
+When you rerun the approval, it should now pass.
+
+### Expensive computations
+
+The Executable class allows you to perform expensive operations only when the command to execute it changes.
+
+For example, if you have a SQL query that is very slow, you can create an executable with the actual SQL to be performed.
+
+The first time the spec runs, it will fail, allowing you to inspect the results.
+If this output looks right, approve the query. The next time the spec is run, it will compare only the actual SQL.
+
+If someone changes the query, then the comparison will fail. Both the previously approved command and the received command will be executed so that you can inspect the difference between the results of the two.
+
+    executable = Approvals::Executable.new(subject.slow_sql) do |output|
+        # do something on failure
+    end
+
+    Approvals.verify(executable, :options => :here)
+
+### RSpec executable
+
+There is a convenience wrapper for RSpec that looks like so:
+
+    verify "an executable" do
+      executable(subject.slow_sql) do |command|
+         result = ActiveRecord::Base.connection.execute(command)
+         # do something to display the result
+      end
+    end
+
+Copyright (c) 2011 Katrina Owen, released under the MIT license

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/TODO

@@ -0,0 +1,2 @@
+[ ] add default namer
+    Approvals.verify(something, :name => 'the name of this test')

data/approvals.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "approvals"
+  s.version     = "0.0.1"
+  s.authors     = ["Katrina Owen"]
+  s.email       = ["katrina.owen@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Approval Tests for Ruby}
+  s.description = %q{Approval Tests for Ruby}
+
+  s.rubyforge_project = "approvals"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'rspec', '~> 2.7'
+  s.add_dependency 'thor'
+  s.add_dependency 'nokogiri'
+end

data/bin/approvals

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'thor'
+require 'approvals'
+require 'approvals/utilities/cli'
+
+Approvals::CLI.start
+

data/lib/approvals.rb

@@ -0,0 +1,24 @@
+require 'nokogiri'
+require 'approvals/configuration'
+require 'approvals/approval'
+require 'approvals/dsl'
+require 'approvals/error'
+require 'approvals/utilities'
+require 'approvals/reporters'
+require 'approvals/writer'
+require 'approvals/namers/default_namer'
+
+require 'approvals/extensions/rspec'
+
+
+module Approvals
+  extend DSL
+
+  class << self
+    def reset
+      Dotfile.reset
+    end
+  end
+end
+
+Approvals.reset

data/lib/approvals/approval.rb

@@ -0,0 +1,97 @@
+module Approvals
+  class Approval
+    class << self
+      attr_accessor :namer
+    end
+
+    attr_reader :subject, :namer, :failure
+    def initialize(subject, options = {})
+      @subject = subject
+      @namer = options[:namer] || default_namer(options[:name])
+      @format = options[:format] || identify_format
+    end
+
+    def default_namer(name)
+      Namers::DefaultNamer.new(name)
+    end
+
+    def identify_format
+      return :hash if subject.respond_to? :each_pair
+      return :array if subject.respond_to? :each_with_index
+      return :txt
+    end
+
+    def writer
+      @writer ||= Writer.for(@format)
+    end
+
+    def verify
+      unless File.exists?(namer.output_dir)
+        FileUtils.mkdir_p(namer.output_dir)
+      end
+
+      writer.write(subject, received_path)
+
+      unless approved?
+        fail_with "Approval file \"#{approved_path}\" not found."
+      end
+
+      unless received_matches?
+        fail_with "Received file \"#{received_path}\" does not match approved \"#{approved_path}\"."
+      end
+
+      success!
+    end
+
+    def success!
+      File.delete received_path
+    end
+
+    def approved?
+      File.exists? approved_path
+    end
+
+    def received_matches?
+      FileUtils.cmp received_path, approved_path
+    end
+
+    def fail_with(message)
+      if subject.respond_to?(:on_failure)
+        subject.on_failure.call(approved_text) if approved?
+        subject.on_failure.call(received_text)
+      end
+
+      Dotfile.append(diff_path)
+
+      raise ApprovalError.new("Approval Error: #{message}")
+    end
+
+    def diff_path
+      "#{received_path} #{approved_path}"
+    end
+
+    def full_path(state)
+      "#{namer.output_dir}#{namer.name}.#{state}.#{writer.extension}"
+    end
+
+    def name
+      namer.name
+    end
+
+    def approved_path
+      full_path('approved')
+    end
+
+    def received_path
+      full_path('received')
+    end
+
+    def approved_text
+      File.read approved_path
+    end
+
+    def received_text
+      File.read received_path
+    end
+  end
+end

data/lib/approvals/configuration.rb

@@ -0,0 +1,24 @@
+require 'singleton'
+
+module Approvals
+
+  class << self
+    def configure(&block)
+      block.call Approvals::Configuration.instance
+    end
+
+    def configuration
+      Approvals::Configuration.instance
+    end
+  end
+
+  class Configuration
+    include Singleton
+
+    attr_writer :approvals_path
+
+    def approvals_path
+      @approvals_path ||= 'approvals/'
+    end
+  end
+end

data/lib/approvals/dsl.rb

@@ -0,0 +1,7 @@
+module Approvals
+  module DSL
+    def verify(object, options = {})
+      Approval.new(object, options).verify
+    end
+  end
+end

data/lib/approvals/error.rb

@@ -0,0 +1,5 @@
+module Approvals
+  class ApprovalError < Exception
+    attr_accessor :received_path, :approved_path
+  end
+end

data/lib/approvals/extensions/rspec.rb

@@ -0,0 +1,11 @@
+if defined? RSpec
+  require 'approvals/extensions/rspec/dsl'
+  require 'approvals/extensions/rspec/example_group'
+  require 'approvals/extensions/rspec/example'
+  require 'approvals/namers/rspec_namer'
+
+  RSpec.configure do |c|
+    c.extend Approvals::RSpec::DSL
+    c.add_setting :approvals_path, :default => 'spec/fixtures/approvals/'
+  end
+end

data/lib/approvals/extensions/rspec/dsl.rb

@@ -0,0 +1,9 @@
+module Approvals
+  module RSpec
+    module DSL
+      def executable(command, &block)
+        Approvals::Executable.new(command, &block)
+      end
+    end
+  end
+end

data/lib/approvals/extensions/rspec/example.rb

@@ -0,0 +1,17 @@
+module Approvals
+  module RSpec
+    class Example < ::RSpec::Core::Example
+
+      attr_reader :received
+      def initialize(example_group, description, options, &block)
+        super(example_group, description, options, block)
+
+        namer = Approvals::Namers::RSpecNamer.new(self)
+        approval = Approval.new(@example_block.call, options.merge(:namer => namer))
+        @example_block = Proc.new { approval.verify }
+      end
+    end
+  end
+end
+
+

data/lib/approvals/extensions/rspec/example_group.rb

@@ -0,0 +1,15 @@
+module Approvals
+  module RSpec
+    module ExampleGroup
+
+      def verify(desc=nil, *args, &block)
+        options = build_metadata_hash_from(args)
+        examples << Approvals::RSpec::Example.new(self, desc, options, &block)
+        examples.last
+      end
+
+    end
+  end
+end
+
+RSpec::Core::ExampleGroup.send(:extend, Approvals::RSpec::ExampleGroup)