git-approvals 0.3.0 → 0.4.0

data/README.md

@@ -16,14 +16,31 @@ Or install it yourself as:
 
     $ gem install git-approvals
 
+## Background
+
+[Approval tests][approvaltests] are a testing device popularized by Llewellyn Falco. The basic premise of an approval test is that the subject under test is captured and written to a file, thereby "approving" it. The test assertion is literally a diff of the approved file (expected) with the subject under test (actual). If there is a diff, the test fails because the result does not match the approved file.
+
+For a more comprehensive background and use cases, see [this blog post][blog] I've written on the subject of approval tests.
+
+**Git::Approvals** leverages `git` as a backend to make approval testing simple and the workflow familiar. Your project doesn't necessarily have to be version controlled by `git` to work, but the approved files must. This library assumes  a basic working knowledge of how to use `git`.
+
 ## Usage
 
->  TODO describe standalone usage
+### Standalone
+
+You can use approval tests manually in Ruby if you wish. Suppose you have a file named `foo/bar.txt` that contains the string "baz". The `Approval#diff` method takes a string and a block. It will shell out to `git` and will diff the given string with the file and will call the block if there is a diff or an error occurs.
+
+``` ruby
+approval = Git::Approvals::Approval.new 'foo/bar.txt'
+approval.diff( "baz" ){ |err| puts "fail" } # nothing
+approval.diff( "qux" ){ |err| puts "fail" } # "fail"
+```
+
+The constructor method also accepts a hash of options, which are explained below.
 
-### With RSpec
+### RSpec Integration
 
-In your spec_helper.rb or wherever, simply `require 'rspec/approvals'`.
-Now you can use the `verify` expectation in your specs:
+In your `spec_helper.rb` or wherever, simply `require 'rspec/approvals'`. You can now use the `verify` expectation in your specs:
 
 `spec/foo_spec.rb`
 
@@ -48,6 +65,26 @@ Another test run shows that the test now passes. On the next test run, the
 same file will be written out. If git says the file has changed, the
 test will fail.
 
+The `verify` method accepts the same options hash as the Approval constructor.
+
+### Options
+
+The following options are supported:
+
+- `:format`: specifies the format to use when writing out the approved file. The format is inferred from the extension of the approved file, but if you specify it here, it will change the extension to match. This option accepts any extension that is registered with [tilt][tilt].
+- `:filename`: specifies the filename of the approved file.
+
+### Formatters
+
+**Git::Approvals** uses [tilt][tilt] to write out approved files, so any template format that tilt supports can be used. **Git::Approvals** adds the following formats in addition to the standard tilt templates:
+
+- `txt` writes out a ruby object using [awesome_print][awesomeprint].
+- `json` pretty-prints a json string using the standard JSON library.
+- `js` pretty-prints JavaScript source using [uglifier][uglifier].
+- `css` pretty-prints CSS source using [SASS][sass].
+
+The format will be determined by checking the `:format` key of the options hash, then the extension of the approved filename, and finally will default to `txt`.
+
 ## Contributing
 
 1. Fork it
@@ -55,3 +92,10 @@ test will fail.
 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
+
+[blog]: http://jeremyruppel.tumblr.com/post/52734828127/committed-for-your-approval
+[tilt]: https://github.com/rtomayko/tilt
+[approvaltests]: http://approvaltests.sourceforge.net/
+[awesomeprint]: https://github.com/michaeldv/awesome_print
+[uglifier]: https://github.com/lautis/uglifier
+[sass]: https://github.com/nex3/sass

data/lib/git/approvals/approval.rb

@@ -1,5 +1,4 @@
 require 'open3'
-require 'pathname'
 require 'tilt'
 
 module Git
@@ -7,40 +6,13 @@ module Git
 
     ##
     #
-    class Approval < Pathname
+    class Approval
+      include Git::Approvals::Utils
 
       def initialize( path, options={} ) # :nodoc:
-        @options = options
-
-        path = Pathname( path )
-        path = munge_format( path )
-        path = munge_filename( path )
-
-        super path.to_path
-      end
-      attr_reader :options
-
-      ##
-      # Makes sure the given pathname has an extension.
-      def munge_format( path )
-        ext = [ options[ :format ], path.extname, 'txt' ].detect do |arg|
-          !arg.nil? && !arg.empty?
-        end
-        ext = ext.to_s
-        ext = '.' + ext unless ext.start_with?( '.' )
-        path.sub_ext ext
-      end
-
-      ##
-      # Makes sure the given pathname has the correct filename.
-      def munge_filename( path )
-        if filename = options[ :filename ]
-          dir, base = path.split
-          dir.join( filename + base.extname )
-        else
-          path
-        end
+        @path = transform_filename( path, options )
       end
