arg-that 0.0.1

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec'
+  gem 'rspec-given'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Justin Searls
+
+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,97 @@
+# arg-that
+
+arg-that provides a simple method to create an argument matcher in equality comparisons. This is particularly handy when writing a test to assert the equality of some complex data struct with another and only one component is difficult or unwise to assert exactly.
+
+## wat?
+
+Typically, tests specify exactly what a result should be equal to. If the value of `result` were `5`, then one would probably write an assertion like `result.should == 5` and call it a day.
+
+But sometimes:
+
+* You don't know exactly what the result is, and the part you don't know about doesn't matter a great deal
+* A looser specification is preferable to an exact one; suppose a looser specification sufficiently verifies the subject code is working, and greater specificity in the assertion would only serve to constrain changes to future implementation details
+
+## example
+
+Suppose our subject returns a hefty hash of attributes following a `save` operation of a `User` entity.
+
+``` ruby
+subject.save #=> {:name => "Bob", :age => 28, :email => "bob@example.com" :created_at => 2013-07-18 21:40:58 -0400}
+```
+
+While authoring the test, we neither care much about the value of `created_time`, nor do we know how to specify it exactly. That means we can't just do this:
+
+``` ruby
+result = subject.save
+result.should == {:name => "Bob", :age => 28, :email => "bob@example.com" :created_at => 2013-07-18 21:40:58 -0400}
+```
+
+This wouldn't work, because at runtime the value of `created_at` will, of course, differ.
+
+So, one could do this:
+
+``` ruby
+result = subject.save
+result[:name].should == "Bob"
+result[:age].should == 28
+result[:email].should == "bob@example.com"
+```
+
+But now we've got three assertions when before we had one. Alas, we no longer have a clear visual of the *shape* of the data being returned by `save`. Additionally, if the map grows with additional meaningful values in the future, this test would continue to pass by incident.
+
+The `arg_that` matcher can save us this annoyance by retaining the more terse *style* of the first example, while retaining the liberal specification necessitated by the situation:
+
+```
+result.should == {
+  :name => "Bob",
+  :age => 28,
+  :email => "bob@example.com",
+  :created_at => arg_that { true }
+}
+```
+
+Where `arg_that { true }` would literally pass any equality test. If there's *something* we want to constrain about the `created_at` value, we could do so. Perhaps a type check like `arg_that { |arg| arg.kind_of?(Time) }` would be more appropriate.
+
+The purpose of releasing something as simple as `arg-that` as a gem is to promote the intentionality about how specific any given equality assertion needs to be. The status quo seems to be to either "always specify everything exactly, but if that gets hard, specify the remainder arbitrarily." And that's not terrific.
+
+## usage
+
+Here's how you'd use it in RSpec.
+
+In your `spec_helper.rb`, you can make arg-that available to all of your examples by telling RSpec to include it:
+
+``` ruby
+require 'arg_that'
+
+RSpec.configure do |config|
+  config.include(ArgThat)
+end
+```
+
+Once included, you can make more liberal assertions as you see fit, like so:
+
+``` ruby
+result = {
+  :zip_code => 48176,
+  :owner => "Fred Jim",
+  :last_audit => Time.new(2012, 8, 12)
+}
+
+result.should == {
+  :zip_code => 48176,
+  :owner => "Fred Jim",
+  :last_audit => arg_that { |arg| arg > Time.new(2012, 1, 1) }
+}
+```
+
+In this way, the result will verify the two entries we want to specify exactly (`zip_code` and `owner`), but allows us the flexibility of only loosely specifying that we're okay with any value of `last_audit` so long as it was some time after January 1st, 2012.
+
+## known issues
+
+`arg_that` does you no good on symbols, as the equality check short-circuits the call to `==` on the receiver.
+
+Any ideas on how to make this pass?
+
+``` ruby
+:foo.should == arg_that { true }
+```

data/Rakefile

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

