baretest 0.2.4 → 0.4.0.pre1

data/lib/baretest/run/xml.rb

@@ -31,47 +31,49 @@ module BareTest
     #   <status>The final status, one of: success, incomplete, failure, error</status>
     #
     module XML # :nodoc:
+      extend Formatter
+      option_defaults :indent => "\t"
+      text       "Options for 'XML' formatter:\n"
+      option     :indent,  '--indent STRING',   :String, 'String to use for indenting'
+      text       "\nEnvironment variables for 'XML' formatter:\n"
+      env_option :indent, 'INDENT'
+
       def run_all
-        @depth = 1
+        @depth  = 1
+        @indent = @options[:indent]
 
         puts '<?xml version="1.0" encoding="utf-8"?>',
              '<tests>'
         start  = Time.now
         super
         stop   = Time.now
-        status = case
-          when @count[:error]   > 0 then 'error'
-          when @count[:failure] > 0 then 'failure'
-          when @count[:pending] > 0 then 'incomplete'
-          when @count[:skipped] > 0 then 'incomplete'
-          else 'success'
-        end
         puts %{</tests>},
              %{<report>},
-             %{\t<duration>#{stop-start}</duration>}
+             %{#{@indent}<duration>#{stop-start}</duration>}
         @count.each { |key, value|
-          puts %{\t<count type="#{key}">#{value}</count>}
+          puts %{#{@indent}<count type="#{key}">#{value}</count>}
         }
         puts %{</report>},
-             %{<status>#{status}</status>}
+             %{<status>#{global_status}</status>}
       end
 
       def run_suite(suite)
-        puts %{#{"\t"*@depth}<suite description="#{suite.description}">}
+        puts %{#{@indent*@depth}<suite description="#{suite.description}">}
         @depth += 1
         super
         @depth -= 1
-        puts %{#{"\t"*@depth}</suite>}
+        puts %{#{@indent*@depth}</suite>}
       end
 
       def run_test(assertion, setup)
         rv = super
-        puts %{#{"\t"*@depth}<test>},
-             %{#{"\t"*@depth}\t<file>#{rv.file}</file>},
-             %{#{"\t"*@depth}\t<line>#{rv.line}</line>},
-             %{#{"\t"*@depth}\t<status>#{rv.status}</status>},
-             %{#{"\t"*@depth}\t<description>#{rv.description}</description>},
-             %{#{"\t"*@depth}</test>}
+        puts %{#{@indent*@depth}<test>},
+             %{#{@indent*@depth}#{@indent}<file>#{assertion.file}</file>},
+             %{#{@indent*@depth}#{@indent}<line>#{assertion.line}</line>},
+             %{#{@indent*@depth}#{@indent}<status>#{rv.status}</status>},
+             %{#{@indent*@depth}#{@indent}<description>#{assertion.description}</description>},
+             %{#{@indent*@depth}</test>}
+        rv
       end
     end
   end

data/lib/baretest/setup.rb

@@ -7,6 +7,8 @@
 
 
 module BareTest
+  # Encapsulates a single setup block and associated information.
+  # Relevant for setup variants.
   Setup = Struct.new(:component, :substitute, :value, :block) do
     def inspect
       sprintf "#<Setup component=%s substitute=%p value=%p>", component, substitute, value

data/lib/baretest/status.rb

@@ -0,0 +1,93 @@
+#--
+# Copyright 2009-2010 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+module BareTest
+
+  # The status of an Assertion or Suite, including failure- and skipreasons,
+  # or in case of exceptions, the exception itself and in what phase it occurred
+    # An assertion or suite has 9 possible states:
+    # :success:: The assertion passed. This means the block returned a trueish value.
+    # :failure:: The assertion failed. This means the block returned a falsish value.
+    #            Alternatively it raised an Assertion::Failure.
+    #            The latter has the advantage that it can provide nicer diagnostics.
+    # :pending:: No block given to the assertion to be run
+    # :skipped:: If one of the parent suites is missing a dependency, its assertions
+    #            will be skipped
+    #            Alternatively it raised an Assertion::Skip.
+    # :error::   The assertion errored out. This means the block raised an exception
+  class Status
+
+    # The assertion or suite this status belongs to. Assertion or Suite.
+    attr_reader :entity
+
+    # The assertions execute context.
+    attr_reader :context
+
+    # The status identifier, see BareTest::Status. Symbol.
+    attr_reader :status
+
+    # Detailed reason for skipping. Array or nil.
+    attr_reader :skip_reason
+
+    # Detailed reason for failing. Array or nil.
+    attr_reader :failure_reason
+
+    # If an exception occured in Assertion#execute, this will contain the
+    # Exception object raised.
+    attr_reader :exception
+
+    # entity::      The suite or Assertion this Status belongs to
+    # status::      The status identifier
+    # skip_reason::    Why the Assertion or Suite failed.
+    #                  Array, String or nil.
+    # failure_reason:: Why the Assertion or Suite was skipped.
+    #                  Array, String or nil.
+    def initialize(entity, status, context=nil, skip_reason=nil, failure_reason=nil, exception=nil)
+      @entity         = entity
+      @status         = status
+      @context        = context
+      @skip_reason    = skip_reason
+      @failure_reason = failure_reason
+      @exception      = exception
+    end
+
+    # The failure/error/skipping/pending reason.
+    # Returns nil if there's no reason, a string otherwise
+    # Options:
+    # :default::     Reason to return if no reason is present
+    # :separator::   String used to separate multiple reasons
+    # :indent::      A String, the indentation to use. Prefixes every line.
+    # :first_indent: A String, used to indent the first line only (replaces indent).
+    def reason(opt=nil)
+      if opt then
+        default, separator, indent, first_indent = 
+          *opt.values_at(:default, :separator, :indent, :first_indent)
+        reason = @skip_reason || @failure_reason || default
+        return nil unless reason
+        reason = Array(reason)
+        reason = reason.join(separator || "\n")
+        reason = reason.gsub(/^/, indent) if indent
+        reason = reason.gsub(/^#{Regexp.escape(indent)}/, first_indent) if first_indent
+        reason
+      else
+        @reason.empty? ? nil : @reason.join("\n")
+      end
+    end
+
+    def inspect # :nodoc:
+      sprintf "#<%s:0x%08x status=%p exception=%p skip_reason=%p failure_reason=%p entity=%p>",
+        self.class,
+        object_id>>1,
+        @status,
+        @exception,
+        @skip_reason,
+        @failure_reason,
+        @entity
+    end
+  end
+end

data/lib/baretest/suite.rb

@@ -21,76 +21,181 @@ module BareTest
   class Suite
 
     # Nested suites, in the order of definition
-    attr_reader :suites
+    attr_reader   :suites
 
     # All assertions in this suite
-    attr_reader :assertions
+    attr_reader   :assertions
 
-    # All skipped assertions in this suite
-    attr_reader :skipped
+    # Whether this suite has been manually skipped (either via
+    # Suite.new(..., :skip => reason) or via Suite#skip)
+    attr_reader   :skipped
 
     # This suites description. Toplevel suites usually don't have a description.
-    attr_reader :description
+    attr_reader   :description
 
     # This suites direct parent. Nil if toplevel suite.
-    attr_reader :parent
+    attr_reader   :parent
 
     # An Array containing the suite itself (first element), then its direct
     # parent suite, then that suite's parent and so on
-    attr_reader :ancestors
+    attr_reader   :ancestors
+
+    # All things this suite depends on, see Suite::new for more information
+    attr_reader   :depends_on
+
+    # All things this suite provides, see Suite::new for more information
+    attr_reader   :provides
+
+    # All things this suite is tagged with, see Suite::new for more information
+    attr_reader   :tags
+
+    # A list of valid options Suite::new accepts
+    ValidOptions = [:skip, :requires, :use, :provides, :depends_on, :tags]
 
     # Create a new suite.
     #
-    # The arguments 'description', 'parent' and '&block' are the same as on Suite::new,
-    # 'opts' is an additional options hash.
+    # Arguments:
+    # description:: A string with a human readable description of this suite,
+    #               preferably less than 60 characters and without newlines
+    # parent::      The suite that nests this suite. Ancestry plays a role in
+    #               execution of setup and teardown blocks (all ancestors setups
+    #               and teardowns are executed too).
+    # opts::        An additional options hash.
     #
     # Keys the options hash accepts:
-    # :requires:: A string or array of strings with requires that have to be done in order to run
-    #             this suite. If a require fails, the suite is created as a Skipped::Suite instead.
-    #
-    def self.create(description=nil, parent=nil, opts={}, &block)
-      Array(opts[:requires]).each { |file| require file } if opts[:requires]
-    rescue LoadError
-      # A suite is skipped if requirements are not met
-      Skipped::Suite.new(description, parent, &block)
-    else
-      # All suites within Skipped::Suite are Skipped::Suite
-      (block ? self : Skipped::Suite).new(description, parent, &block)
-    end
-
-    # Create a new suite.
+    # :skip::       Skips the suite if true or a String is passed. If a String
+    #               is passed, it is used as the reason.
+    # :requires::   A string or array of strings with requires that have to be
+    #               done in order to run this suite. If a require fails, the
+    #               assertions will all be skipped with reason "Missing
+    #               dependency".
+    # :use::        A symbol or array of symbols with components this suite
+    #               should load prior to running.
+    # :provides::   A symbol or array of symbols with dependencies this suite
+    #               resolves, see 'depends_on'.
+    # :depends_on:: A symbol or array of symbols with dependencies of this
+    #               suite, see 'provides'.
+    # :tags::       A symbol or array of symbols, useful to run only suites
+    #               having/not having specific tags
     #
-    # Arguments:
-    # description:: A string with a human readable description of this suite, preferably
-    #               less than 60 characters and without newlines
-    # parent::      The suite that nests this suite. Ancestry plays a role in execution of setup
-    #               and teardown blocks (all ancestors setups and teardowns are executed too).
-    # &block::      The given block is instance evaled.
-    def initialize(description=nil, parent=nil, &block)
+    # &block::      The given block is instance evaled and can contain further
+    #               definition of this assertion. See Suite#suite and
+    #               Suite#assert.
+    def initialize(description=nil, parent=nil, opts=nil, &block)
       @description = description
       @parent      = parent
       @suites      = [] # [["description", subsuite, skipped], ["description2", ...], ...] - see Array#assoc
       @assertions  = []
-      @skipped     = []
+      @skipped     = false
       @setup       = {nil => []}
       @components  = []
       @teardown    = []
-      @ancestors   = [self] + (@parent ? @parent.ancestors : [])
+      if @parent then
+        @ancestors   = [self, *@parent.ancestors]
+        @depends_on  = @parent.depends_on
+        @tags        = @parent.tags
+      else
+        @ancestors   = [self]
+        @depends_on  = []
+        @tags        = []
+      end
+      @provides    = []
+      @reason      = [] # skip reason
+      if opts then
+        raise ArgumentError, "Invalid option(s): #{(opts.keys - ValidOptions).inspect}" unless (opts.keys - ValidOptions).empty?
+        skip, requires, use, provides, depends_on, tags = opts.values_at(*ValidOptions)
+        skip(skip == true ? nil : skip) if skip
+        use(*use) if use
+        requires(*requires) if requires
+        @depends_on |= Array(depends_on) if depends_on
+        @provides   |= Array(provides) if provides
+        @tags       |= Array(tags) if tags
+      end
       instance_eval(&block) if block
     end
 
+    # An ID, usable for persistence
+    def id
+      @id ||= ancestors.map { |suite| suite.description }.join("\f")
+    end
+
+    # Instruct this suite to use the given components.
+    # The suite is skipped if a component is not available.
+    def use(*components)
+      components.each do |name|
+        component = BareTest.component(name)
+        if component then
+          instance_eval(&component)
+        else
+          skip("Missing component: #{name.inspect}")
+        end
+      end
+    end
+
+    # Instruct this suite to require the given files.
+    # The suite is skipped if a file can't be loaded.
+    def requires(*paths)
+      paths.each do |file|
+        begin
+          require file
+        rescue LoadError => e
+          skip("Missing source file: #{file} (#{e})")
+        end
+      end
+    end
+
+    # Returns whether this suite has all the passed tags
+    def tagged?(tags)
+      (@tags-tags).empty?
+    end
+
+    # Marks this suite as manually skipped.
+    def skip(reason=nil)
+      @skipped  = true
+      @reason  |= reason ? Array(reason) : ['Manually skipped']
+      true
+    end
+
+    # Returns whether this assertion has been marked as manually skipped.
+    def skipped?
+      @skipped
+    end
+
+    # The failure/error/skipping/pending reason.
+    # Returns nil if there's no reason, a string otherwise
+    # Options:
+    # :default::     Reason to return if no reason is present
+    # :separator::   String used to separate multiple reasons
+    # :indent::      A String, the indentation to use. Prefixes every line.
+    # :first_indent: A String, used to indent the first line only (replaces indent).
+    def reason(opt=nil)
+      if opt then
+        default, separator, indent, first_indent = 
+          *opt.values_at(:default, :separator, :indent, :first_indent)
+        reason = @reason
+        reason = Array(default) if reason.empty? && default
+        return nil if reason.empty?
+        reason = reason.join(separator || "\n")
+        reason = reason.gsub(/^/, indent) if indent
+        reason = reason.gsub(/^#{Regexp.escape(indent)}/, first_indent) if first_indent
+        reason
+      else
+        @reason.empty? ? nil : @reason.join("\n")
+      end
+    end
+
     # Define a nested suite.
     #
     # Nested suites inherit setup & teardown methods.
     # Also if an outer suite is skipped, all inner suites are skipped too.
     #
-    # Valid values for opts:
-    # :requires:: A list of files to require, if one of the requires fails,
-    #               the suite will be skipped. Accepts a String or an Array
-    def suite(description=nil, opts={}, &block)
-      suite = self.class.create(description, self, opts, &block)
-      if append_to = @suites.assoc(description) then
-        append_to.last.update(suite)
+    # See Suite::new - all arguments are passed to it verbatim, and self is
+    # added as parent.
+    def suite(description=nil, *args, &block)
+      suite          = self.class.new(description, self, *args, &block)
+      existing_suite = @suites.assoc(description)
+      if existing_suite then
+        existing_suite.last.update(suite)
       else
         @suites << [description, suite]
       end
@@ -101,20 +206,23 @@ module BareTest
     #
     # Used to merge suites with the same description.
     def update(with_suite)
-      if ::BareTest::Skipped::Suite === with_suite then
-        @skipped.concat(with_suite.skipped)
-      else
-        @assertions.concat(with_suite.assertions)
-        @setup.update(with_suite.setup) do |k,v1,v2| v1+v2 end
-        @teardown.concat(with_suite.teardown)
-        with_suite.suites.each { |description, suite|
-          if append_to = @suites.assoc(description) then
-            append_to.last.update(suite)
-          else
-            @suites << [description, suite]
-          end
-        }
-      end
+      assertions, setup, teardown, provides, depends_on, skipped, reason, suites =
+        *with_suite.merge_attributes
+      @assertions.concat(assertions)
+      @setup.update(setup) do |k,v1,v2| v1+v2 end
+      @teardown.concat(teardown)
+      @provides   |= provides
+      @depends_on |= depends_on
+      @skipped   ||= skipped
+      @reason.concat(reason)
+      suites.each { |description, suite|
+        if append_to = @suites.assoc(description) then
+          append_to.last.update(suite)
+        else
+          @suites << [description, suite]
+        end
+      }
+
       self
     end
 
@@ -173,6 +281,13 @@ module BareTest
       block ? @teardown << block : @teardown
     end
 
+    # Returns the number of possible setup variations.
+    # See #each_component_variant
+    def component_variant_count
+      ancestry_setup.values_at(*ancestry_components).inject(1) { |r,f| r*f.size }
+    end
+
+    # Yields all possible permutations of setup components.
     def each_component_variant
       setups     = ancestry_setup
       components = ancestry_components
@@ -196,6 +311,7 @@ module BareTest
       self
     end
 
+    # Return only the first of all possible setup variation permutations.
     def first_component_variant
       setups, *comps = ancestry_setup.values_at(nil, *ancestry_components)
       setups = setups+comps.map { |comp| comp.first }
@@ -208,8 +324,8 @@ module BareTest
     # (anything but nil or false).
     #
     # See Assertion for more info.
-    def assert(description=nil, &block)
-      assertion = Assertion.new(self, description, &block)
+    def assert(description=nil, opts=nil, &block)
+      assertion = Assertion.new(self, description, opts, &block)
       if match = caller.first.match(/^(.*):(\d+)(?::.+)?$/) then
         file, line = match.captures
         file = File.expand_path(file)
@@ -220,6 +336,7 @@ module BareTest
       end
       @assertions << assertion
     end
+    alias guard assert # TODO: This is temporary, guards should become first class citizens
 
     def to_s #:nodoc:
       sprintf "%s %s", self.class, @description
@@ -228,9 +345,18 @@ module BareTest
     def inspect #:nodoc:
       sprintf "#<%s:%08x %p>", self.class, object_id>>1, @description
     end
+
+  protected
+    # All attributes that are required when merging two suites
+    def merge_attributes
+      return @assertions,
+             @setup,
+             @teardown,
+             @provides,
+             @depends_on,
+             @skipped,
+             @reason,
+             @suites
+    end
   end
 end
-
-
-
-require 'baretest/skipped/suite' # TODO: determine why this require is on the bottom and document it.