+      attr_reader :path
 
       ##
       # Diffs the given string with this approval file. If the
@@ -49,20 +21,20 @@ module Git
       # called if the diff fails, meaning there are differences.
       def diff( string, &block )
         # Make sure the directory of the file exists.
-        dirname.mkpath
+        FileUtils.mkdir_p File.dirname( path )
 
         # Write the new string to the file.
-        open 'w' do |f|
-          f << Tilt.new( to_path ).render( string )
+        File.open path, 'w' do |f|
+          f << Tilt.new( path ).render( string )
         end
 
         # If the file hasn't been checked in, raise an error.
-        sh "git ls-files #{to_path} --error-unmatch" do |err|
-          raise Errno::ENOENT, to_path
+        sh "git ls-files #{path} --error-unmatch" do |err|
+          raise Errno::ENOENT, path
         end
 
         # If the file has changed, call the block.
-        sh "git diff --exit-code #{to_path}" do |err|
+        sh "git diff --exit-code #{path}" do |err|
           block.call err
         end
       end
@@ -79,6 +51,7 @@ module Git
 
     ##
     # Register all formatters as tilt templates.
+    Tilt.register PlainFormatter,        ''
     Tilt.register AwesomePrintFormatter, 'txt'
     Tilt.register JSONFormatter,         'json'
     Tilt.register UglifierFormatter,     'js'

data/lib/git/approvals/plain_formatter.rb

@@ -0,0 +1,19 @@
+require 'tilt'
+
+module Git
+  module Approvals
+    class PlainFormatter < Tilt::Template
+
+      def self.engine_initialized?
+        true
+      end
+
+      def prepare
+      end
+
+      def evaluate( context, locals, &block )
+        context.to_s
+      end
+    end
+  end
+end

data/lib/git/approvals/utils.rb

@@ -12,6 +12,24 @@ module Git
           .downcase
       end
       module_function :filenamify
+
+      ##
+      #
+      def transform_filename( str, options={} )
+
+        if opt = options.delete( :format )
+          str.chomp! File.extname( str )
+          str << '.' << opt.to_s
+        end
+
+        if opt = options.delete( :filename )
+          base = File.basename( str, File.extname( str ) )
+          str.sub! /#{base}(?!\/)/, opt
+        end
+
+        str
+      end
+      module_function :transform_filename
     end
   end
 end

data/lib/git/approvals/version.rb

@@ -1,5 +1,5 @@
 module Git
   module Approvals
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/git/approvals.rb

@@ -5,6 +5,7 @@ module Git
     autoload :Approval,              'git/approvals/approval'
     autoload :AwesomePrintFormatter, 'git/approvals/awesome_print_formatter.rb'
     autoload :JSONFormatter,         'git/approvals/json_formatter.rb'
+    autoload :PlainFormatter,        'git/approvals/plain_formatter.rb'
     autoload :SassFormatter,         'git/approvals/sass_formatter.rb'
     autoload :UglifierFormatter,     'git/approvals/uglifier_formatter.rb'
     autoload :Utils,                 'git/approvals/utils'

data/spec/fixtures/input

@@ -0,0 +1 @@
+Plain text.

data/spec/fixtures/input.css

@@ -0,0 +1,2 @@
+/* Comments are preserved */
+html,body{font-family:"Helvetica Neue";}

data/spec/fixtures/input.js

@@ -0,0 +1,2 @@
+// Comments are preserved
+(function(){return {status:"IT WERKS"};})();

data/spec/fixtures/input.json

@@ -0,0 +1 @@
+{"foo":"bar","baz":"quux"}

data/spec/fixtures/output

@@ -0,0 +1 @@
+Plain text.

data/spec/fixtures/{asset.css → output.css}

@@ -1,3 +1,4 @@
+/* Comments are preserved */
 html, body {
   font-family: "Helvetica Neue";
 }

data/spec/fixtures/output.txt

@@ -0,0 +1,8 @@
+{
+  :foo => "bar",
+  :baz => [
+    [0] 1,
+    [1] 2,
+    [2] 3
+  ]
+}

data/spec/git/approvals/approval_spec.rb

@@ -3,24 +3,13 @@ require 'spec_helper'
 describe Git::Approvals::Approval do
 
   describe '#initialize' do