data/arg_that.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'arg_that/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "arg-that"
+  spec.version       = ArgThat::VERSION
+  spec.authors       = ["Justin Searls"]
+  spec.email         = ["searls@gmail.com"]
+  spec.description   = %q{arg-that provides a simple method to create an argument matcher in equality comparisons.}
+  spec.summary       = %q{arg-that provides a simple method to create an argument matcher in equality comparisons. This is particularly handy when writing a test to assert the equality of some complex data struct with another and only one component is difficult or unwise to assert exactly.}
+  spec.homepage      = "http://github.com/testdouble/arg-that"
+  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_development_dependency "bundler", "~> 1.3"
+end

data/lib/arg_that.rb

@@ -0,0 +1,8 @@
+require "arg_that/version"
+require "arg_that/that_arg"
+
+module ArgThat
+  def arg_that(&blk)
+    ThatArg.new(&blk)
+  end
+end

data/lib/arg_that/that_arg.rb

@@ -0,0 +1,9 @@
+class ThatArg
+  def initialize(&blk)
+    @blk = blk
+  end
+
+  def ==(other)
+    @blk.call(other)
+  end
+end

data/lib/arg_that/version.rb

@@ -0,0 +1,3 @@
+module ArgThat
+  VERSION = "0.0.1"
+end

data/spec/arg_that_spec.rb

@@ -0,0 +1,64 @@
+require 'rspec'
+require 'rspec/given'
+
+require 'arg_that'
+
+RSpec.configure do |config|
+  config.include(ArgThat)
+end
+
+describe ArgThat do
+
+  context "catch-all" do
+    Then { :foo.should == arg_that { true }}
+
+    Then { 5.should == arg_that { true } }
+    Then { 5.should_not == arg_that { false } }
+  end
+
+  context "direct value equality" do
+    Then { 1.should == arg_that {|arg| arg.kind_of?(Fixnum) } }
+    Then { 1.should_not == arg_that {|arg| arg.kind_of?(String) } }
+  end
+
+  context "a value inside something else" do
+    Then { [5, 6, 1].should == [5, 6, arg_that {|arg| arg.kind_of?(Fixnum) }]}
+    Then { [5, 6, 1].should_not == [5, 6, arg_that {|arg| arg > 1 }]}
+    Then do
+      {
+        :a => 1,
+        :b => 99
+      }.should == {
+        :a => 1,
+        :b => arg_that {|arg| arg > 98 && arg < 100 }
+      }
+    end
+
+    Then do
+      {
+        :zip_code => 48176,
+        :owner => "Fred Jim",
+        :last_audit => Time.new(2012, 8, 12)
+      }.should == {
+        :zip_code => 48176,
+        :owner => "Fred Jim",
+        :last_audit => arg_that { |arg| arg > Time.new(2012, 1, 1) }
+      }
+    end
+
+    Then do
+      {
+        :name => "Bob",
+        :age => 28,
+        :email => "bob@example.com",
+        :created_at => Time.new(2013, 7, 18, 21, 40, 58)
+      }.should == {
+        :name => "Bob",
+        :age => 28,
+        :email => "bob@example.com",
+        :created_at => arg_that { |arg| arg.kind_of?(Time) }
+      }
+    end
+  end
+
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: arg-that
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Justin Searls
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: arg-that provides a simple method to create an argument matcher in equality
+  comparisons.
+email:
+- searls@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- arg_that.gemspec
+- lib/arg_that.rb
+- lib/arg_that/that_arg.rb
+- lib/arg_that/version.rb
+- spec/arg_that_spec.rb
+homepage: http://github.com/testdouble/arg-that
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: arg-that provides a simple method to create an argument matcher in equality
+  comparisons. This is particularly handy when writing a test to assert the equality
+  of some complex data struct with another and only one component is difficult or
+  unwise to assert exactly.
+test_files:
+- spec/arg_that_spec.rb