xspec 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 43babe397ea759864cca9b9cf9f7b3f85574df64
-  data.tar.gz: 9bb1e2521e47fd442469f79c15f5ac0bb785a010
+  metadata.gz: a5dba5d7629f6d87591f9abe883290f50372dc64
+  data.tar.gz: ead15780cdec15272984c1580051e7d7f2eadded
 SHA512:
-  metadata.gz: 4a3278a29ac464e56907888124acf872c5151282718286ee141cd57e933e2b28e15d817c81e20b1a5f29199b2097ba962264190d7df44b604ab974ddfed3e76f
-  data.tar.gz: 652428e1709ecb942d8e858f764489cf5681d40b8b09e4061c9b2814a93f956ddc8df5d48b39fc382b6ec755f455a2c3df8fb4fcf7f93bea7aebdd10b808fb3d
+  metadata.gz: b37433a77450176d0cf1ebeae40d5ad24ef28ce8095887126edfd5dfd0040fdcfbf418a1726862a60eb7f275f347d19a371720331b5376145e256bff08374ef5
+  data.tar.gz: 963b1b472454aeaeb03aa956a1e38ff3a9b1a9bb4bf78fcd8c9eb06aae26a31d4591ed8e7b9a4fa1c11f43a7413a2d37112d2bd140c182145fcadc8745922b91

data/README.md

@@ -1,15 +1,15 @@
 XSpec
 =====
 