-    subject { described_class.new './foo/bar.txt' }
-
-    its( :to_path ){ should == './foo/bar.txt' }
-    its( :options ){ should == { } }
-  end
-
-  describe '#options' do
-    describe ':format' do
-      it 'replaces the extension' do
-        subject = described_class.new 'foo/bar.txt', :format => :json
-        subject.to_path.should == 'foo/bar.json'
-      end
+    context 'straight up' do
+      subject { described_class.new 'foo/bar.txt' }
+      its( :path ){ should == 'foo/bar.txt' }
     end
-    describe ':filename' do
-      it 'replaces the filename' do
-        subject = described_class.new 'foo/bar.txt', :filename => 'baz'
-        subject.to_path.should == 'foo/baz.txt'
-      end
+    context 'with options' do
+      subject { described_class.new 'foo/bar.txt', :format => :json, :filename => 'baz' }
+      its( :path ){ should == 'foo/baz.json' }
     end
   end
 
@@ -56,36 +45,12 @@ describe Git::Approvals::Approval do
     end
   end
 
-  describe 'formats' do
-    it 'formats strings' do
-      approval = described_class.new './spec/fixtures/string.txt'
-      approval.diff( 'IT WERKS' ){ |diff| fail diff }
-    end
-    it 'formats arrays' do
-      approval = described_class.new './spec/fixtures/array.txt'
-      approval.diff( [ :foo, :bar, :baz ] ){ |diff| fail diff }
-    end
-    it 'formats hashes' do
-      approval = described_class.new './spec/fixtures/hash.txt'
-      approval.diff( { :foo => 'bar', :quux => 'bar' } ){ |diff| fail diff }
-    end
-    it 'formats json' do
-      approval = described_class.new './spec/fixtures/hash.json'
-      approval.diff( '{"foo":"bar","baz":"quux"}' ){ |diff| fail diff }
-    end
-    it 'formats javascript' do
-      approval = described_class.new './spec/fixtures/asset.js'
-      approval.diff( <<-EOS ){ |diff| fail diff }
-      // Comments are preserved
-      (function(){return {status:"IT WERKS"};})();
-      EOS
-    end
-    it 'formats css' do
-      approval = described_class.new './spec/fixtures/asset.css'
-      approval.diff( <<-EOS ){ |diff| fail diff }
-      // Comments are preserved
-      html,body{font-family:"Helvetica Neue";}
-      EOS
-    end
+  describe 'Tilt mappings' do
+    subject { Tilt.mappings }
+    it { should include( ''     => [ Git::Approvals::PlainFormatter ] ) }
+    it { should include( 'txt'  => [ Git::Approvals::AwesomePrintFormatter ] ) }
+    it { should include( 'css'  => [ Git::Approvals::SassFormatter ] ) }
+    it { should include( 'json' => [ Git::Approvals::JSONFormatter ] ) }
+    it { should include( 'js'   => [ Git::Approvals::UglifierFormatter ] ) }
   end
 end

data/spec/git/approvals/formatter_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+shared_examples 'formatter' do |ext|
+  let( :input  ){ File.read "./spec/fixtures/input#{ext}" }
+  let( :output ){ "./spec/fixtures/output#{ext}" }
+
+  it 'formats the input appropriately' do
+    approval = Git::Approvals::Approval.new output
+    approval.diff( input ){ |diff| fail diff }
+  end
+end
+
+describe Git::Approvals::PlainFormatter do
+  include_examples 'formatter', ''
+end
+describe Git::Approvals::JSONFormatter do
+  include_examples 'formatter', '.json'
+end
+describe Git::Approvals::UglifierFormatter do
+  include_examples 'formatter', '.js'
+end
+describe Git::Approvals::SassFormatter do
+  include_examples 'formatter', '.css'
+end
+describe Git::Approvals::AwesomePrintFormatter do
+  include_examples 'formatter', '.txt' do
+    let( :input ){ { :foo => 'bar', :baz => [ 1, 2, 3 ] } }
+  end
+end

data/spec/git/approvals/rspec_spec/rspec_integration/verify/fails_when_changed

@@ -0,0 +1 @@
+IT WERKS

data/spec/git/approvals/rspec_spec/rspec_integration/verify/passes_when_unchanged

@@ -0,0 +1 @@
+IT WERKS

data/spec/git/approvals/rspec_spec.rb

@@ -18,7 +18,7 @@ describe 'RSpec integration' do
     after { `git checkout #{approval_directory}` }
 
     it 'passes when unchanged' do
-      verify { 'IT WERKS' }
+      expect { verify { 'IT WERKS' } }.not_to raise_error
     end
     it 'fails when changed' do
       expect { verify { 'IT BROKE' } }.to raise_error( RSpec::Expectations::ExpectationNotMetError )

data/spec/git/approvals/utils_spec.rb

@@ -15,4 +15,20 @@ describe Git::Approvals::Utils do
       end
     end
   end
