arg-that 0.0.1 → 0.1.0

data/.travis.yml

@@ -0,0 +1,2 @@
+language: ruby
+script: 'bundle exec rspec'

data/README.md

@@ -1,5 +1,7 @@
 # arg-that
 
+[![Build Status](https://travis-ci.org/testdouble/arg-that.png?branch=master)](https://travis-ci.org/testdouble/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?
@@ -19,11 +21,11 @@ Suppose our subject returns a hefty hash of attributes following a `save` operat
 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:
+While authoring the test, we neither care much about the value of `created_at`, 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}
+expect(result).to eq(:name => "Bob", :age => 28, :email => "bob@example.com" :created_at => Time.new(2013,7,18,21,40,58,"-04:00"))
 ```
 
 This wouldn't work, because at runtime the value of `created_at` will, of course, differ.
@@ -32,27 +34,27 @@ So, one could do this:
 
 ``` ruby
 result = subject.save
-result[:name].should == "Bob"
-result[:age].should == 28
-result[:email].should == "bob@example.com"
+expect(result[:name]).to eq("Bob")
+expect(result[:age]).to eq(28)
+expect(result[:email]).to eq("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.
+But now we've got three assertions when before we only 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 == {
+expect(result).to eqish(
   :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.
+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. Also, note that arg-that includes an RSpec matcher called `eqish` which is meant to be used in conjunction with the `arg_that` matcher. [Please refer to the bottom of this document for a discussion on why.]
 
-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.
+The purpose of releasing something as simple as `arg-that` as a gem is to promote more intentionality about how specific any given equality assertion needs to be. The modus operandi of most Rubyists seems to be "always specify everything exactly, but if that gets hard, specify the remainder arbitrarily." And that's not terrific.
 
 ## usage
 
@@ -77,21 +79,36 @@ result = {
   :last_audit => Time.new(2012, 8, 12)
 }
 
-result.should == {
+expect(result).to eqish(
   :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
+## what's up with this `eqish` matcher?
+
+**tl;dr whenever you use `arg_that` in an equality RSpec expectation, always use the `eqish` matcher or otherwise ensure that `==` is being called on the object containing the `arg_that` matcher**
+
+As mentioned above, the reason that arg-that includes a matcher called `eqish` is because of the nature of how equality (`==`) tests work in Ruby (and most other OOP languages). The object that receives the message "are you equal?" is responsible for determining whether some other thing this equal to it.
 
-`arg_that` does you no good on symbols, as the equality check short-circuits the call to `==` on the receiver.
+This works fine in most of our programs, because in almost every circumstance, two objects of the same type will adhere to the *symmetric property of equality* contract when asked whether one equals the other.
 
-Any ideas on how to make this pass?
+That is to say, if:
 
 ``` ruby
-:foo.should == arg_that { true }
+x = 5
+y = 5
+
+x == y #=> true
+y == x #=> true
 ```
+
+**However**, it's the very nature of matchers like `arg_that` to *intentionally violate* the symmetric property of equality. We do this because such tests are only concerned about *partial equality*. As a result, to serve the purpose of the test, it's important that the expected value be the object who is asked "are you equal?" to the object being interrogated by the test; if the actual value is asked the question, then our definition of partial equality will never be invoked!
+
+This is a bit of a bummer, because RSpec (and most testing libraries) will invoke `==` on the actual value, and not the expected value. Therefore, if an asymmetric definition of equality is desired, `==` must be invoked on the expected value.
+
+To work around this, arg_that includes an RSpec matcher (which is auto-defined if you include `ArgThat` in an `RSpec.configure` block) called `eqish` [source](https://github.com/testdouble/arg-that/blob/master/lib/arg_that/eqish.rb). The implementation of `eqish` is literally to swap the order of `actual == expected` to `expected == actual`. In all other matters, it delegates to RSpec's built-in `eq` matcher.
+

data/lib/arg_that.rb

@@ -5,4 +5,10 @@ module ArgThat
   def arg_that(&blk)
     ThatArg.new(&blk)
   end
+
+  def self.included(includer)
+    if defined?(RSpec) && includer.ancestors.include?(RSpec::Core::ExampleGroup)
+      require "arg_that/eqish"
+    end
+  end
 end

data/lib/arg_that/eqish.rb

@@ -0,0 +1,21 @@
+RSpec::Matchers.define :eqish do |expected|
+  match do |actual|
+    expected == actual
+  end
+
+  failure_message_for_should do |actual|
+    RSpec::Matchers::BuiltIn::Eq.new(expected).
+      tap {|eq| eq.matches?(actual) }.
+      failure_message_for_should
+  end
+
+  failure_message_for_should_not do |actual|
+    RSpec::Matchers::BuiltIn::Eq.new(expected).
+      tap {|eq| eq.matches?(actual) }.
+      failure_message_for_should_not
+  end
+
+  description do
+    RSpec::Matchers::BuiltIn::Eq.new(expected).description
+  end
+end

data/lib/arg_that/version.rb

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

data/spec/arg_that_spec.rb

@@ -8,57 +8,96 @@ RSpec.configure do |config|
 end
 
 describe ArgThat do
+  describe "using arg_that as a catch-all" do
+    subject { Object.new }
 
-  context "catch-all" do
-    Then { :foo.should == arg_that { true }}
+    context "arg_that { true } always matches" do
+      Then { expect(subject).to eqish arg_that { true } }
+    end
 
-    Then { 5.should == arg_that { true } }
-    Then { 5.should_not == arg_that { false } }
+    context "arg_that { false } never matches" do
+      Then { expect(subject).to_not eqish arg_that { false } }
+    end
   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) } }
+  describe "directly comparing a value with an arg_that matcher" do
+    Then { expect(:foo).to eqish arg_that {|arg| arg.kind_of?(Symbol) } }
+    Then { expect(:foo).to_not eqish 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 }
-      }
+  describe "comparing a value nestled in a collection with an arg_that matcher" do
+    context "arrays" do
+      Then { expect([5, 6, 1]).to eqish [5, 6, arg_that {|arg| arg < 2 }]}
+      Then { expect([5, 6, 1]).to_not eqish [5, 6, arg_that {|arg| arg > 1 }]}
     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
+    context "hashes" do
+      Then do
+        expect(
+          :a => 1,
+          :b => 99
+        ).to eqish(
+          :a => 1,
+          :b => arg_that {|arg| arg > 98 && arg < 100 }
+        )
+      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) }
-      }
+      Then do
+        expect(
+          :zip_code => 48176,
+          :owner => "Fred Jim",
+          :last_audit => Time.new(2012, 8, 12)
+        ).to eqish(
+          :zip_code => 48176,
+          :owner => "Fred Jim",
+          :last_audit => arg_that { |arg| arg > Time.new(2012, 1, 1) }
+        )
+      end
+
+      Then do
+        expect(
+          :name => "Bob",
+          :age => 28,
+          :email => "bob@example.com",
+          :created_at => Time.new(2013, 7, 18, 21, 40, 58)
+        ).to eqish(
+          :name => "Bob",
+          :age => 28,
+          :email => "bob@example.com",
+          :created_at => arg_that { |arg| arg.kind_of?(Time) }
+        )
+      end
     end
   end
 
+  describe "comparing custom types with an arg_that matcher" do
+    context "a simple type" do
+      class Dog
+        def bark
+          "wan wan"
+        end
+      end
+      subject { Dog.new }
+      When(:result) { subject.bark }
+      Then { expect(result).to eqish arg_that { |arg| arg.include?("wan") } }
+      And { expect(result).to_not eqish arg_that { |arg| arg.include?("woof") } }
+    end
+
+    context "a type that overrides ==" do
+      class Cat
+        def ==(other)
+          false
+        end
+
+        def name
+          "Gorbypuff"
+        end
+      end
+
+      subject { Cat.new }
+      Then { expect(subject).to eqish arg_that { |arg| arg.name == "Gorbypuff" }}
+      Then { expect(subject).to_not eqish arg_that { |arg| arg.name == "Miles" }}
+    end
+  end
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arg-that
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-19 00:00:00.000000000 Z
+date: 2013-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -36,12 +36,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - arg_that.gemspec
 - lib/arg_that.rb
+- lib/arg_that/eqish.rb
 - lib/arg_that/that_arg.rb
 - lib/arg_that/version.rb
 - spec/arg_that_spec.rb