graham 0.0.3a → 0.0.3

data/README.md

@@ -1,13 +1,29 @@
-# Graham #
+Graham
+------
 
-Graham is a tiny-yet-useful testing library based on Mallow - in fact it _is_ Mallow, with a tweaked DSL and some extra exception handling, bundled with a trivial pretty printer and a helper for Rake tasks. It was written to handle Mallow's unit tests because:
+Graham is a small-but-strong testing library based on Mallow - in fact it _is_ Mallow, with a tweaked DSL and some extra exception handling, bundled with a trivial pretty printer and a helper for Rake tasks. It was written to handle Mallow's unit tests because:
 * Test::Unit was too ugly
 * TestRocket was too minimal
 * RSpec was too verbose (not to mention ridiculous overkill)
 
-## How does one use graham ??? ##
+Features
+--------
 
-Graham test cases are instance methods on arbitrary classes:
+* Dandy DSL
+* Zero namespace pollution
+* Hackable with a small code footprint
+* Testing paradigm does not necessitate the gratuitous reinvention of such language features as inheritance, namespacing, and variable assignment (unlike some other frameworks that i sometimes have to use :/)
+
+But how to use ???
+----------------------
+
+Graham test cases are just ordinary methods on arbitrary objects:
+```ruby
+  Graham.test {|that|
+    that[1].even?.is true
+  } #=> {#<TestCase ...> => false}
+```
+You can optionally specify a default receiver for tests:
 ```ruby
   class Cases
     def initialize
@@ -23,14 +39,18 @@ Graham test cases are instance methods on arbitrary classes:
       obj.upcase
     end
   end
-```
-Then test your cases:
-```ruby
-  Graham.test(Cases) do |that|
+
+  Graham.test(Cases.new) do |that|
     that.one_squared.is 1
     that.dividing_by_zero.returns_a(Fixnum).such_that {|n| n > 1}
     that.calling_upcase_on(Graham).does_not_raise_an_exception
-  end #=> {:one_squared=>true, :dividing_by_zero=>#<ZeroDivisionError>, :calling_upcase_on=>false}
+  end
 ```
-Or use Graham::test! to run the results through Graham's pretty printer.
+See RDoc documentation for more details on usage, and for information on how to use the Rake helper. Hint:
+```ruby
+  require 'graham/rake_task'
+  Graham::RakeTask.new
+  task default: :test
+```
+
 

data/lib/graham.rb

@@ -3,49 +3,27 @@ require 'mallow'
 require 'graham/version'
 # == A miniature test engine powered by Mallow
 # ---
-# Test cases are instance methods on arbitrary classes, and expectations on
-# their return values are enumerated using a very slightly modified
+# Test cases are methods on arbitrary objects, and expectations on 
+# their return values are enumerated using a slightly modified 
 # Mallow::DSL.
 # 
-#  class Cases
-#    def four_plus_five
-#      4 + 5 
-#    end
+#  class MyCase
 #    def upcasing(s)
 #      s.upcase
 #    end
-#    def one_divided_by_zero
-#      1/0
-#    end
 #  end
 #
-#  Graham.test(Cases) { |that|
-#    that.four_plus_five.is 9
+#  Graham.test(MyCase.new) { |that|
 #    that.upcasing('test').returns 'TeST'
-#    that.one_divided_by_zero.equals :infinity
-#  } #=> {:four_plus_five=>true, :upcasing=>false, :one_divided_by_zero=>#<ZeroDivisionError>}
-#
-# === N.B.
-# Since a Graham test is basically a Mallow pattern matcher, only the first
-# test on a case will actually be executed, as subsequent invocations of the
-# test case will be matched by the first rule. This can lead to confusing
-# results:
+#  } #=> {#<TestCase ...>=>false}
 #
-#  Graham.test(Cases) { |that|
-#    that.four_plus_five.returns_a(Fixnum)
-#    that.four_plus_five.returns_a(String)
-#  } #=> {:four_plus_five=>true}
+# The argument to Graham::test is optional, but if you include it,
+# you don't need to specify test subjects. Compare:
 #
-# To avoid this issue, either run separate tests:
-#
-#  Graham.test(Cases) {|that| that.four_plus_five.returns_a Fixnum} #=> {:four_plus_five=>true}
-#  Graham.test(Cases) {|that| that.four_plus_five.returns_a String} #=> {:four_plus_five=>false}
-# 
-# Or (better) chain the tests you want to run:
-# 
-#  Graham.test(Cases) { |that|
-#    that.four_plus_five.returns_a(Fixnum).that {is_a? String}
-#  } #=> {:four_plus_five=>false}
+#  Graham.test! { |that|
+#    that[1].odd?.returns true
+#    that['adsf'].is_a? String
+#  }
 #
 module Graham
   autoload :PP,       'graham/pp'
