xspec 0.0.1

data/lib/xspec/autorun.rb

@@ -0,0 +1,8 @@
+# # Autorun
+
+# A convenience file that sets up an auto-running common case DSL in the
+# top-level namespace to get you going fast.
+require 'xspec'
+
+extend XSpec.dsl
+autorun!

data/lib/xspec/data_structures.rb

@@ -0,0 +1,181 @@
+# # Data Structures
+
+# XSpec data structures are very dumb. They:
+#
+# * Only contain iteration and creation logic.
+# * Do not store recursive references ("everything flows downhill").
+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.
+  UnitOfWork = Struct.new(:name, :block)
+
+
+  # A context is a recursively nested structure, usually created with the
+  # `describe` DSL method, that contains other contexts and units of work. Most
+  # of the logic for a context happens at the class level rather than instance,
+  # which is unusual but required for method inheritance to work correctly. It
+  # currently violates the logic rule specified above, more work is required to
+  # decouple it.
+  require 'xspec/dsl'
+  class Context
+    class << self
+      attr_reader :name, :children, :units_of_work, :assertion_context
+
+      # A context includes the same DSL methods as the root level module, which
+      # enables the recursive creation.
+      def __xspec_context; self; end
+      include ::XSpec::DSL
+
+      # 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
+      # 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)
+        x = Class.new(self)
+        x.initialize!(name, assertion_context)
+        x.class_eval(&block) if block
+        x.apply_assertion_context!
+        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)
+        @children          = []
+        @units_of_work     = []
+        @name              = name
+        @assertion_context = assertion_context
+      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)
+      end
+
+      # Executing a unit of work creates a new instance and hands it off to the
+      # `call` method, which is defined by whichever assertion context is being
+      # used. By creating a new instance everytime, no state is preserved
+      # between executions.
+      def execute(unit_of_work)
+        new.call(unit_of_work)
+      end
+
+      # The root context is nothing special, and behaves the same as all the
+      # others.
+      def root(assertion_context)
+        make(nil, assertion_context)
+      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)
+      end
+
+      def add_unit_of_work(name = nil, opts = {}, &block)
+        self.units_of_work << UnitOfWork.new(name, block)
+      end
+
+      # A shared context is a floating context that isn't part of any context
+      # heirachy, so its units of work will not be visible to the root node. It
+      # can be brought into any point in the heirachy using `copy_into_tree`
+      # (aliased as `it_behaves_like_a` in the DSL), and this can be done
+      # multiple times, which allows definitions to be reused.
+      #
+      # 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)
+      end
+
+      def copy_into_tree(source_context)
+        target_context = make(
+          source_context.name,
+          source_context.assertion_context
+        )
+        source_context.nested_units_of_work.each do |x|
+          target_context.units_of_work << x.unit_of_work
+        end
+        self.children << target_context
+        target_context
+      end
+
+      # The most convenient way to access all units of work is this recursive
+      # iteration that returns all leaf-nodes as `NestedUnitOfWork` objects.
+      require 'enumerator'
+      def nested_units_of_work(&block)
+        enum = Enumerator.new do |y|
+          children.each do |child|
+            child.nested_units_of_work do |x|
+              y.yield x.nest_under(self)
+            end
+          end
+
+          units_of_work.each do |x|
+            y.yield NestedUnitOfWork.new([self], x)
+          end
+        end
+
+        if block
+          enum.each(&block)
+        else
+          enum
+        end
+      end
+
+      # Values of memoized methods are remembered only for the duration of a
+      # single unit of work. These are typically created using the `let` DSL
+      # method.
+      def add_memoized_method(name, &block)
+        define_method(name) do
+          memoized[block] ||= instance_eval(&block)
+        end
+      end
+
+      # Dynamically generated classes are hard to identify in object graphs, so
+      # it is helpful for debugging to set an explicit name.
+      def to_s
+        "Context:'#{name}'"
+      end
+    end
+
+    def memoized
+      @memoized ||= {}
+    end
+  end
+
+  # Units of work can be nested inside contexts. This is the main object that
+  # other components of the system work with.
+  NestedUnitOfWork = Struct.new(:parents, :unit_of_work) do
+    def block; unit_of_work.block; end
+    def name;  unit_of_work.name; end
+
+    def immediate_parent
+      parents.last
+    end
+
+    def nest_under(parent)
+      self.class.new([parent] + parents, unit_of_work)
+    end
+  end
+
+  # The result of executing a unit of work, including timing information. This
+  # is passed to notifiers for display or other processing.
+  ExecutedUnitOfWork = Struct.new(:nested_unit_of_work, :errors, :duration) do
+    def name; nested_unit_of_work.name end
+    def parents; nested_unit_of_work.parents end
+  end
+
+  # A test failure will be reported as a `Failure`, which includes contextual
+  # information about the failure useful for reporting to the user.
+  Failure = Struct.new(:unit_of_work, :message, :caller)
+
+  # An exception is mostly handled the same way as a failure.
+  CodeException = Class.new(Failure)
+end

