exemplor 2010.0.2 → 2010.1.0

data/README

@@ -6,20 +6,20 @@ An example-based test framework inspired by [testy](http://github.com/ahoward/te
 Simpler that BDD/TDD, fancier than a file with a bunch of print statements.
 
 Very tiny api. Here it is
-    
+
     eg.helpers do
       ... your helpers ...
     end
-    
+
     eg.setup { ... setup codez ... }
-      
+
     eg "an example" do
       ... example code ...
     end
-    
+
     eg "another example" do
       ... etc ...
-    end                                      
+    end
 
 The output is both human readable and machine parsable, which means you can test your tests.
 
@@ -29,29 +29,29 @@ Writing Examples
 See `examples.rb` and `/examples` for more examples.
 
 The simplest possible example:
-                                
+
     eg 'An example block without any checks prints the value of the block' do
       "foo"
     end
-    
+
     #=>
-    
+
     (i) An example block without any checks prints the value of the block: foo
 
 The 'i' stands for 'info' which means the example ran without error.
 
 Inspecting a few values, by default `Check` prints its argument and the value of the argument:
-                                
+
     eg 'Accessing different parts of an array' do
       list = [1, 2, 3]
       Check(list.first)
       Check(list[1])
       Check(list.last)
     end
-    
+
     #=>
-    
-    (I) Accessing different parts of an array: 
+
+    (I) Accessing different parts of an array:
       (i) list.first: 1
       (i) list[1]: 2
       (i) list.last: 3
@@ -66,31 +66,31 @@ Calls to `Check` with the same argument can be disambiguated with `[]`:
       list << 2
       Check(list.last)["after append"]
     end
-    
+
     #=>
-    
-    (I) Array appending: 
+
+    (I) Array appending:
       (i) list.last before append: 42
       (i) list.last after append: 2
 
 Errors are caught and reported nicely:
-    
+
     eg 'Raising an error' do
-      raise "boom!"    
+      raise "boom!"
     end
 
     #=>
 
-    (e) Raising an error: 
+    (e) Raising an error:
       class: RuntimeError
       message: boom!
-      backtrace: 
+      backtrace:
       - examples/an_error.rb:4
       # ... more backtrace lines
 
 Once you're happy with how your code is running you can make some assertions about its behaviour by adding `is()` calls after your `Check()` statements:
-    
-    
+
+
     eg 'Asserting first is first' do
       list = [1, 2, 3]
       Check(list.first).is(1)
@@ -98,7 +98,7 @@ Once you're happy with how your code is running you can make some assertions abo
 
     #=>
 
-    (s) Asserting first is first: 
+    (s) Asserting first is first:
       (s) list.first: 1
 
 's' stands for 'success' and 'f' for failure:
@@ -110,8 +110,8 @@ Once you're happy with how your code is running you can make some assertions abo
 
     #=>
 
-    (f) Assertion failure: 
-      (f) list.first: 
+    (f) Assertion failure:
+      (f) list.first:
         expected: 2
         actual: 1
 
@@ -138,15 +138,15 @@ Running with `--list` or `-l` lists all examples:
     - called with some other arg (always interpreted as a regex)
 
 Otherwise the first argument is taken as a regex and only examples whose titles match are run:
-    
+
     $> ruby examples.rb called
-    (s) called with --list arg: 
-      (s) list: 
+    (s) called with --list arg:
+      (s) list:
       - Modified env
       - Unmodified env
-    (s) called with --l arg: 
-      (s) list: 
+    (s) called with --l arg:
+      (s) list:
       - Modified env
       - Unmodified env
-    (s) called with some other arg (always interpreted as a regex): 
+    (s) called with some other arg (always interpreted as a regex):
       (s) tests_run: 1

data/VERSION

@@ -1 +1 @@
-2010.0.2
+2010.1.0

data/examples/assertion_success_and_failure.rb

@@ -4,7 +4,7 @@ eg 'Some successes, then a fail' do
   list = [1, 2, 3]
   Check(list.first).is(1)
   Check(list[1]).is(2)
-  Check(list.last).is(1)
+  Check(list.last).is(1) # fail!
   Check(list[2]).is(3) # would be successful but we never get here
 end
 

data/examples/assertion_success_and_info.rb

@@ -10,8 +10,8 @@ end
 
 __END__
 
-- name: Some successes, then a fail
-  status: failure
+- name: Some successes, then an info
+  status: info (with checks)
   result: 
   - name: list.first
     status: success

data/lib/checker.rb

@@ -0,0 +1,39 @@
+module Exemplor
+  class Check
+
+    attr_reader :expectation, :value, :status
+
+    def initialize(name, value)
+      @name  = name
+      @value = value
+      @status = :info
+    end
+
+    def [](disambiguate)
+      @disambiguate = disambiguate
+      self
+    end
+
+    def name
+      @name + (defined?(@disambiguate) ? " #{@disambiguate}" : '')
+    end
+
+    def is(expectation)
+      @expectation = expectation
+      @status = (value == expectation) ? :success : :failure
+    end
+
+    def success?
+      status == :success
+    end
+
+    def failure?
+      status == :failure
+    end
+
+    def info?
+      status == :info
+    end
+
+  end
+end

data/lib/command.rb

@@ -0,0 +1,9 @@
+# takes an array of command line arguments
+def Exemplor(args)
+  args = args.dup
+  if args.delete('--list') || args.delete('-l')
+    Exemplor.examples.list(args)
+  else
+    exit Exemplor.examples.run(args)
+  end
+end

data/lib/environment.rb

@@ -0,0 +1,113 @@
+module Exemplor
+
+  class ExampleEnv
+
+    class << self
+
+      alias_method :helpers, :class_eval
+      attr_accessor :setup_block
+
+      def setup(&blk) self.setup_block = blk end
+
+      # runs the block in the example environment, returns triple:
+      # [status, result, stderr]
+      def run(&code)
+        env = self.new
+        stderr = fake_stderr!
+        status, result = begin
+
+          env.instance_eval(&self.setup_block) if self.setup_block
+          value = env.instance_eval(&code)
+          result = env._status == :info ?
+            render_value(value) : render_checks(env._checks)
+          [env._status, result]
+
+        rescue Object => error
+          [:error, render_error(error)]
+        ensure
+          restore_stderr!
+        end
+        [status, result, stderr.rewind && stderr.read]
+      end
+
+      # tests are run with a fake stderr so warnings output can be assoicated
+      # with the specific test. this is still a little hokey and hard to test
+      # properly
+      def fake_stderr!
+        fake = StringIO.new
+        @real_stderr = $stderr
+        $stderr = fake
+      end
+
+      def restore_stderr!
+        $stderr = @real_stderr
+      end
+
+      # -- these "render" methods could probably be factored away
+
+      # yaml doesn't want to print a class
+      def render_value(value)
+        value.kind_of?(Class) ? value.inspect : value
+      end
+
+      def render_checks(checks)
+        failure = nil
+        out = []
+        checks.each do |check|
+          failure = check if check.failure?
+          break if failure
+          out << OrderedHash do |o|
+            o['name'] = check.name
+            o['status'] = check.status.to_s
+            o['result'] = render_value check.value
+          end
+        end
+        if failure
+          out << OrderedHash do |o|
+            o['name'] = failure.name
+            o['status'] = failure.status.to_s
+            o['expected'] = failure.expectation
+            o['actual'] = render_value failure.value
+          end
+        end
+        out
+      end
+
+      def render_error(error)
+        OrderedHash do |o|
+          o['class'] = error.class.name
+          o['message'] = error.message
+          o['backtrace'] = error.backtrace
+        end
+      end
+
+    end
+
+    attr_accessor :_checks
+
+    def initialize
+      @_checks = []
+    end
+
+    def Check(value)
+      file, line_number = caller.first.match(/^(.+):(\d+)/).captures
+      line = File.readlines(file)[line_number.to_i - 1].strip
+      name = line[/Check\((.+?)\)\s*($|#|\[|\.is.+)/,1]
+      check = Check.new(name, value)
+      _checks << check
+      check
+    end
+
+    def _status
+      (:info    if _checks.empty?) ||
+      (:failure if _checks.any? { |c| c.failure? }) ||
+      (:success if _checks.all? { |c| c.success? }) ||
+       :infos
+    end
+
+  end
+
+  def environment
+    ExampleEnv
+  end
+end

data/lib/examples.rb

@@ -0,0 +1,62 @@
+module Exemplor
+
+  def examples
+    @examples ||= Examples.new
+  end
+
+  # sets @example_file to first file that calls the `eg` method
+  def set_example_file_from(caller_trace)
+    @example_file ||= caller_trace.first.split(":").first
+  end
+
+  def example_file_set?
+    !!@example_file
+  end
+
+  def run_directly?
+    @example_file == $0
+  end
+
+  class ExampleDefinitionError < StandardError ; end
+
+  def make_example_name_from(caller_trace)
+    file, line_number = caller_trace.first.match(/^(.+):(\d+)/).captures
+    line = File.readlines(file)[line_number.to_i - 1].strip
+    name = line[/^eg\s*\{\s*(.+?)\s*\}$/,1]
+    raise Exemplor::ExampleDefinitionError, "example at #{caller_trace.first} has no name so must be on one line" if name.nil?
+    name
+  end
+
+  class Examples
+
+    def initialize
+      @examples = OrderedHash.new
+    end
+
+    def add(name, &body)
+      @examples[name] = body
+    end
+
+    def run(patterns)
+      fails = 0
+      # unoffically supports multiple patterns
+      patterns = Regexp.new(patterns.join('|'))
+      examples_to_run = @examples.select { |name,_| name =~ patterns }
+      return 0 if examples_to_run.empty?
+      examples_to_run.each do |name, code|
+        result = ResultPrinter.new(name, *ExampleEnv.run(&code))
+        fails +=1 if result.failure?
+        puts($stdout.tty? ? result.fancy : result.yaml)
+      end
+      (fails.to_f/examples_to_run.size)*100
+    end
+
+    def list(patterns)
+      patterns = Regexp.new(patterns.join('|'))
+      list = @examples.keys.select { |name| name =~ patterns }
+      print YAML.without_header(list)
+    end
+
+  end
+
+end

data/lib/exemplor.rb

@@ -1,305 +1,67 @@
+# -- Implementation
+
 require 'orderedhash'
 require 'yaml'
 
-def OrderedHash(&blk)
-  ohsh = OrderedHash.new
-  blk.call(ohsh)
-  ohsh
-end
-
-def YAML.without_header(obj)
-  obj.to_yaml.match(/^--- \n?/).post_match
-end
-
-class String
-  def indent
-    self.split("\n").map { |line| '  ' + line }.join("\n")
-  end
-end
-
 module Exemplor
 
-  def self.version() File.read(__FILE__.sub('lib/exemplor.rb','VERSION')) end
-
-  class ExampleDefinitionError < StandardError ; end
-
-  class Check
-
-    attr_reader :expectation, :value
-
-    def initialize(name, value)
-      @name  = name
-      @value = value
-    end
-
-    def [](disambiguate)
-      @disambiguate = disambiguate
-      self
-    end
-
-    def name
-      @name + (defined?(@disambiguate) ? " #{@disambiguate}" : '')
-    end
-
-    def is(expectation)
-      @expectation = expectation
-    end
-
-    def status
-      return :info unless defined? @expectation
-      @value == @expectation ? :success : :failure
-    end
-
-    def success?
-      status == :success
-    end
-
-    def failure?
-      status == :failure
-    end
-
-    def info?
-      status == :info
-    end
+  extend self
 
+  def path(rel_path)
+    File.join(File.dirname(__FILE__), rel_path)
   end
 
-  class ResultPrinter
-
-    attr_reader :name,:status,:result,:stderr
-
-    def initialize(name,status,result,stderr)
-      @name,@status,@result,@stderr = name,status,result,stderr
-    end
-
-    def failure?
-      [:error,:failure].include?(self.status)
-    end
-
-    def yaml
-      hsh = OrderedHash do |o|
-        o['name'] = self.name
-        o['status'] = case status = self.status
-          when :info  : 'info (no checks)'
-          when :infos : 'info (with checks)'
-          else ; status.to_s
-        end
-        o['result'] = self.result
-      end
-      YAML.without_header([hsh])# prints an array
-    end
-
-    def fancy
-      # •∙ are inverted in my terminal font (Incosolata) so I'm swapping them
-      require 'term/ansicolor'
-      case status
-      when :info : blue format_info("• #{name}", result)
-      when :infos
-        formatted_result = result.map do |r|
-          # TODO: successful ones should be green
-          format_info("#{{'success' => '✓', 'info' => '•' }[r['status']]} #{r['name']}", r['result']).rstrip
-        end.join("\n")
-        blue("∙ #{name}\n#{formatted_result.indent}")
-      when :success
-        green("✓ #{name}")
-      when :failure
-        # sooo hacky
-        failure = result.find { |r| r['status'] == 'failure' }
-        out = failure.dup
-        out.delete('status')
-        out.delete('name')
-        color(:red,  "✗ #{name} - #{failure['name']}\n#{YAML.without_header(out).indent}")
-      when :error
-        class_and_message = "#{result['class']} - #{result['message']}"
-        backtrace = result['backtrace'].join("\n")
-        color(:red, "☠ #{name}\n#{class_and_message.indent}\n#{backtrace.indent}")
-      end
-    end
-
-    def blue(str) color(:blue,str) end
-    def green(str) color(:green,str) end
-
-    def color(color, str)
-      [Term::ANSIColor.send(color), str, Term::ANSIColor.reset].join
-    end
-
-    # whatahack
-    def format_info(str, result)
-      YAML.without_header({'FANCY' => result}).sub('FANCY', str)
-    end
-
+  def version
+    File.read(path('/../VERSION'))
   end
 
-  class ExampleEnv
-
-    class << self
-
-      alias_method :helpers, :class_eval
-      attr_accessor :setup_block
-
-      def setup(&blk) self.setup_block = blk end
-
-      # runs the block in the example environment, returns triple:
-      # [status, result, stderr]
-      def run(&code)
-        env = self.new
-        stderr = StringIO.new
-        status, result = begin
-          real_stderr = $stderr ; $stderr = stderr # swap stderr
-
-          env.instance_eval(&self.setup_block) if self.setup_block
-          value = env.instance_eval(&code)
-          result = env._status == :info ?
-            render_value(value) : render_checks(env._checks)
-          [env._status, result]
-
-        rescue Object => error
-          [:error, render_error(error)]
-        ensure
-          $stderr = real_stderr # swap stderr back
-        end
-        [status, result, stderr.rewind && stderr.read]
-      end
-
-      # -- these "render" methods could probably be factored away
-
-      # yaml doesn't want to print a class
-      def render_value(value)
-        value.kind_of?(Class) ? value.inspect : value
-      end
-
-      def render_checks(checks)
-        failure = nil
-        out = []
-        checks.each do |check|
-          failure = check if check.failure?
-          break if failure
-          out << OrderedHash do |o|
-            o['name'] = check.name
-            o['status'] = check.status.to_s
-            o['result'] = render_value check.value
-          end
-        end
-        if failure
-          out << OrderedHash do |o|
-            o['name'] = failure.name
-            o['status'] = failure.status.to_s
-            o['expected'] = failure.expectation
-            o['actual'] = render_value failure.value
-          end
-        end
-        out
-      end
-
-      def render_error(error)
-        OrderedHash do |o|
-          o['class'] = error.class.name
-          o['message'] = error.message
-          o['backtrace'] = error.backtrace
-        end
-      end
-
-    end
-
-    attr_accessor :_checks
-
-    def initialize
-      @_checks = []
-    end
-
-    def Check(value)
-      file, line_number = caller.first.match(/^(.+):(\d+)/).captures
-      line = File.readlines(file)[line_number.to_i - 1].strip
-      name = line[/Check\((.+?)\)\s*($|#|\[|\.is.+)/,1]
-      check = Check.new(name, value)
-      _checks << check
-      check
-    end
-
-    def _status
-      (:info    if _checks.empty?) ||
-      (:failure if _checks.any? { |c| c.failure? }) ||
-      (:success if _checks.all? { |c| c.success? }) ||
-       :infos
-    end
-
-  end
-
-  class Examples
-
-    def initialize
-      @examples = OrderedHash.new
-    end
-
-    def add(name, &body)
-      @examples[name] = body
-    end
-
-    def run(patterns)
-      fails = 0
-      # unoffically supports multiple patterns
-      patterns = Regexp.new(patterns.join('|'))
-      examples_to_run = @examples.select { |name,_| name =~ patterns }
-      return 0 if examples_to_run.empty?
-      examples_to_run.each do |name, code|
-        result = ResultPrinter.new(name, *ExampleEnv.run(&code))
-        fails +=1 if result.failure?
-        puts($stdout.tty? ? result.fancy : result.yaml)
-      end
-      (fails.to_f/examples_to_run.size)*100
-    end
-
-    def list(patterns)
-      patterns = Regexp.new(patterns.join('|'))
-      list = @examples.keys.select { |name| name =~ patterns }
-      print YAML.without_header(list)
-    end
-
-  end
-
-  class << self
-
-    def examples
-      @examples ||= Examples.new
-    end
-
-    def extract_example_file(caller_trace)
-      @example_file ||= caller_trace.first.split(":").first
-    end
-
-    # attr_reader :example_file
+end
 
-    def run_directly?
-      @example_file == $0
-    end
+require Exemplor.path('/ext')
+require Exemplor.path('/checker')
+require Exemplor.path('/result_printer')
+require Exemplor.path('/environment')
+require Exemplor.path('/examples')
+require Exemplor.path('/command')
+
+# -- Public API
+
+# Interface for defining examples and configuring their environment.
+#
+# To define an example call eg with a name and block
+#
+#   eg "yellling" do
+#     "hi".capitalize
+#   end
+#
+# `eg` can be called without a name if the entire call is on one line, in
+# that case the code in the example is used as its name:
+#
+#   eg { the_duck_swims_in_the_pond }
+#   same as:
+#   eg("the_duck_swims_in_the_pond") { the_duck_swims_in_the_pond }
+#
+# Call `eg` without args to configure the examples enviornment:
+#
+#   eg.setup do
+#     # code here will run before each example
+#   end
+#
+#   eg.helpers do
+#     # methods defined here can be called from inside an example
+#   end
+#
+def eg(name = nil, &example)
+  called_without_args = name.nil? && example.nil?
+  return Exemplor.environment if called_without_args
 
-  end
+  Exemplor.set_example_file_from caller unless Exemplor.example_file_set?
 
-end
+  called_without_explicit_name = name.nil? && !example.nil?
+  name = Exemplor.make_example_name_from caller if called_without_explicit_name
 
-# Defines an example. After definition, an example is an entry in the
-# Examples.examples ordered hash, the key is the name, the body is the example
-# code
-def eg(name = nil, &example)
-  return Exemplor::ExampleEnv if name.nil? && example.nil?
-  Exemplor.extract_example_file caller # only runs once
-  if name.nil?
-     file, line_number = caller.first.match(/^(.+):(\d+)/).captures
-     line = File.readlines(file)[line_number.to_i - 1].strip
-     name = line[/^eg\s*\{\s*(.+?)\s*\}$/,1] if name.nil?
-     raise Exemplor::ExampleDefinitionError, "example at #{caller.first} has no name so must be on one line" if name.nil?
-  end
   Exemplor.examples.add(name, &example)
 end
 
-# Parses the command line args and either runs or lists the examples.
-at_exit do
-  if Exemplor.run_directly?
-    args = ARGV.dup
-    if args.delete('--list') || args.delete('-l')
-      Exemplor.examples.list(args)
-    else
-      exit Exemplor.examples.run(args)
-    end
-  end
-end
+# Command line interface
+at_exit { Exemplor(ARGV) if Exemplor.run_directly? }

data/lib/ext.rb

@@ -0,0 +1,15 @@
+def OrderedHash(&blk)
+  ohsh = OrderedHash.new
+  blk.call(ohsh)
+  ohsh
+end
+
+def YAML.without_header(obj)
+  obj.to_yaml.match(/^--- \n?/).post_match
+end
+
+class String
+  def indent
+    self.split("\n").map { |line| '  ' + line }.join("\n")
+  end
+end

data/lib/result_printer.rb

@@ -0,0 +1,67 @@
+module Exemplor
+  class ResultPrinter
+
+    attr_reader :name,:status,:result,:stderr
+
+    def initialize(name,status,result,stderr)
+      @name,@status,@result,@stderr = name,status,result,stderr
+    end
+
+    def failure?
+      [:error,:failure].include?(self.status)
+    end
+
+    def yaml
+      hsh = OrderedHash do |o|
+        o['name'] = self.name
+        o['status'] = case status = self.status
+          when :info  : 'info (no checks)'
+          when :infos : 'info (with checks)'
+          else ; status.to_s
+        end
+        o['result'] = self.result
+      end
+      YAML.without_header([hsh])# prints an array
+    end
+
+    def fancy
+      # •∙ are inverted in my terminal font (Incosolata) so I'm swapping them
+      require 'term/ansicolor'
+      case status
+      when :info : blue format_info("• #{name}", result)
+      when :infos
+        formatted_result = result.map do |r|
+          # TODO: successful ones should be green
+          format_info("#{{'success' => '✓', 'info' => '•' }[r['status']]} #{r['name']}", r['result']).rstrip
+        end.join("\n")
+        blue("∙ #{name}\n#{formatted_result.indent}")
+      when :success
+        green("✓ #{name}")
+      when :failure
+        # sooo hacky
+        failure = result.find { |r| r['status'] == 'failure' }
+        out = failure.dup
+        out.delete('status')
+        out.delete('name')
+        color(:red,  "✗ #{name} - #{failure['name']}\n#{YAML.without_header(out).indent}")
+      when :error
+        class_and_message = "#{result['class']} - #{result['message']}"
+        backtrace = result['backtrace'].join("\n")
+        color(:red, "☠ #{name}\n#{class_and_message.indent}\n#{backtrace.indent}")
+      end
+    end
+
+    def blue(str) color(:blue,str) end
+    def green(str) color(:green,str) end
+
+    def color(color, str)
+      [Term::ANSIColor.send(color), str, Term::ANSIColor.reset].join
+    end
+
+    # whatahack
+    def format_info(str, result)
+      YAML.without_header({'FANCY' => result}).sub('FANCY', str)
+    end
+
+  end
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 2010
+  - 1
   - 0
-  - 2
-  version: 2010.0.2
+  version: 2010.1.0
 platform: ruby
 authors: 
 - Myles Byrne
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-27 00:00:00 -05:00
+date: 2010-03-31 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,7 +77,13 @@ files:
 - examples/ten_percent_failures.rb
 - examples/with_checks.rb
 - examples/with_setup.rb
+- lib/checker.rb
+- lib/command.rb
+- lib/environment.rb
+- lib/examples.rb
 - lib/exemplor.rb
+- lib/ext.rb
+- lib/result_printer.rb
 has_rdoc: true
 homepage: http://github.com/quackingduck/exemplor
 licenses: []