+
+  describe '#transform_filename' do
+    {
+      [ 'foo'                                 ] => 'foo',
+      [ 'foo',         { :format => :json }   ] => 'foo.json',
+      [ 'foo',         { :format => 'json' }  ] => 'foo.json',
+      [ 'foo.txt',     { :format => :json }   ] => 'foo.json',
+      [ 'foo',         { :filename => 'bar' } ] => 'bar',
+      [ 'foo.txt',     { :filename => 'bar' } ] => 'bar.txt',
+      [ 'foo/foo.txt', { :filename => 'bar' } ] => 'foo/bar.txt'
+    }.each do |args, filename|
+      example 'with %s' % [ args.inspect ] do
+        described_class.transform_filename( *args ).should == filename
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git-approvals
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-14 00:00:00.000000000 Z
+date: 2013-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tilt
@@ -194,22 +194,27 @@ files:
 - lib/git/approvals/approval.rb
 - lib/git/approvals/awesome_print_formatter.rb
 - lib/git/approvals/json_formatter.rb
+- lib/git/approvals/plain_formatter.rb
 - lib/git/approvals/rspec.rb
 - lib/git/approvals/sass_formatter.rb
 - lib/git/approvals/uglifier_formatter.rb
 - lib/git/approvals/utils.rb
 - lib/git/approvals/version.rb
 - lib/rspec/approvals.rb
-- spec/fixtures/array.txt
-- spec/fixtures/asset.css
-- spec/fixtures/asset.js
-- spec/fixtures/hash.json
-- spec/fixtures/hash.txt
-- spec/fixtures/string.txt
+- spec/fixtures/input
+- spec/fixtures/input.css
+- spec/fixtures/input.js
+- spec/fixtures/input.json
+- spec/fixtures/output
+- spec/fixtures/output.css
+- spec/fixtures/output.js
+- spec/fixtures/output.json
+- spec/fixtures/output.txt
 - spec/git/approvals/approval_spec.rb
+- spec/git/approvals/formatter_spec.rb
 - spec/git/approvals/rspec_spec.rb
-- spec/git/approvals/rspec_spec/rspec_integration/verify/fails_when_changed.txt
-- spec/git/approvals/rspec_spec/rspec_integration/verify/passes_when_unchanged.txt
+- spec/git/approvals/rspec_spec/rspec_integration/verify/fails_when_changed
+- spec/git/approvals/rspec_spec/rspec_integration/verify/passes_when_unchanged
 - spec/git/approvals/utils_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/jeremyruppel/git-approvals
@@ -238,16 +243,20 @@ signing_key:
 specification_version: 3
 summary: Simple git-powered approval tests.
 test_files:
-- spec/fixtures/array.txt
-- spec/fixtures/asset.css
-- spec/fixtures/asset.js
-- spec/fixtures/hash.json
-- spec/fixtures/hash.txt
-- spec/fixtures/string.txt
+- spec/fixtures/input
+- spec/fixtures/input.css
+- spec/fixtures/input.js
+- spec/fixtures/input.json
+- spec/fixtures/output
+- spec/fixtures/output.css
+- spec/fixtures/output.js
+- spec/fixtures/output.json
+- spec/fixtures/output.txt
 - spec/git/approvals/approval_spec.rb
+- spec/git/approvals/formatter_spec.rb
 - spec/git/approvals/rspec_spec.rb
-- spec/git/approvals/rspec_spec/rspec_integration/verify/fails_when_changed.txt
-- spec/git/approvals/rspec_spec/rspec_integration/verify/passes_when_unchanged.txt
+- spec/git/approvals/rspec_spec/rspec_integration/verify/fails_when_changed
+- spec/git/approvals/rspec_spec/rspec_integration/verify/passes_when_unchanged
 - spec/git/approvals/utils_spec.rb
 - spec/spec_helper.rb
 has_rdoc: 

data/spec/fixtures/array.txt

@@ -1,5 +0,0 @@
-[
-  [0] :foo,
-  [1] :bar,
-  [2] :baz
-]

data/spec/fixtures/hash.txt

@@ -1,4 +0,0 @@
-{
-  :foo  => "bar",
-  :quux => "bar"
-}

data/spec/fixtures/string.txt

@@ -1 +0,0 @@
-"IT WERKS"

data/spec/git/approvals/rspec_spec/rspec_integration/verify/fails_when_changed.txt

@@ -1 +0,0 @@
-"IT WERKS"

data/spec/git/approvals/rspec_spec/rspec_integration/verify/passes_when_unchanged.txt

@@ -1 +0,0 @@
-"IT WERKS"