@@ -55,12 +33,12 @@ module Graham
     # A convenience method that builds and executes a Graham::Core
     # in the given namespace (defaults to Cases). See documentation for
     # Graham for more on usage.
-    def test(ns, &b)
+    def test(ns=nil, &b)
       DSL.build_core(ns, &b).test
     end
     # A convenience method that calls ::test and passes the output to a
     # pretty printer.
-    def pp(ns, &b)
+    def pp(ns=nil, &b)
       PP.new(test ns,&b).pp
     end
     alias test! pp
@@ -69,7 +47,7 @@ module Graham
   class Core < Mallow::Core
     attr_reader :cases
     def initialize
-      @cases = {}
+      @cases = []
       super
     end
 
@@ -84,7 +62,7 @@ module Graham
       end
     end
 
-    def test; Hash[_fluff @cases.keys] end
+    def test; Hash[_fluff @cases] end
   end
 end
 

data/lib/graham/dsl.rb

@@ -1,9 +1,10 @@
+require 'graham/test_case'
 module Graham
   class DSL < Mallow::BasicDSL
     include Mallow::DSL::Matchers
     def self.build_core(ns)
       yield(dsl = new(ns))
-      dsl.finish!
+      dsl.send(:rule!).core
     end
 
     def initialize(ns)
@@ -16,23 +17,26 @@ module Graham
       when /^((and|that)_)+(.+)$/
         respond_to?($3)? send($3, *args, &b) : super
       else
-        core.cases[msg] = args
-        (conditions.empty?? self : rule!)._where {|e|e==msg}
+        _case @ns, msg, args, b
       end
     end
 
-    def _where(&b)
-      push b, :conditions
+    # Add a condition on a test case's return value. If the given block
+    # has no parameters, it is evaluated in the context of the return
+    # value.
+    def where(&b)
+      push {|e| preproc(b).call e.go }
     end
 
-    def where(&b)
-      _where {|e| preproc(b).call @ns.new.send(e, *core.cases[e]) }
+    # Specify the subject for the next test.
+    def subject(obj)
+      TestCase::Proxy.new self, obj
     end
 
     def raises(x=nil)
