assay 0.3.0 → 0.4.0

data/README.rdoc

@@ -1,5 +1,11 @@
 = Assay
 
+{Website}[http://rubyworks.github.com/assay] /
+{Report Issue}[http://github.com/rubyworks/assay/issues] /
+{Source Code}[http://github.com/rubyworks/assay] /
+{Mailing List}[http://groups.google.com/group/rubyworks-mailinglist]
+
+
 == DESCRIPTION
 
 Assay defines assertions in the same way that Ruby defines
@@ -8,26 +14,21 @@ extended Exception class. Assay provides a complete set
 of these assertion classes for the most common assertion types.
 It also provides both TestUnit-style assertion methods and
 RSpec-compatiable matchers built from these assertion classes
-for use in your preferred test harness. Assay works with
+for use in your preferred test harness. Assay is compatible with
 TestUnit, MiniTest, RSpec and other test frameworks.
 
 
 == FEATURES
 
-* Mirrors the Ruby Exception system.
-* Assertions get their own specialized error messages.
-
-
-== RESOURCES
+* Patterned after the Ruby exception system.
+* Allows assertions specialized error messages.
+* Supports any variety of assertion "grammers".
+* Can be used with almost any test framework. 
 
-* home: http://rubyworks.github.com/assay
-* code: http://github.com/rubyworks/assay
-* mail: http://groups.google.com/group/rubyworks-mailinglist
 
+== LIMITATIONS
 
-== SYNOPSIS
-
-See QED documentation.
+* Assay is Ruby 1.9+ only!
 
 
 == INSTALLATION
@@ -40,11 +41,133 @@ Site installation with the tarball can be done with Ruby Setup
 (gem install setup). See http://rubyworks.github.com/setup.
 
 
-== COPYING
+== UTILIZATION
+
+=== Assay Classes
+
+Assay consists of a set of Assertion subclasses known as *assays*. They
+are akin to Ruby's Exception subclasses, indeed the +Assertion+ base class
+is a subclass of Exception. But assays have special class methods that are
+used to make assertions.
+
+Consider the +EqualityAssay+ class. It defines methods for asserting equality
+via the `#==` method.
+
+  EqualityAssay.assert!(1,1)
+
+Additionally, we can check the assertion's test without actually raising the
+assertion if it fails using the query method.
+
+  EqualityAssay.pass?(1,1)    #=> true
+
+Assays also provide the opposite method `#refute!` along with `#fail?`.
+
+  EqualityAssay.refute!(1,2)
+
+  EqualityAssay.fail?(1,2)    #=> true
+
+Assay instances are test matchers, which can be conveniently defined with `#[]`.
+
+  EqualityAssay[1] =~ 1
+
+Notice in the example we have used `#=~` to apply the matcher which makes
+the `#assert!` call to the Assay object. Likewise `#!~` can be used to
+call `#refute!` instead. And note that `#===` is also an alias for `#=~`.
+
+  EqualityAssay[1] === 1
+
+Which means assay matchers can be used in case statments.
+
+  case 10
+  when InstanceAssay[Fixnum]
+  when EqualityAssay[10.0]
+  end
+
+Pretty neat.
+
+=== Framework Adapters
+
+Assay follows a standard practice of defining assertion error classes with
+an `#assertion?` method that returns +true+. This can be used by any test 
+framework to easily detect when a raised error is an assertion rather than
+an ordinary error. To add support for this to common test frameworks Assay
+provides adapters.
+
+For example, to use assay with MiniTest framework add to your test helper
+script:
+
+  require 'assay/adapter/minitest'
+
+Likewise for TestUnit.
+
+  require 'assay/adapter/testunit'
+
+An RSpec adadpter is in the works, and should be out with the next release.
+
+Note that even without the adapter, you can still use Assay with other test
+frameworks. They will simply count Assay's assertions as regular errors.
+
+=== Customized Grammars
+
+Of course the classes are interesting and clearly make for a sound foundation,
+but in the end we want to write assertions more easily and concisely. For this
+we turn to separate "grammar" projects that depend on Assay's classes. The
+first of these, created as a spin-off project to demonstrate Assay's prowess,
+is {Fluidity}[http://rubyworks.github.com/fluidity]. Here is a quick taste of
+that gem's functionality.
+
+  require 'fluidity'
+
+  10.should.be.kind_of(Integer)
+
+But is you are acustom to MiniTest's spec methods, you might prefer `must`.
+
+  10.must.be.kind_of(Integer)
+
+And to satisfy all those technical aficionados (like yours truly) there is `assert`.
+
+  10.assert.kind_of(Integer)
+
+Thre are also compatibility grammar projects available, spun-off from Assay, that
+provide compatability with legacy test frameworks which can serve as transition
+to Assay from these other frameworks. Follow the links below for each:
+
+* {Assay TestUnit}[http://github.com/rubyworks/assay-testunit]
+* {Assay MiniTest}[http://github.com/rubyworks/assay-minitest]
+* {Assay RSpec}[http://github.com/rubyworks/assay-rspec]
+
+Usage is essentially the same for any one of them. For example,
+
+  require 'assay/rspec'
+
+  include Assay::Matchers
+
+  10.should be_kind_of(Integer)
+
+Note that the compatibility modules are not yet 100% compatable, lacking some
+of the more esoteric and complex features. But they are very nearly so, and
+will become more so in time.
+
+These are just a few possible grammars. There is no reason not to build
+your own grammar on top of Assay's classes if you have another approach in mind.
+Indeed, please do! That, after all, is the main purpose of having such
+a set of reusable assertion classes!
+
+=== Learning More
+
+There's more learn about Assay, mainly the variety of assay classes available,
+but also a few other bits of functionality not comvered here. To learn
+about these check out the {QED documentation}[http://github.com/rubyworks/assay]
+which provides an overiew of functionality with working examples, and the
+the {API documentation}[http://rubydoc.info/gems/asasy] for a more in depth look
+under the hood.
+
+
+== COPYRIGHTS
 
-Copyright (c) 2009 Thomas Sawyer
+Copyright (c) 2009 Rubyworks
 
-This program is ditributed under the terms of the Apache 2.0 license.
+This program is ditributed under the terms of the *BSD-2-Cluase* license.
 
-See NOTICE.rdoc and APACHE2.txt file for details.
+See COPYING.rdoc file for details.
 

data/lib/assay.rb

@@ -1,44 +1,97 @@
-module Assay
-  #VERSION="1.0.0"
-
-  # Returns a Hash table of failure classes indexed by
-  # asserton operator.
-  def self.failure_classes_by_operator
-    @_failure_classes_by_operator ||= (
-      c = {}
-      ObjectSpace.each_object(Class) do |fc|
-        next unless fc < Assay::Assertion
-        if fc.respond_to?(:assertion_operator)
-          c[fc.assertion_operator.to_sym] = fc
-        end
-      end
-      c
-    )
-  end
+# Load Assay's assertion classes.
+require_relative 'assay/assertion'
+dir = File.dirname(__FILE__) + '/assay'
+Dir.entries(dir).each do |file|
+  next if File.extname(file) != '.rb'
+  require_relative 'assay/' + file
+end
 
-  # Lookup failure class by operator.
-  def self.lookup(operator)
-    failure_classes_by_operator[operator.to_sym]
-  end
+module Assay
 
+  #
   # Returns Hash table of project metadata.
-  def self.meta
+  #
+  def self.metadata
     @spec ||= (
       require 'yaml'
       YAML.load(File.new(File.dirname(__FILE__) + '/assay.yml'))
     )
   end
 
+  #
   # Check metadata for missing constants.
+  #
   def self.const_missing(name)
-    meta[name.to_s.downcase] || super(name)
+    metadata[name.to_s.downcase] || super(name)
   end
-end
 
-# Load Assay's failure classes.
-dir  = File.dirname(__FILE__)
-glob = File.join(dir, 'assay', 'assertions', '*.rb')
-Dir[glob].each do |rb|
-  require 'assay/assertions/' + File.basename(rb)
+  #
+  # Returns a list of Assertion subclasses.
+  #
+  def self.assertions
+    Assertion.subclasses
+  end
+
+  #
+  # Set ANSI color mode. Default is false, so set to `true` to get ANSI color
+  # in some error messages.
+  #
+  # @example
+  #   Assay.color = true
+  #
+  def self.color=(boolean)
+    if boolean
+      require 'ansi/diff'
+      $ansi = true
+    else
+      $ansi = false
+    end 
+  end
+
+  #
+  # Lookup assay class by operator or name.
+  #
+  def self.lookup(symbol)
+    lookup_by_operator(symbol) || lookup_by_name(symbol)
+  end
+
+  #
+  # If operator is not given, returns a hash table of assertion classes
+  # indexed by operator.
+  #
+  def self.lookup_by_operator(operator=nil)
+    Assertion.by_operator(operator)
+  end
+
+  #
+  # If operator is not given, returns a hash table of assertion classes
+  # indexed by assertive name.
+  #
+  def self.lookup_by_name(name=nil)
+    Assertion.by_name(name)
+  end
+
+  # This module serves as the primary container for traditonal style assertion
+  # methods, which can be mixed in to one's testing scope (e.g. World).
+  #
+  module Assertions
+  end
+
+  # This module holds the subject matcher methods, which can be mixin
+  # to one's testing scope (e.g. World).
+  #
+  module Matchers
+  end
+
+  # This module holds the assertion extension mehods, which are mixed into
+  # the Object class.
+  #
+  module Extensions
+  end
+
+  #class ::Object
+  #  include Assay::Extensions
+  #end
+
 end
 

data/lib/assay.yml

@@ -1,44 +1,49 @@
---- 
-spec_version: 1.0.0
-replaces: []
-
-loadpath: 
-- lib
-name: assay
-repositories: {}
-
-conflicts: []
-
-engine_check: []
-
-title: Assay
-resources: 
-  code: http://github.com/rubyworks/assay
-  docs: http://rubydoc.info/gems/assay
-  home: http://rubydoc.info/gems/assay
-maintainers: []
-
-requires: 
-- group: []
-
-  name: ansi
-  version: ">=1.2.5"
-- group: 
+---
+source:
+- meta
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+copyrights:
+- holder: Thomas Sawyer
+  year: '2009'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: ansi
+- name: brass
+- name: detroit
+  groups:
   - build
-  name: redline
-  version: 0+
-- group: 
+  development: true
+- name: qed
+  groups:
   - test
-  name: qed
-  version: 0+
-suite: rubyworks
-manifest: MANIFEST.txt
-version: 0.2.0
-licenses: 
-- Apache 2.0
-copyright: Copyright (c) 2007 Thomas Sawyer
-authors: 
-- Thomas Sawyer
-description: The Assay project defines Assertions in the same way that Ruby defines Exceptions. An asserition then simply becomes an extension to an Exception class.
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git@github.com:rubyworks/assay.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubydoc.info/gems/assay
+  docs: http://rubydoc.info/gems/assay
+  code: http://github.com/rubyworks/assay
+  mail: http://groups.google.com/groups/rubyworks-mailinglist
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2009-08-21'
 summary: Class-based Assertions Framework
-created: 2009-08-21
+title: Assay
+version: 0.4.0
+name: assay
+description: ! 'The Assay project defines Assertions in the same way that Ruby defines
+  Exceptions.
+
+  An asserition then simply becomes an extension to an Exception class.'
+organization: Rubyworks
+date: '2012-01-25'

data/lib/assay/assertable.rb

@@ -0,0 +1,174 @@
+require_relative 'assertor'
+
+module Assay
+
+  module Assertable
+
+    $ASSERTION_COUNTS ||= Hash.new{ |h,k| h[k] = 0 } #{:total=>0,:pass=>0,:fail=>0}
+
+    #
+    # When displaying errors, use this as a rule of thumb
+    # for determining when the inspected object will be too
+    # big for a single line message.
+    #
+    SIZE_LIMIT = 13
+
+    # TODO: There's really no point to the defaults for #operator and
+    #       assertive name b/c `register` is now reauired which set them.
+    #       But that's in Assertion not Assertable, so something's not quite
+    #       right in that regard.
+
+    #
+    # If the assertion coresponds to a regular method, particular a symbolic
+    # operator (hence the name of this method) then it should be specified via
+    # this interface. Otherwise, it should be given a fitting "make believe"
+    # method name and specified here. If not overridden it will be assumed
+    # to be the same as the `assertion_name` appended by `?`.
+    #
+    def operator
+      @operator ||= (name.split('::').last.chomp('Assay').downcase + '?').to_sym
+    end
+
+    #
+    # The assertive name is used for the construction of assertive nomenclatures
+    # such as `assert_equal`.
+    # 
+    def assertive_name
+      @assertive_name ||= (
+        if operator.to_s.end_with?('?')
+          operator.to_s.chomp('?').to_sym
+        else
+          name.split('::').last.chomp('Assay').downcase.to_sym
+        end
+      )
+    end
+
+    #
+    # Create an assertor for the assay class, given +criteria+.
+    #
+    def assertor(*criteria, &block)
+      Assertor.new(self, *criteria, &block)
+    end
+
+    #
+    # Alias for `#assertor`.
+    #
+    def [](*criteria, &block)
+      assertor(*criteria, &block)
+    end
+
+    #
+    # Check the assertion, return `true` if passing, `false` otherwise.
+    #
+    def pass?(subject, *criteria, &block)
+      subject 
+    end
+
+    #
+    # Check the assertion, return `true` if failing, `false` otherwise.
+    #
+    def fail?(subject, *criteria, &block)
+      ! pass?(subject, *criteria, &block)
+    end
+
+    #
+    # Test the assertion, raising the exception if failing.
+    #
+    def assert!(*arguments, &block)
+      options = (Hash === arguments.last ? arguments.pop : {})
+
+      backtrace = options[:backtrace] || caller
+      message   = options[:message]   || assert_message(*arguments, &block)
+
+      pass = pass?(*arguments, &block)
+
+      assert pass, self, message, backtrace
+
+      #if pass?(*arguments, &block)
+      #  increment(:pass)
+      #else
+      #  increment(:fail)
+      #  fail self, message, backtrace
+      #end
+    end
+
+    #
+    # Test the refutation of the assertion.
+    #
+    # Test the inverse assertion, raising the exception if not failing.
+    #
+    def refute!(*arguments, &block)
+      options = (Hash === arguments.last ? arguments.pop : {})
+
+      backtrace = options[:backtrace] || caller
+      message   = options[:message]   || refute_message(*arguments, &block)
+
+      fail = fail?(*arguments, &block)
+
+      assert fail, self, message, backtrace
+
+      #if fail?(*arguments, &block)
+      #  increment(:pass)
+      #else
+      #  increment(:fail)
+      #  fail self, message, backtrace
+      #end
+    end
+
+    ##
+    ##
+    ##
+    #def get_message(subject, fail=false)
+    #  @not ^ fail ? refute_message(subject) : assert_message(subject)
+    #end
+
+    #
+    #
+    #
+    def assert_message(*arguments, &block)
+      standard_message(*arguments, &block)
+    end
+
+    #
+    #
+    #
+    def refute_message(*arguments, &block)
+      "! " + assert_message(*arguments, &block)
+    end
+
+  private
+
+    ##
+    ## Increment global `$ASSERTION_COUNTS` variable.
+    ##
+    #def increment(which)
+    #  $ASSERTION_COUNTS[:total] += 1
+    #  $ASSERTION_COUNTS[which.to_sym] += 1
+    #end
+
+    #
+    # Construct a standard error message.
+    #
+    def standard_message(*arguments, &block)
+      args_inspect = arguments.map{ |o| o.inspect }
+
+      op = self.operator.to_s
+      op = (/\w/ =~ op) ? ".#{op} " : " #{op} "
+
+      if args_inspect.any?{ |o| o.size > SIZE_LIMIT }
+        vars = ['b']
+        t = args_inspect.size - 2
+        t.times{ vars << vars.last.succ }
+
+        msg = ''   
+        msg << "a#{op} " + vars.join(',') + "\n"
+        msg << args_inspect.join("\n")
+        msg
+      else
+        args_inspect.first + "#{op}" + args_inspect[1..-1].join(', ') + ""
+      end
+    end
+
+  end
+
+end