rspec-approvals 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

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,81 @@
+# RSpec 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.
+
+See [ApprovalTests](http://www.approvaltests.com) for videos and additional documentation about the general concept.
+
+The original Approvals libraries for Java and C# were developed by Llewellyn Falco.
+
+
+## Configuration
+
+The default location for the output files is
+
+    spec/approvals
+
+You can change this using the configuration option
+
+    RSpec.configure do |c|
+      c.approvals_path = 'some/other/path'
+    end
+
+
+## Usage
+
+The basic format of the approval is modeled after RSpec's `it`:
+
+    approve "something" do
+      "this is the received contents"
+    end
+
+
+The `:to_s` method on the object will be used to generate the output for
+the `*.received.txt` file. For custom objects you will need to override
+the `:to_s` to get helpful output, rather than the default:
+
+    #<Object:0x0000010105ea40>
+
+The first time the specs are run, two files will be created:
+
+    full_description_of_something.received.txt
+    full_description_of_something.approved.txt
+
+
+Since you have not yet approved anything, the `*.approved.txt` file is
+empty.
+
+The contents of the two files are compared, and the approval will fail at this point.
+
+### Approving a spec
+
+If the contents of the received file is to your liking, you can approve
+the file by overwriting the approved file with the received file.
+
+For an example who's full description is `My Spec`:
+
+    mv my_spec.received.txt my_spec.approved.txt
+
+When you rerun the spec, it should now pass.
+
+### Formatters
+
+You can specify a custom formatter when you run the specs.
+
+E.g.
+
+    rspec --require /path/to/lib/rspec/approvals/formatters/opendiff_formatter.rb \
+    -f RSpec::Approvals::Formatters::OpendiffFormatter spec/
+
+The OpendiffFormatter automatically launches opendiff for each failed
+approval. It falls back on the ProgressFormatter for all non-approval
+specs.
+
+That's pretty unweildy, so I'm looking at options to add shortcuts for
+this.
+
+
+
+Copyright (c) 2011 Katrina Owen, released under the MIT license

data/Rakefile

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

data/lib/rspec/approvals/approval.rb

@@ -0,0 +1,80 @@
+require 'rspec/expectations/errors'
+
+module RSpec
+  module Approvals
+
+    class ReceivedDiffersError < RSpec::Expectations::ExpectationNotMetError; end
+
+    class Approval
+
+      def self.normalize(s)
+        s.gsub(/[\W]/, ' ').strip.squeeze(" ").gsub(' ', '_').downcase
+      end
+
+      def self.base_path(s)
+        Approvals.path + normalize(s)
+      end
+
+      attr_reader :location
+
+      def initialize(example, received = '')
+        @path = Approval.base_path(example.full_description)
+
+        example.options[:approval] = true
+        example.options[:approval_diff_paths] = {
+          :received => received_path,
+          :approved => approved_path,
+        }
+
+        write(:approved, '') unless File.exists?(approved_path)
+        write(:received, received)
+      end
+
+      def approved_path
+        "#{@path}.approved.txt"
+      end
+
+      def received_path
+        "#{@path}.received.txt"
+      end
+
+      def write(suffix, contents)
+        File.open("#{@path}.#{suffix}.txt", 'w') do |f|
+          f.write contents
+        end
+      end
+
+      def failure_message
+        <<-FAILURE_MESSAGE
+
+        Approval Failure:
+
+        The received contents did not match the approved contents.
+
+        Inspect the differences in the following files:
+        #{received_path}
+        #{approved_path}
+
+        If you like what you see in the *.received.txt file, you can approve it
+        like so:
+
+        mv #{received_path} #{approved_path}
+
+
+        FAILURE_MESSAGE
+      end
+
+      def location=(backtrace)
+        @location = [backtrace.first.gsub(Dir.pwd, '.')]
+      end
+
+      def verify
+        if FileUtils.cmp(received_path, approved_path)
+          File.unlink(received_path)
+        else
+          raise RSpec::Approvals::ReceivedDiffersError, failure_message, location
+        end
+      end
+    end
+  end
+end

data/lib/rspec/approvals/dsl.rb

@@ -0,0 +1,23 @@
+require 'rspec/expectations/errors'
+
+module RSpec
+  module Approvals
+    module DSL
+
+      def approve(description)
+
+        specify(description) do
+          approval = Approval.new(example, yield)
+
+          # We may be able to set file_path and
+          # line_number on example in the approval
+          # see RSpec::Core::Metadata::LocationKeys
+          approval.location = caller
+
+          approval.verify
+        end
+      end
+
+    end
+  end
+end

data/lib/rspec/approvals/formatters/opendiff_formatter.rb

@@ -0,0 +1,22 @@
+require 'rspec/core/formatters/progress_formatter'
+
+module RSpec
+  module Approvals
+    module Formatters
+
+      class OpendiffFormatter < RSpec::Core::Formatters::ProgressFormatter
+        def dump_failures
+          super
+          failed_examples.each do |example|
+            if example.options[:approval]
+              paths = example.options[:approval_diff_paths]
+              system("opendiff #{paths[:received]} #{paths[:approved]} &")
+            end
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/rspec/approvals/version.rb

@@ -0,0 +1,5 @@
+module RSpec
+  module Approvals
+    VERSION = "0.0.1"
+  end
+end

data/lib/rspec/approvals.rb

@@ -0,0 +1,30 @@
+
+require "rspec/approvals/version"
+require "rspec/approvals/approval"
+require "rspec/approvals/dsl"
+require 'rspec/approvals/formatters/opendiff_formatter'
+
+
+module RSpec
+  RSpec.configure do |c|
+    c.extend RSpec::Approvals::DSL
+    c.add_setting :approvals_path, :default => 'spec/approvals'
+  end
+
+  module Approvals
+
+    class << self
+      def initialize_approvals_path
+        FileUtils.makedirs(RSpec.configuration.approvals_path) unless Dir.exists?(RSpec.configuration.approvals_path)
+      end
+
+      def path
+        RSpec.configuration.approvals_path + "/"
+      end
+    end
+
+  end
+
+end
+
+RSpec::Approvals.initialize_approvals_path

data/rspec-approvals.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rspec/approvals/version"
+
+Gem::Specification.new do |s|
+  s.name        = "rspec-approvals"
+  s.version     = RSpec::Approvals::VERSION
+  s.authors     = ["Katrina Owen"]
+  s.email       = ["katrina.owen@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Approval Tests for Ruby}
+  s.description = %q{An RSpec extension that adds support for approvals. Based on the idea of the Golden Master.}
+
+  s.rubyforge_project = "rspec-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.6'
+end

data/spec/approval_spec.rb

@@ -0,0 +1,157 @@
+require 'spec_helper'
+
+describe Approvals::Approval do
+  let(:description) { 'spec/approvals/fairy_dust_and_unicorns' }
+  let(:example) { stub('example', :full_description => 'fairy dust and unicorns').as_null_object }
+
+  describe "#normalize" do
+    it "downcases" do
+      Approvals::Approval.normalize("KTHXBYE").should eq("kthxbye")
+    end
+
+    it "replaces spaces with underscores" do
+      Approvals::Approval.normalize("the spec").should eq("the_spec")
+    end
+
+    it "leaves numbers alone" do
+      Approvals::Approval.normalize('a 2009 party').should eq("a_2009_party")
+    end
+
+    it "deletes funky characters" do
+      Approvals::Approval.normalize('the !@\#$%^&*(){}+| name').should eq("the_name")
+    end
+
+    it "collapses spaces before replacing with underscores" do
+      Approvals::Approval.normalize('omf             g').should eq('omf_g')
+    end
+
+    it "deletes all sorts of spaces" do
+      name = <<-FUNKY_NAME
+
+The::Class       \t \r\n \fname
+      FUNKY_NAME
+      Approvals::Approval.normalize(name).should eq('the_class_name')
+    end
+  end
+
+  it "knows the approved_path" do
+    approval = Approvals::Approval.new(example)
+    approval.approved_path.should eq("#{description}.approved.txt")
+  end
+
+  it "knows the received path" do
+    approval = Approvals::Approval.new(example)
+    approval.received_path.should eq("#{description}.received.txt")
+  end
+
+  it "can set a location" do
+    Dir.stub(:pwd => 'the/path')
+    approval = Approvals::Approval.new(example)
+    approval.location = ['the/path/to/my/heart:9372 <is through my stomach>', 'bla bla bla']
+    approval.location.should eq(['./to/my/heart:9372 <is through my stomach>'])
+  end
+
+  context "approvals" do
+    before :each do
+      @approved_file = "#{description}.approved.txt"
+      @received_file = "#{description}.received.txt"
+    end
+
+    after :each do
+      File.delete(@approved_file) if File.exists?(@approved_file)
+      File.delete(@received_file) if File.exists?(@received_file)
+    end
+
+    describe "on the filesystem" do
+
+      it "writes the approved file if it doesn't exist" do
+        File.delete(@approved_file) if File.exists?(@approved_file)
+
+        Approvals::Approval.new(example)
+
+        File.exists?(@approved_file).should be_true
+        File.read(@approved_file).should eq('')
+      end
+
+      it "doesn't overwrite an existing approved file" do
+        File.open(@approved_file, 'w') do |f|
+          f.write "this doesn't get deleted"
+        end
+
+        Approvals::Approval.new(example)
+
+        File.exists?(@approved_file).should be_true
+        File.read(@approved_file).should eq("this doesn't get deleted")
+      end
+
+      it "writes the received contents to file" do
+        approval = Approvals::Approval.new(example, 'oooh, shiney!')
+
+        File.exists?(@received_file).should be_true
+        File.read(@received_file).should eq("oooh, shiney!")
+      end
+    end
+
+    describe "verification" do
+
+      context "with a match" do
+        before :each do
+          @approval = Approvals::Approval.new(example, 'xyz')
+          @approval.write(:approved, 'xyz')
+        end
+
+        it "does not raise an error" do
+          lambda { @approval.verify }.should_not raise_error(RSpec::Approvals::ReceivedDiffersError)
+        end
+
+        it "does not leave a received file" do
+          lambda { @approval.verify }.call
+          File.exists?(@approval.received_path).should be_false
+        end
+      end
+
+      context "with a mismatch" do
+        before :each do
+          @approval = Approvals::Approval.new(example, 'xyz')
+          @approval.write(:approved, 'abc')
+        end
+
+        it "raises an error" do
+          lambda { @approval.verify }.should raise_error(RSpec::Approvals::ReceivedDiffersError)
+        end
+
+        it "leaves a received file" do
+          begin
+            @approval.verify
+          rescue RSpec::Approvals::ReceivedDiffersError => e
+            # we want to land here and then move on
+          end
+          File.exists?(@approval.received_path).should be_true
+        end
+      end
+    end
+
+    it "fails magnificently" do
+      approval = Approvals::Approval.new(example, 'xyz')
+      message = <<-FAILURE_MESSAGE
+
+        Approval Failure:
+
+        The received contents did not match the approved contents.
+
+        Inspect the differences in the following files:
+        #{approval.received_path}
+        #{approval.approved_path}
+
+        If you like what you see in the *.received.txt file, you can approve it
+        like so:
+
+        mv #{approval.received_path} #{approval.approved_path}
+
+
+      FAILURE_MESSAGE
+
+      approval.failure_message.should eq(message)
+    end
+  end
+end

data/spec/approvals/rspec_approvals_a_complex_object.approved.txt

@@ -0,0 +1 @@
+Hello, World!

data/spec/approvals/rspec_approvals_a_hash.approved.txt

@@ -0,0 +1 @@
+{:universe=>{:side=>:dark, :other_side=>:light}, :force=>true}

data/spec/approvals/rspec_approvals_a_string.approved.txt

@@ -0,0 +1 @@
+We have, I fear, confused power with greatness.

data/spec/approvals/rspec_approvals_an_array.approved.txt

@@ -0,0 +1 @@
+["abc", 123, ["cheese", "burger", "ribs", "steak", "bacon"]]

data/spec/approvals_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe Approvals do
+
+  it "defaults the output dir to spec/approvals" do
+    RSpec.configuration.approvals_path.should == 'spec/approvals'
+  end
+
+  describe "initializing approval directory" do
+    it "does nothing if directory exists" do
+      RSpec.configuration.stub(:approvals_path).and_return 'xyz'
+      Dir.stub(:exists?).and_return true
+      FileUtils.should_not_receive(:makedirs).with 'xyz'
+
+      Approvals.initialize_approvals_path
+    end
+
+    it "creates directory if it is missing" do
+      RSpec.configuration.stub(:approvals_path).and_return 'abc'
+      Dir.stub(:exists?).and_return false
+      FileUtils.should_receive(:makedirs).with('abc')
+
+      Approvals.initialize_approvals_path
+    end
+  end
+
+  it "needs to be able to run with :filtered => true"
+
+  approve "a string" do
+    "We have, I fear, confused power with greatness."
+  end
+
+  approve "a hash" do
+    {
+      :universe => {
+        :side => :dark,
+        :other_side => :light
+      },
+      :force => true
+    }
+  end
+
+  approve "an array" do
+    [
+      "abc",
+      123,
+      %w(cheese burger ribs steak bacon)
+    ]
+  end
+
+  approve "a complex object" do
+    hello = Object.new
+    def hello.to_s
+      "Hello, World!"
+    end
+
+    def hello.inspect
+      "<HelloWorld id:#{object_id}>"
+    end
+
+    hello # => output matches hello.to_s
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'rspec/approvals'
+include RSpec

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: rspec-approvals
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Katrina Owen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-11 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 6
+        version: "2.6"
+  type: :runtime
+  version_requirements: *id001
+description: An RSpec extension that adds support for approvals. Based on the idea of the Golden Master.
+email: 
+- katrina.owen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- License.txt
+- README.md
+- Rakefile
+- lib/rspec/approvals.rb
+- lib/rspec/approvals/approval.rb
+- lib/rspec/approvals/dsl.rb
+- lib/rspec/approvals/formatters/opendiff_formatter.rb
+- lib/rspec/approvals/version.rb
+- rspec-approvals.gemspec
+- spec/approval_spec.rb
+- spec/approvals/rspec_approvals_a_complex_object.approved.txt
+- spec/approvals/rspec_approvals_a_hash.approved.txt
+- spec/approvals/rspec_approvals_a_string.approved.txt
+- spec/approvals/rspec_approvals_an_array.approved.txt
+- spec/approvals_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rspec-approvals
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Approval Tests for Ruby
+test_files: []
+