-      _where {
+      push {|tc|
         begin
-          call
+          tc.go
           false
         rescue x => e
           true
@@ -43,9 +47,9 @@ module Graham
     end
 
     def does_not_raise(x=nil)
-      _where {
+      push {|tc|
         begin
-          call
+          tc.go
           true
         rescue x => e
           false
@@ -78,6 +82,18 @@ module Graham
     alias returns_a  a
     alias returns_an a
 
+    alias []   subject
+
+    private
+    def push(&p)
+      conditions << p
+      self
+    end
+
+    def _case(obj, msg, args, blk)
+      core.cases << (tc=TestCase.new obj, msg, args, blk)
+      (conditions.empty?? self : rule!).send(:push) {|e|e==tc}
+    end
   end
 end
 

data/lib/graham/pp.rb

@@ -12,14 +12,14 @@ module Graham
       @results, @bt, @out, @color = results, bt, out, color
     end
     def pp
-      results.each do |name, result|
+      results.each do |tc, result|
         out.puts case result
         when true
-          [hi('PASS', GREEN), lo(name)]
+          [hi('PASS', GREEN), lo(tc)]
         when false
-          [hi('FAIL', RED),   lo(name)]
+          [hi('FAIL', RED),   lo(tc), "#=> #{tc.go}"]
         else
-          [hi('XPTN', RED),   lo(name), result.class.name, result.message] + backtrace(result, bt)
+          [hi('XPTN', RED),   lo(tc), result.class.name, result.message] + backtrace(result, bt)
         end.join ' :: '
       end
     end

data/lib/graham/test_case.rb

@@ -0,0 +1,26 @@
+module Graham
+  # A struct for encapsulating test cases. Memoizes the case's return
+  # value.
+  class TestCase < Struct.new(:obj, :msg, :args, :blk)
+    def go
+      defined?(@val) ? @val : (@val = obj.send msg, *args, &blk)
+    end
+
+    def to_s
+      "#{Class===obj ? '::' : ?#}#{msg}(#{args.join ', '})#{" {...}" if blk}"
+    end
+
+    # Delegator to create test cases out of methods that would otherwise
+    # mistakenly be called on a DSL instance.
+    class Proxy < BasicObject
+      def initialize(dsl,obj)
+        @dsl,@obj=dsl,obj
+      end
+
+      def method_missing(msg,*args,&blk)
+        @dsl.send :_case,@obj,msg,args,blk
+      end
+    end
+  end
+end
+

data/lib/graham/version.rb

@@ -1,3 +1,3 @@
 module Graham
-  VERSION = '0.0.3a'
+  VERSION = '0.0.3'
 end

data/test/case/cases.rb

@@ -3,7 +3,7 @@ class TestCases
   def DocTest2; 'test'.upcase end
   def DocTest3; 1/0  end
   def rdoc_example
-    Graham.test(TestCases) { |that|
+    Graham.test(TestCases.new) { |that|
       that.DocTest1.returns_a(Fixnum).such_that {self < 100}
       that.DocTest2.returns 'TeST'
       that.DocTest3.returns_a(Numeric)
@@ -21,7 +21,7 @@ class TestCases
     Graham.this_is_not_a_method
   end
   def readme_example
-    Graham.test(TestCases) do |that|
+    Graham.test(TestCases.new) do |that|
       that.squaring(1).returns 1
       that.dividing_by_zero(1).returns_a(Fixnum)
       that.calling_a_nonexistent_method.does_not_raise_an_exception
@@ -29,16 +29,14 @@ class TestCases
   end
 end
 
-Graham.pp(TestCases) do |that|
-  that.rdoc_example.returns_a(Hash).of_size(3).such_that {|h|
-    h[:DocTest1] == true  and
-    h[:DocTest2] == false and
-    h[:DocTest3].is_a? ZeroDivisionError
+Graham.test!(TestCases.new) do |that|
+  that.rdoc_example.returns_a(Hash).of_size(3).such_that {
+    values[0..1] == [true, false] and
+    values[2].is_a? ZeroDivisionError
   }
-  that.readme_example.returns_a(Hash).of_size(3).such_that {|h|
-    h[:squaring] == true and
-    h[:dividing_by_zero].is_a? ZeroDivisionError and
-    h[:calling_a_nonexistent_method] == false
+  that.readme_example.returns_a(Hash).of_size(3).such_that {
+    values.values_at(0,2) == [true, false] and
+    values[1].is_a? ZeroDivisionError
   }
 end
 

data/test/case/control.rb

@@ -3,7 +3,7 @@ class ControlCases
   def raising_a_name_error; raise Asdf.qwer.ty / 0 end
 end
 
-Graham.pp(ControlCases) {|that|
+Graham.pp(ControlCases.new) {|that|
   that.the_number_99.returns_a(Fixnum).such_that {self==99}.and_that_is 99
   that.raising_a_name_error.raises.and_raises_a NameError
 }

data/test/case/subject.rb

@@ -0,0 +1,3 @@
+Graham.test! {|that|
+  that[1].even?.is false
+}

data/test/unit/arguments.rb

@@ -4,6 +4,6 @@ class Arguments
   end
 end
 
-Graham.pp(Arguments) {|that|
+Graham.pp(Arguments.new) {|that|
   that.doubling(2).equals 4
 }

data/test/unit/namespaces.rb

@@ -14,13 +14,10 @@ class Namespace
   end
 end
 
-Graham.pp(Namespace) do |that|
+Graham.pp(Namespace.new) do |that|
   that.namespacing.is_such_that {
     self.class == Namespace
   }.and {!respond_to? :rdoc_example
   }.and { respond_to? :namespacing}
-
-  that.initialization.returns 1
-  that.reinitialization.returns 1
 end
 

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: graham
 version: !ruby/object:Gem::Version
-  version: 0.0.3a
-  prerelease: 5
+  version: 0.0.3
+  prerelease: 
 platform: ruby
 authors:
 - feivel jellyfish
@@ -40,9 +40,11 @@ files:
 - lib/graham/pp.rb
 - lib/graham/version.rb
 - lib/graham/dsl.rb
+- lib/graham/test_case.rb
 - Rakefile
 - test/case/control.rb
 - test/case/cases.rb
+- test/case/subject.rb
 - test/unit/arguments.rb
 - test/unit/namespaces.rb
 homepage: http://github.com/gwentacle/graham
@@ -60,9 +62,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -73,5 +75,6 @@ test_files:
 - Rakefile
 - test/case/control.rb
 - test/case/cases.rb
+- test/case/subject.rb
 - test/unit/arguments.rb
 - test/unit/namespaces.rb