data/lib/xspec/defaults.rb

@@ -0,0 +1,30 @@
+# # Defaults
+
+# 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.
+require 'xspec/evaluators'
+require 'xspec/assertion_contexts'
+require 'xspec/notifiers'
+
+module XSpec
+  def add_defaults(options = {})
+    # A notifier makes it possible to observe the state of the system, be that
+    # progress or details of failing tests.
+    options[:notifier] ||= XSpec::Notifier::DEFAULT
+
+    # A unit of work will run as an instance method on the context it is
+    # defined in, but in addition an assertion context will be added as well.
+    # 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
+
+    # An evaluator 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)
+    options
+  end
+  module_function :add_defaults
+end

data/lib/xspec/dsl.rb

@@ -0,0 +1,26 @@
+# 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.
+module XSpec
+  module DSL
+    def it(*args, &block)
+      __xspec_context.add_unit_of_work(*args, &block)
+    end
+
+    def describe(*args, &block)
+      __xspec_context.add_child_context(*args, &block)
+    end
+
+    def let(*args, &block)
+      __xspec_context.add_memoized_method(*args, &block)
+    end
+
+    def shared_context(*args, &block)
+      __xspec_context.create_shared_context(*args, &block)
+    end
+
+    def it_behaves_like_a(context)
+      __xspec_context.copy_into_tree(context)
+    end
+  end
+end

data/lib/xspec/evaluators.rb

@@ -0,0 +1,40 @@
+# # Evaluators
+
+# Evaluators are responsible for collecting all units of work to be run and
+# scheduling them.
+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 })
+      end
+
+      def run(context)
+        notifier.run_start
+
+        context.nested_units_of_work.each do |x|
+          notifier.evaluate_start(x)
+
+          start_time  = clock.()
+          errors      = x.immediate_parent.execute(x)
+          finish_time = clock.()
+
+          result = ExecutedUnitOfWork.new(x, errors, finish_time - start_time)
+          notifier.evaluate_finish(result)
+        end
+
+        notifier.run_finish
+      end
+
+      protected
+
+      attr_reader :notifier, :clock
+    end
+
+    DEFAULT = Serial
+  end
+end

data/lib/xspec/notifiers.rb