-XSpec is an rspec-inspired testing library that is written in a literate style
-and designed to be obvious to use, highly modular, and easy to extend.
-
-Open up `lib/xspec.rb` and start reading, or use this [nicely formatted
-version](http://xaviershay.github.io/xspec/).
+XSpec is an rspec-inspired testing library for Ruby that is written in a
+literate style and designed to be obvious to use, highly modular, and easy to
+extend.
 
 Usage
 -----
 
+    gem install xspec
+
 The default configuration XSpec provides a number of interesting features:
 assertions, doubles, and rich output.
 
@@ -40,7 +40,7 @@ Running this with the built-in runner generates some pretty output. You can't
 see the colors in this README, but trust me they are quite lovely.
 
 ```
-> bin/xspec example.rb
+> xspec example.rb
 
 my application
   0.000s does math
@@ -61,8 +61,7 @@ my application fails:
   bin/xspec:19:in `<main>'
 ```
 
-Customization
--------------
+### Customization
 
 Every aspect of XSpec is customizable, from how tests are scheduled and run all
 the way through to formatting of output.
@@ -86,56 +85,29 @@ describe '...' do
 end
 ```
 
-Of course, you can easily make your own extension classes as well. A runner
-that randomly drops tests and reports random durations? Whatever floats your
-boat:
-
-``` ruby
-require 'xspec'
-
-class UnhelpfulRunner
-  attr_reader :notifier
-
-  def initialize(opts)
-    @notifier = opts.fetch(:notifier)
-  end
-
-  def run(context)
-    notifier.run_start
-
-    context.nested_units_of_work.each do |x|
-      next if rand > 0.9
+Of course, you can make your own extension classes as well. For details, see
+the "Configuration" section of the documentation.
 
-      notifier.evaluate_start(x)
-
-      errors   = x.immediate_parent.execute(x)
-      duration = rand
-      result   = XSpec::ExecutedUnitOfWork.new(x, errors, duration)
+Documentation
+-------------
 
-      notifier.evaluate_finish(result)
-    end
+There are two major sources of documentation:
 
-    notifier.run_finish
-  end
-end
+* [Main API documentation.](https://xaviershay.github.io/xspec/api.html)
+* [Literate source code.](https://xaviershay.github.io/xspec/)
 
-extend XSpec.dsl(
-  evaluator: UnhelpfulRunner.new(notifier: XSpec::Notifier::DEFAULT)
-)
-
-describe '...' do
-  # etc etc
-end
-```
+It is expected that regular users of XSpec will read both at least once. There
+isn't much to them, and they will give you a useful mental model of how XSpec
+works.
 
 Developing
 ----------
 
 Follow the idioms you find in the source, they are somewhat different than
-a traditional Ruby project. Bug fixes welcome, features likely to be rejected
-since I have a strong opinion of what this library should and should not do.
-Talk to me before embarking on anything large. Tests are written in XSpec,
-which might do your head in:
+a traditional Ruby project. Bug fixes welcome, though features are likely to be
+rejected since I have a strong opinion of what this library should and should
+not do. Talk to me before embarking on anything large. Tests are written in
+XSpec, which might do your head in:
 
     bundle install
-    bin/test
+    bundle exec bin/xspec

data/bin/xspec

@@ -1,5 +1,9 @@
 #!/usr/bin/env ruby
 
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+require 'xspec'
+
 $LOAD_PATH.unshift "spec"
 $LOAD_PATH.unshift "lib"
 
@@ -9,8 +13,6 @@ else
   Dir['spec/**/*_spec.rb']
 end
 
-require 'xspec'
-
 files.each do |f|
   load f
 end

data/lib/xspec.rb

@@ -16,13 +16,16 @@ module XSpec
     options = XSpec.add_defaults(options)
 
     Module.new do
+      # Each DSL provides a standard set of methods provided by the [DSL
+      # module](dsl.html).
       include DSL
 
-      # Each DSL has its own independent context, which is described in detail
-      # in `data_structures.rb`.
+      # In addition, each DSL has its own independent context, which is
+      # described in detail in the
+      # [`data_structures.rb`](data_structures.html).
       def __xspec_context
-        assertion_context = __xspec_opts.fetch(:assertion_context)
-        @__xspec_context ||= XSpec::Context.root(assertion_context)
+        evaluator = __xspec_opts.fetch(:evaluator)
+        @__xspec_context ||= XSpec::Context.root(evaluator)
       end
 
       # Some meta-magic is needed to enable the options from local scope above
@@ -31,9 +34,12 @@ module XSpec
 
       # `run!` is where the magic happens. Typically called at the end of a
       # file (or by `autorun!`), this method takes all the data that was
-      # accumulated by the DSL methods above and runs it through the evaluator.
+      # accumulated by the DSL methods above and runs it through the scheduler.
       def run!
-        __xspec_opts.fetch(:evaluator).run(__xspec_context)
+        notifier  = __xspec_opts.fetch(:notifier)
+        scheduler = __xspec_opts.fetch(:scheduler)
+
+        scheduler.run(__xspec_context, notifier)
       end
 
       # It is often convenient to trigger a run after all files have been
@@ -49,13 +55,14 @@ module XSpec
   module_function :dsl
 end
 
-# Understanding the data structures used by XSpec will assist you in
-# understanding the behavoural components such as the evaluator and notifier.
+# Understanding the [data structures](data_structures.html) used by XSpec will
+# assist you in understanding the behavoural components such as the scheduler
+# and notifier. Read it next.
 require 'xspec/data_structures'
 
-# To further explore the code base, dive into the defaults file, which
-# describes the different sub-components of XSpec that you can use or
-# customize.
+# To further explore the code base, dive into the [defaults
+# file](defaults.html), which describes the different sub-components of XSpec
+# that you can use or customize.
 require 'xspec/defaults'
 
 require 'xspec/dsl'

data/lib/xspec/data_structures.rb

@@ -7,7 +7,7 @@
 module XSpec
   # A unit of work, usually created by the `it` DSL method, is a labeled,
   # indivisible code block that expresses an assertion about a property of the
-  # system under test. They are run by an evaluator.
+  # system under test. They are run by a scheduler.
   UnitOfWork = Struct.new(:name, :block)
 
 
@@ -20,7 +20,7 @@ module XSpec
   require 'xspec/dsl'
   class Context
     class << self
-      attr_reader :name, :children, :units_of_work, :assertion_context
+      attr_reader :name, :children, :units_of_work, :evaluator
 
       # A context includes the same DSL methods as the root level module, which
       # enables the recursive creation.
@@ -29,33 +29,33 @@ module XSpec
 
       # Each nested context creates a new class that inherits from the parent.
       # Methods can be added to this class as per normal, and are correctly
-      # inherited by children. When it comes time to run tests, the evaluator
+      # inherited by children. When it comes time to run tests, the scheduler
       # will create a new instance of the context (a class) for each test,
       # making the defined methods available and also ensuring that there is no
       # state pollution between tests.
-      def make(name, assertion_context, &block)
+      def make(name, evaluator, &block)
         x = Class.new(self)
-        x.initialize!(name, assertion_context)
+        x.initialize!(name, evaluator)
         x.class_eval(&block) if block
-        x.apply_assertion_context!
+        x.apply_evaluator!
         x
       end
 
       # A class cannot have an implicit initializer, but some variable
       # inititialization is required so the `initialize!` method is called
       # explicitly when ever a dynamic subclass is created.
-      def initialize!(name, assertion_context)
+      def initialize!(name, evaluator)
         @children          = []
         @units_of_work     = []
         @name              = name
-        @assertion_context = assertion_context
+        @evaluator = evaluator
       end
 
       # The assertion context should be applied after the user has had a chance
       # to add their own methods. It needs to be last so that users can't
       # clobber the assertion methods.
-      def apply_assertion_context!
-        include(assertion_context)
+      def apply_evaluator!
+        include(evaluator)
       end
 
       # Executing a unit of work creates a new instance and hands it off to the
@@ -68,14 +68,14 @@ module XSpec
 
       # The root context is nothing special, and behaves the same as all the
       # others.
-      def root(assertion_context)
-        make(nil, assertion_context)
+      def root(evaluator)
+        make(nil, evaluator)
       end
 
       # Child contexts and units of work are typically added by the `describe`
       # and `it` DSL methods respectively.
       def add_child_context(name = nil, opts = {}, &block)
-        self.children << make(name, assertion_context, &block)
+        self.children << make(name, evaluator, &block)
       end
 
       def add_unit_of_work(name = nil, opts = {}, &block)
@@ -91,13 +91,13 @@ module XSpec
       # This is leaky abstraction, since only units of work are copied from
       # shared contexts. Methods and child contexts are ignored.
       def create_shared_context(&block)
-        make(nil, assertion_context, &block)
+        make(nil, evaluator, &block)
       end
 
       def copy_into_tree(source_context)
         target_context = make(
           source_context.name,
-          source_context.assertion_context
+          source_context.evaluator
         )
         source_context.nested_units_of_work.each do |x|
           target_context.units_of_work << x.unit_of_work

data/lib/xspec/defaults.rb

@@ -2,9 +2,9 @@
 
 # These are the defaults used by `XSpec.dsl`, but feel free to specify your own
 # instead. They are set up in such a way that if you can override a component
-# down in the bowels without having to provide an entire top level evaluator.
+# down in the bowels without having to provide an entire top level scheduler.
+require 'xspec/schedulers'
 require 'xspec/evaluators'
-require 'xspec/assertion_contexts'
 require 'xspec/notifiers'
 
 module XSpec
@@ -18,12 +18,12 @@ module XSpec
     # This is a module that is included as the final step in constructing a
     # context. Allows for different matchers and expectation frameworks to be
     # used.
-    options[:assertion_context] ||= AssertionContext::DEFAULT
+    options[:evaluator] ||= Evaluator::DEFAULT
 
-    # An evaluator is responsible for scheduling units of work and handing them
+    # An scheduler is responsible for scheduling units of work and handing them
     # off to the assertion context. Any logic regarding threads, remote
-    # execution or the like belongs in an evaluator.
-    options[:evaluator]         ||= Evaluator::DEFAULT.new(options)
+    # execution or the like belongs in a scheduler.
+    options[:scheduler]         ||= Scheduler::DEFAULT
     options
   end
   module_function :add_defaults

data/lib/xspec/dsl.rb

@@ -1,6 +1,11 @@
+# # DSL
+
 # Common DSL functions are provided as a module so that they can be used in
 # both top-level and nested contexts. The method names are modeled after
 # rspec, and should behave roughly the same.
+#
+# They delegate to method in the [current context](xspec.html#section-5) named
+# in a way that more accurately represents XSpec implementation details.
 module XSpec
   module DSL
     def it(*args, &block)

data/lib/xspec/evaluators.rb

@@ -1,40 +1,334 @@
 # # Evaluators
 
-# Evaluators are responsible for collecting all units of work to be run and
-# scheduling them.
+# Evaluators are usually composed together into a stack. The final stack has a
+# single API method `call`, which is sent the unit of work to be executed and
+# must return an array of `Failure` objects. It should not allow code-level
+# exceptions to be raised, though should not block system exceptions
+# (`SignalException`, `NoMemoryError`, etc).
 module XSpec
   module Evaluator
-    # The serial evaluator, unsurprisingly, runs all units of works serially in
-    # a loop. It is about as simple an evaluator as you can imagine. Parents
-    # are responsible for actually executing the work.
-    class Serial
-      def initialize(opts)
-        @notifier = opts.fetch(:notifier)
-        @clock    = opts.fetch(:clock, ->{ Time.now.to_f })
+    # A stack is typically book-ended by the top and bottom evaluators, so this
+    # helper is the most commond way to build up a custom stack.
+    def self.stack(&block)
+      Module.new do
+        include Bottom
+        instance_exec &block
+        include Top
+      end
+    end
+
+    # The bottom evaluator executes the unit of work, with no error handling or
+    # extra behaviour. By separating this, all other evaluators layered on top
+    # of this one can just call `super`, making them easy to compose.
+    module Bottom
+      def call(unit_of_work)
+        instance_exec(&unit_of_work.block)
+        []
+      end
+    end
+
+    # The top should usually be included as the final module in a stack. It is
+    # a catch all to make sure all standard exceptions have been handled and do
+    # not leak outside the stack.
+    module Top
+      def call(unit_of_work)
+        super
+      rescue => e
+        [CodeException.new(unit_of_work, e.message, e.backtrace)]
+      end
+    end
+
+    # ### Simple Assertions
+    #
+    # This simple evaluator provides very straight-forward assertion methods.
+    module Simple
+      class AssertionFailed < RuntimeError
+        attr_reader :message, :backtrace
+
+        def initialize(message, backtrace)
+          @message   = message
+          @backtrace = backtrace
+        end
+      end
+
+      def call(unit_of_work)
+        super
+      rescue AssertionFailed => e
+        [Failure.new(unit_of_work, e.message, e.backtrace)]
+      end
+
+      def assert(proposition, message=nil)
+        unless proposition
+          message ||= 'assertion failed'
+
+          _raise message
+        end
+      end
+
+      def assert_equal(expected, actual)
+        unless expected == actual
+          message ||= <<-EOS.chomp
+want: #{expected.inspect}
+ got: #{actual.inspect}
+EOS
+
+          _raise message
+        end
+      end
+
+      def assert_include(expected, output)
+        assert output.include?(expected),
+          "#{expected.inspect} not present in: #{output.inspect}"
+      end
+
+      def fail(message = nil)
+        message ||= 'failed'
+
+        _raise message
+      end
+
+      private
+
+      def _raise(message)
+        raise AssertionFailed.new(message, caller)
+      end
+    end
+
+    # ### Doubles
+    #
+    # The doubles module provides test doubles that can be used in-place of
+    # real objects.
+    module Doubles
+      DoubleFailure = Class.new(RuntimeError)
+
+      def call(unit_of_work)
+        super
+      rescue DoubleFailure => e
+        [Failure.new(unit_of_work, e.message, e.backtrace)]
+      end
+
+      # It can be configured with the following options:
+      #
+      # * `strict` forbids doubling of classes that have not been loaded. This
+      # should generally be enabled when doing a full spec run, and disabled
+      # when running specs in isolation.
+      #
+      # The `with` method returns a module that can be included in a stack.
+      def self.with(*opts)
+        modules = [self] + opts.map {|x| {
+          strict: Strict
+        }.fetch(x) }
+
+
+        Module.new do
+          modules.each do |m|
+            include m
+          end
+        end
+      end
+
+      # An instance double stands in for an instance of the given class
+      # reference, given as a string. The class does not need to be loaded, but
+      # if it is then only public instance methods defined on the class are
+      # able to be expected.
+      def instance_double(klass)
+        _double(klass, InstanceReference)
+      end
+
+      # Simarly, a class double validates that class responds to all expected
+      # methods, if that class has been loaded.
+      def class_double(klass)
+        _double(klass, ClassReference)
+      end
+
+      # If the doubled class has not been loaded, a null object reference is
+      # used that allows expecting of all methods.
+      def _double(klass, type)
+        ref = if self.class.const_defined?(klass)
+          type.new(self.class.const_get(klass))
+        else
+          StringReference.new(klass)
+        end
+
+        Double.new(ref)
       end
 
-      def run(context)
-        notifier.run_start
+      # Use `verify` to assert that a method was called on a double with
+      # particular arguments. Doubles record all received messages, so `verify`
+      # should be called at the end of your test.
+      def verify(obj)
+        Proxy.new(obj, :_verify)
+      end
+
+
+      # All messages sent to a double will return `nil`. Use `stub` to specify
+      # a return value instead: `stub(double).some_method(1, 2) { "return
+      # value" }`. This must be called before the message is sent to the
+      # double.
+      def stub(obj)
+        Proxy.new(obj, :_stub)
+      end
+
+      # The proxy object captures messages sent to it and passes them through
+      # to either the `_verify` of `_stub` method on the double.
+      class Proxy < BasicObject
+        def initialize(double, method)
+          @double = double
+          @method = method
+        end
+
+        def method_missing(*args, &ret)
+          @double.__send__(@method, args, &(ret || ->{}))
+        end
+      end
+
+      # Since the double object inherits from `BasicObject`, virtually every
+      # method call will be routed through `method_missing`. From there, the
+      # message can be recorded and an appropriate return value selected from
+      # the stubs.
+      class Double < BasicObject
+        def initialize(klass)
+          @klass    = klass
+          @expected = []
+          @received = []
+        end
+
+        def method_missing(*actual_args)
+          stub = @expected.find {|expected_args, ret|
+            expected_args == actual_args
+          }
+
+          ret = if stub
+            stub[1].call
+          end
+
+          @received << actual_args
+
+          ret
+        end
+
+        # The two methods needed on this object to set it up and verify it are
+        # prefixed by `_` to try to ensure they don't clash with any method
+        # expectations. While not fail-safe, users should only be using
+        # expectations for a public API, and `_` is traditionally only used
+        # for private methods (if at all).
+        def _stub(args, &ret)
+          @klass.validate_call! args
+
+          @expected << [args, ret]
+        end
+
+        def _verify(args)
+          @klass.validate_call! args
+
+          i = @received.index(args)
+
+          if i
+            @received.delete_at(i)
+          else
+            name, rest = *args
+            ::Kernel.raise DoubleFailure,
+              "Did not receive: %s(%s)\nDid receive:%s\n" % [
+                name,
+                [*rest].map(&:inspect).join(", "),
+                @received.map {|name, *args|
+                  "  %s(%s)" % [name, args.map(&:inspect).join(", ")]
+                }.join("\n")
+              ]
+          end
+        end
+      end
+
+      # A reference can be thought of as a "backing object" for a double. It
+      # provides an API to validate that a method being expected actually
+      # exists - the implementation is different for the different types of
+      # doubles.
+      class Reference
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def validate_call!(args)
+        end
+
+        def to_s
+          @klass.to_s
+        end
+      end
 
-        context.nested_units_of_work.each do |x|
-          notifier.evaluate_start(x)
+      # A string reference is the "null object" of references, allowing all
+      # methods to be expected. It is used when nothing is known about the
+      # referenced class (such as when it has not been loaded).
+      class StringReference < Reference
+      end
 
-          start_time  = clock.()
-          errors      = x.immediate_parent.execute(x)
-          finish_time = clock.()
+      # Class and Instance references are backed by loaded classes, and
+      # restrict the messages that can be expected on a double.
+      class ClassReference < Reference
+        def validate_call!(args)
+          name, rest = *args
 
-          result = ExecutedUnitOfWork.new(x, errors, finish_time - start_time)
-          notifier.evaluate_finish(result)
+          unless @klass.respond_to?(name)
+            raise DoubleFailure,
+              "#{@klass}.#{name} is unimplemented or not public"
+          end
         end
+      end
+
+      class InstanceReference < Reference
+        def validate_call!(args)
+          name, rest = *args
 
-        notifier.run_finish
+          unless @klass.public_instance_methods.include?(name)
+            raise DoubleFailure,
+              "#{@klass}##{name} is unimplemented or not public"
+          end
+        end
       end
 
-      protected
+      # The `:strict` option mixes in this `Strict` module, which raises rather
+      # than create a `StringReference` for unknown classes.
+      module Strict
+        def _double(klass, type)
+          ref = if self.class.const_defined?(klass)
+            type.new(self.class.const_get(klass))
+          else
+            raise DoubleFailure, "#{klass} is not a valid class name"
+          end
 
-      attr_reader :notifier, :clock
+          super
+        end
+      end
     end
 
-    DEFAULT = Serial
+
+    # ### RSpec Integration
+    #
+    # This RSpec adapter shows two useful techniques: dynamic library loading
+    # which removes RSpec as a direct dependency, and use of the `mixin`
+    # method to further extend the target evalutor.
+    module RSpecExpectations
+      def self.included(mod)
+        begin
+          require 'rspec/expectations'
+          require 'rspec/matchers'
+        rescue LoadError
+          raise "RSpec is not available, cannot use RSpec assertion context."
+        end
+
+        mod.include(RSpec::Matchers)
+      end
+
+      def call(unit_of_work)
+        super
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        [Failure.new(unit_of_work, e.message, e.backtrace)]
+      end
+    end
+
+    DEFAULT = stack do
+      include Simple
+      include Doubles
+    end
   end
 end