@@ -0,0 +1,310 @@
+# # Notifiers
+
+# Without a notifier, there is no way for XSpec to interact with the outside
+# world. A notifier handles progress updates as tests are executed, and
+# summarizing the run when it finished.
+module XSpec
+  module Notifier
+    # Many notifiers play nice with others, and can be composed together in a
+    # way that each notifier will have its callback run in turn.
+    module Composable
+      def +(other)
+        Composite.new(self, other)
+      end
+    end
+
+    class Composite
+      include Composable
+
+      def initialize(*notifiers)
+        @notifiers = notifiers
+      end
+
+      def run_start
+        notifiers.each(&:run_start)
+      end
+
+      def evaluate_start(*args)
+        notifiers.each {|x| x.evaluate_start(*args) }
+      end
+
+      def evaluate_finish(*args)
+        notifiers.each {|x| x.evaluate_finish(*args) }
+      end
+
+      def run_finish
+        notifiers.map(&:run_finish).all?
+      end
+
+      protected
+
+      attr_reader :notifiers
+    end
+
+    # Outputs a single character for each executed unit of work representing
+    # the result.
+    class Character
+      include Composable
+
+      def initialize(out = $stdout)
+        @out = out
+      end
+
+      def run_start; end
+
+      def evaluate_start(*_); end
+
+      def evaluate_finish(result)
+        @out.print label_for_failure(result.errors[0])
+        @failed ||= result.errors.any?
+      end
+
+      def run_finish
+        @out.puts
+        !@failed
+      end
+
+      protected
+
+      def label_for_failure(f)
+        case f
+          when CodeException then 'E'
+          when Failure then 'F'
+          else '.'
+        end
+      end
+
+    end
+
+    # Renders a histogram of test durations after the entire run is complete.
+    class TimingsAtEnd
+      include Composable
+
+      DEFAULT_SPLITS = [0.001, 0.005, 0.01, 0.1, 1.0, Float::INFINITY]
+
+      def initialize(out:    $stdout,
+                     splits: DEFAULT_SPLITS,
+                     width:  20)
+
+        @timings = {}
+        @splits  = splits
+        @width   = width
+        @out     = out
+      end
+
+      def run_start(*_); end
+
+      def evaluate_start(_)
+      end
+
+      def evaluate_finish(result)
+        timings[result] = result.duration
+      end
+
+      def run_finish
+        buckets = bucket_from_splits(timings, splits)
+        max     = buckets.values.max
+
+        out.puts "           Timings:"
+        buckets.each do |(split, count)|
+          label = split.infinite? ? "∞" : split
+
+          out.puts "    %6s %-#{width}s %i" % [
+            label,
+            '#' * (count / max.to_f * width.to_f).ceil,
+            count
+          ]
+        end
+        out.puts
+      end
+
+    private
+
+      attr_reader :timings, :splits, :width, :out
+
+      def bucket_from_splits(timings, splits)
+        initial_buckets = splits.each_with_object({}) do |b, a|
+          a[b] = 0
+        end
+
+        buckets = timings.each_with_object(initial_buckets) do |(_, d), a|
+          split = splits.detect {|x| d < x }
+          a[split] += 1
+        end
+
+        remove_trailing_zero_counts(buckets)
+      end
+
+      def remove_trailing_zero_counts(buckets)
+        Hash[
+          buckets
+            .to_a
+            .reverse
+            .drop_while {|_, x| x == 0 }
+            .reverse
+        ]
+      end
+    end
+
+    # Outputs error messages and backtraces after the entire run is complete.
+    class FailuresAtEnd
+      include Composable
+
+      def initialize(out = $stdout)
+        @errors = []
+        @out    = out
+      end
+
+      def run_start; end
+
+      def evaluate_start(*_); end
+
+      def evaluate_finish(result)
+        self.errors += result.errors
+      end
+
+      def run_finish
+        return true if errors.empty?
+
+        out.puts
+        errors.each do |error|
+          out.puts "%s:\n%s\n\n" % [full_name(error.unit_of_work), error.message.lines.map {|x| "  #{x}"}.join("")]
+          clean_backtrace(error.caller).each do |line|
+            out.puts "  %s" % line
+          end
+          out.puts
+        end
+
+        false
+      end
+
+      def full_name(unit_of_work)
+        (unit_of_work.parents + [unit_of_work]).map(&:name).compact.join(' ')
+      end
+
+      # A standard backtrace contains many entries for XSpec itself which are
+      # not useful for debugging your tests, so they are stripped out.
+      def clean_backtrace(backtrace)
+        lib_dir = File.dirname(File.expand_path('..', __FILE__))
+
+        backtrace.reject {|x|
+          File.dirname(x).start_with?(lib_dir)
+        }
+      end
+
+      protected
+
+      attr_accessor :out, :errors
+    end
+
+    # Includes nicely formatted names and durations of each test in the output,
+    # with color.
+    class ColoredDocumentation
+      require 'set'
+
+      include Composable
+
+      VT100_COLORS = {
+        :black   => 30,
+        :red     => 31,
+        :green   => 32,
+        :yellow  => 33,
+        :blue    => 34,
+        :magenta => 35,
+        :cyan    => 36,
+        :white   => 37
+      }
+
+      def color_code_for(color)
+        VT100_COLORS.fetch(color)
+      end
+
+      def colorize(text, color)
+        "\e[#{color_code_for(color)}m#{text}\e[0m"
+      end
+
+      def decorate(result)
+        name = result.name
+        out = if result.errors.any?
+          colorize(append_failed(name), :red)
+        else
+          colorize(name , :green)
+        end
+        "%.3fs " % result.duration + out
+      end
+
+      def initialize(out = $stdout)
+        self.indent          = 2
+        self.last_seen_names = []
+        self.failed          = false
+        self.out             = out
+      end
+
+      def run_start; end
+
+      def evaluate_start(*_); end
+
+      def evaluate_finish(result)
+        output_context_header! result.parents.map(&:name).compact
+
+        spaces = ' ' * (last_seen_names.size * indent)
+
+        self.failed ||= result.errors.any?
+
+        out.puts "%s%s" % [spaces, decorate(result)]
+      end
+
+      def run_finish
+        out.puts
+        !failed
+      end
+
+      protected
+
+      attr_accessor :last_seen_names, :indent, :failed, :out
+
+      def output_context_header!(parent_names)
+        if parent_names != last_seen_names
+          tail = parent_names - last_seen_names
+
+          out.puts
+          if tail.any?
+            existing_indent = parent_names.size - tail.size
+            tail.each_with_index do |name, i|
+              out.puts '%s%s' % [' ' * ((existing_indent + i) * indent), name]
+            end
+          end
+
+          self.last_seen_names = parent_names
+        end
+      end
+
+      def append_failed(name)
+        [name, "FAILED"].compact.join(' - ')
+      end
+    end
+
+    # Includes nicely formatted names and durations of each test in the output.
+    class Documentation < ColoredDocumentation
+      def colorize(name, _)
+        name
+      end
+    end
+
+    # A notifier that does not do anything and always returns successful.
+    # Useful as a parent class for other notifiers or for testing.
+    class Null
+      include Composable
+
+      def run_start; end
+      def evaluate_start(*_); end
+      def evaluate_finish(*_); end
+      def run_finish; true; end
+    end
+
+    DEFAULT =
+      ColoredDocumentation.new +
+      TimingsAtEnd.new +
+      FailuresAtEnd.new
+  end
+end