mcmire-protest 0.2.4

data/lib/protest/test_case.rb

@@ -0,0 +1,248 @@
+module Protest
+  # Define a top level test context where to define tests. This works exactly
+  # the same as subclassing TestCase explicitly.
+  #
+  #     Protest.context "A user" do
+  #       ...
+  #     end
+  #
+  # is just syntax sugar to write:
+  #
+  #     class TestUser < Protest::TestCase
+  #       self.description = "A user"
+  #       ...
+  #     end
+  def self.context(description, &block)
+    TestCase.context(description, &block)
+  end
+
+  class << self
+    alias_method :describe,   :context
+    alias_method :story,      :context
+  end
+
+  # A TestCase defines a suite of related tests. You can further categorize
+  # your tests by declaring nested contexts inside the class. See
+  # TestCase.context.
+  class TestCase
+    begin
+      require "test/unit/assertions"
+      include Test::Unit::Assertions
+    rescue LoadError
+    end
+
+    # Run all tests in this context. Takes a Report instance in order to
+    # provide output.
+    def self.run(runner)
+      runner.report(TestWrapper.new(:setup, self), true)
+      tests.each {|test| runner.report(test, false) }
+      runner.report(TestWrapper.new(:teardown, self), true)
+    rescue Exception => e
+      # If any exception bubbles up here, then it means it was during the
+      # global setup/teardown blocks, so let's just skip the rest of this
+      # context.
+      return
+    end
+
+    # Tests added to this context.
+    def self.tests
+      @tests ||= []
+    end
+
+    # Add a test to be run in this context. This method is aliased as +it+ and
+    # +should+ for your comfort.
+    def self.test(name, &block)
+      tests << new(name, caller.at(0), &block)
+    end
+
+    # Add a setup block to be run before each test in this context. This method
+    # is aliased as +before+ for your comfort.
+    def self.setup(&block)
+      define_method :setup do
+        super()
+        instance_eval(&block)
+      end
+    end
+
+    # Add a +setup+ block that will be run *once* for the entire test case,
+    # before the first test is run.
+    #
+    # Keep in mind that while +setup+ blocks are evaluated on the context of the
+    # test, and thus you can share state between them, your tests will not be
+    # able to access instance variables set in a +global_setup+ block.
+    #
+    # This is usually not needed (and generally using it is a code smell, since
+    # you could make a test dependent on the state of other tests, which is a
+    # huge problem), but it comes in handy when you need to do expensive
+    # operations in your test setup/teardown and the tests won't modify the
+    # state set on this operations. For example, creating large amount of
+    # records in a database or filesystem, when your tests will only read these
+    # records.
+    def self.global_setup(&block)
+      (class << self; self; end).class_eval do
+        define_method :do_global_setup do
+          super()
+          instance_eval(&block)
+        end
+      end
+    end
+
+    # Add a teardown block to be run after each test in this context. This
+    # method is aliased as +after+ for your comfort.
+    def self.teardown(&block)
+      define_method :teardown do
+        instance_eval(&block)
+        super()
+      end
+    end
+
+    # Add a +teardown+ block that will be run *once* for the entire test case,
+    # after the last test is run.
+    #
+    # Keep in mind that while +teardown+ blocks are evaluated on the context of
+    # the test, and thus you can share state between the tests and the
+    # teardown blocks, you will not be able to access instance variables set in
+    # a test from your +global_teardown+ block.
+    #
+    # See TestCase.global_setup for a discussion on why these methods are best
+    # avoided unless you really need them and use them carefully.
+    def self.global_teardown(&block)
+      (class << self; self; end).class_eval do
+        define_method :do_global_teardown do
+          instance_eval(&block)
+          super()
+        end
+      end
+    end
+
+    # Define a new test context nested under the current one. All +setup+ and
+    # +teardown+ blocks defined on the current context will be inherited by the
+    # new context. This method is aliased as +describe+ for your comfort.
+    def self.context(description, &block)
+      subclass = Class.new(self)
+      subclass.class_eval(&block) if block
+      subclass.description = description
+      const_set(sanitize_description(description), subclass)
+    end
+
+    class << self
+      # Fancy name for your test case, reports can use this to give nice,
+      # descriptive output when running your tests.
+      attr_accessor :description
+
+      alias_method :describe,   :context
+      alias_method :story,      :context
+
+      alias_method :before,     :setup
+      alias_method :after,      :teardown
+
+      alias_method :before_all, :global_setup
+      alias_method :after_all,  :global_setup
+
+      alias_method :it,         :test
+      alias_method :should,     :test
+      alias_method :scenario,   :test
+    end
+
+    # Initialize a new instance of a single test. This test can be run in
+    # isolation by calling TestCase#run.
+    def initialize(name, location, &block)
+      @test = block
+      @location = location
+      @name = name
+    end
+
+    # Run a test in isolation. Any +setup+ and +teardown+ blocks defined for
+    # this test case will be run as expected.
+    #
+    # You need to provide a Runner instance to handle errors/pending tests/etc.
+    #
+    # If the test's block is nil, then the test will be marked as pending and
+    # nothing will be run.
+    def run(report)
+      @report = report
+      pending if test.nil?
+
+      setup
+      instance_eval(&test)
+      teardown
+      @report = nil
+    end
+
+    # Ensure a condition is met. This will raise AssertionFailed if the
+    # condition isn't met. You can override the default failure message
+    # by passing it as an argument.
+    def assert(condition, message="Expected condition to be satisfied")
+      @report.add_assertion
+      raise AssertionFailed, message unless condition
+    end
+
+    # Provided for Test::Unit compatibility, this lets you include
+    # Test::Unit::Assertions and everything works seamlessly.
+    def assert_block(message="Expected condition to be satisified") #:nodoc:
+      assert(yield, message)
+    end
+
+    # Make the test be ignored as pending. You can override the default message
+    # that will be sent to the report by passing it as an argument.
+    def pending(message="Not Yet Implemented")
+      raise Pending, message, [@location, *caller].uniq
+    end
+
+    # Name of the test
+    def name
+      @name
+    end
+
+    private
+
+    def setup #:nodoc:
+    end
+
+    def teardown #:nodoc:
+    end
+
+    def test
+      @test
+    end
+
+    def self.sanitize_description(description)
+      "Test#{description.gsub(/\W+/, ' ').strip.gsub(/(^| )(\w)/) { $2.upcase }}".to_sym
+    end
+    private_class_method :sanitize_description
+
+    def self.do_global_setup
+    end
+    private_class_method :do_global_setup
+
+    def self.do_global_teardown
+    end
+    private_class_method :do_global_teardown
+
+    def self.description #:nodoc:
+      parent = ancestors[1..-1].detect {|a| a < Protest::TestCase }
+      "#{parent.description rescue nil} #{@description}".strip
+    end
+
+    def self.inherited(child)
+      Protest.add_test_case(child)
+    end
+
+    # Provides the TestCase API for global setup/teardown blocks, so they can be
+    # "faked" as tests into the reporter (they aren't counted towards the total
+    # number of tests but they could count towards the number of failures/errors.)
+    class TestWrapper #:nodoc:
+      attr_reader :name
+
+      def initialize(type, test_case)
+        @type = type
+        @test = test_case
+        @name = "Global #{@type} for #{test_case.description}"
+      end
+
+      def run(report)
+        @test.send("do_global_#{@type}")
+      end
+    end
+  end
+end

data/lib/protest/tests.rb

@@ -0,0 +1,90 @@
+module Protest
+  # Encapsulates the relevant information about a test. Useful for certain
+  # reports.
+  class Test
+    # Instance of the test case that was run.
+    attr_reader :test
+
+    # Name of the test that passed. Useful for certain reports.
+    attr_reader :test_name
+
+    def initialize(test) #:nodoc:
+      @test = test
+      @test_name = test.name
+    end
+  end
+
+  # Mixin for tests that had an error (this could be either a failed assertion,
+  # unrescued exceptions, or just a pending tests.)
+  module TestWithErrors
+    # The triggered exception (AssertionFailed, Pending, or any
+    # subclass of Exception in the case of an ErroredTest.)
+    attr_reader :error
+
+    # Message with which it failed the assertion.
+    def error_message
+      error.message
+    end
+
+    # Line of the file where the assertion failed.
+    def line
+      backtrace.first.split(":")[1]
+    end
+
+    # File where the assertion failed.
+    def file
+      backtrace.first.split(":")[0]
+    end
+
+    # Filtered backtrace of the assertion. See Protest::Utils::BacktraceFilter
+    # for details on the filtering.
+    def backtrace
+      @backtrace ||= Protest.backtrace_filter.filter_backtrace(raw_backtrace)
+    end
+
+    # Raw backtrace, as provided by the error.
+    def raw_backtrace
+      error.backtrace
+    end
+  end
+
+  # Encapsulate the relevant information for a test that passed.
+  class PassedTest < Test
+  end
+
+  # Encapsulates the relevant information for a test which failed an
+  # assertion.
+  class FailedTest < Test
+    include TestWithErrors
+
+    def initialize(test, error) #:nodoc:
+      super(test)
+      @error = error
+    end
+  end
+
+  # Encapsulates the relevant information for a test which raised an
+  # unrescued exception.
+  class ErroredTest < Test
+    include TestWithErrors
+
+    def initialize(test, error) #:nodoc:
+      super(test)
+      @error = error
+    end
+  end
+
+  # Encapsulates the relevant information for a test that the user marked as
+  # pending.
+  class PendingTest < Test
+    include TestWithErrors
+
+    # Message passed to TestCase#pending, if any.
+    alias_method :pending_message, :error_message
+
+    def initialize(test, error) #:nodoc:
+      super(test)
+      @error = error
+    end
+  end
+end

data/lib/protest/utils/backtrace_filter.rb

@@ -0,0 +1,25 @@
+module Protest
+  module Utils
+    # Small utility object to filter an error's backtrace and remove any mention
+    # of Protest's own files.
+    class BacktraceFilter
+      ESCAPE_PATHS = [
+        # Path to the library's 'lib' dir.
+        /^#{Regexp.escape(File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__)))))}/,
+
+        # Users certainly don't care about what test loader is being used
+        %r[lib/rake/rake_test_loader.rb], %r[bin/testrb]
+      ]
+
+      # Filter the backtrace, removing any reference to files located in
+      # BASE_PATH.
+      def filter_backtrace(backtrace, prefix=nil)
+        paths = ESCAPE_PATHS + [prefix].compact
+        backtrace.reject do |line|
+          file = line.split(":").first
+          paths.any? {|path| File.expand_path(file) =~ path }
+        end
+      end
+    end
+  end
+end

data/lib/protest/utils/colorful_output.rb

@@ -0,0 +1,67 @@
+module Protest
+  module Utils
+    # Mixin that provides colorful output to your console based reports. This uses
+    # bash's escape sequences, so it won't work on windows.
+    #
+    # TODO: Make this work on windows with ansicolor or whatever the gem is named
+    module ColorfulOutput
+      # Returns a hash with the color values for different states. Override this
+      # method safely to change the output colors. The defaults are:
+      #
+      # :passed::  Light green
+      # :pending:: Light yellow
+      # :errored:: Light purple
+      # :failed::  Light red
+      #
+      # See http://www.hypexr.org/bash_tutorial.php#colors for a description of
+      # Bash color codes.
+      def self.colors
+        { :passed => "1;32",
+          :pending => "1;33",
+          :errored => "1;35",
+          :failed => "1;31" }
+      end
+
+      class << self
+        # Whether to use colors in the output or not. The default is +true+.
+        attr_accessor :colorize
+      end
+
+      self.colorize = true
+
+      # Print the string followed by a newline to whatever IO stream is defined in
+      # the method #stream using the correct color depending on the state passed.
+      def puts(string=nil, state=:normal)
+        if string.nil? # calling IO#puts with nil is not the same as with no args
+          stream.puts
+        else
+          stream.puts colorize(string, state)
+        end
+      end
+
+      # Print the string to whatever IO stream is defined in the method #stream
+      # using the correct color depending on the state passed.
+      def print(string=nil, state=:normal)
+        if string.nil? # calling IO#puts with nil is not the same as with no args
+          stream.print
+        else
+          stream.print colorize(string, state)
+        end
+      end
+
+      private
+
+        def colorize(string, state)
+          if state == :normal || !ColorfulOutput.colorize
+            string
+          else
+            "\033[#{color_for_state(state)}m#{string}\033[0m"
+          end
+        end
+
+        def color_for_state(state)
+          ColorfulOutput.colors.fetch(state)
+        end
+    end
+  end
+end

data/lib/protest/utils/summaries.rb

@@ -0,0 +1,129 @@
+module Protest
+  module Utils
+    # Mixin that provides summaries for your text based test runs.
+    module Summaries
+      # Call on +:end+ to output the amount of tests (passed, pending, failed
+      # and errored), the amount of assertions, and the time elapsed.
+      #
+      # For example:
+      #
+      #     on :end do |report|
+      #       report.puts
+      #       report.summarize_test_totals
+      #     end
+      #
+      # This relies on the public Report API, and on the presence of a #puts
+      # method to write to whatever source you are writing your report.
+      def summarize_test_totals
+        puts test_totals
+        puts running_time
+      end
+
+      # Call on +:end+ to print a list of pending tests, including file and line
+      # number where the call to TestCase#pending+ was made.
+      #
+      # It will not output anything if there weren't any pending tests.
+      #
+      # For example:
+      #
+      #     on :end do |report|
+      #       report.puts
+      #       report.summarize_pending_tests
+      #     end
+      #
+      # This relies on the public Report API, and on the presence of a #puts
+      # method to write to whatever source you are writing your report.
+      def summarize_pending_tests
+        return if pendings.empty?
+
+        puts "Pending tests:"
+        puts
+
+        pad_indexes = pendings.size.to_s.size
+        pendings.each_with_index do |pending, index|
+          puts "  #{pad(index+1, pad_indexes)}) #{pending.test_name} (#{pending.pending_message})", :pending
+          puts indent("On line #{pending.line} of `#{pending.file}'", 6 + pad_indexes), :pending
+          puts
+        end
+      end
+
+      # Call on +:end+ to print a list of failures (failed assertions) and errors
+      # (unrescued exceptions), including file and line number where the test
+      # failed, and a short backtrace.
+      #
+      # It will not output anything if there weren't any pending tests.
+      #
+      # For example:
+      #
+      #     on :end do |report|
+      #       report.puts
+      #       report.summarize_pending_tests
+      #     end
+      #
+      # This relies on the public Report API, and on the presence of a #puts
+      # method to write to whatever source you are writing your report.
+      def summarize_errors
+        return if failures_and_errors.empty?
+
+        puts "Failures:"
+        puts
+
+        pad_indexes = failures_and_errors.size.to_s.size
+        failures_and_errors.each_with_index do |error, index|
+          colorize_as = ErroredTest === error ? :errored : :failed
+          puts "  #{pad(index+1, pad_indexes)}) #{test_type(error)}: `#{error.test_name}' (on line #{error.line} of `#{error.file}')", colorize_as
+          # If error message has line breaks, indent the message
+          if error.error_message =~ /\n/
+            puts indent("with #{error.error.class}: <<", 6 + pad_indexes), colorize_as
+            puts indent(error.error_message, 6 + pad_indexes + 2), colorize_as
+            puts indent(">>", 6 + pad_indexes), colorize_as
+          else
+            puts indent("with #{error.error.class} `#{error.error_message}'", 6 + pad_indexes), colorize_as
+          end
+          indent(error.backtrace[0..2], 6 + pad_indexes).each {|backtrace| puts backtrace, colorize_as }
+          puts
+        end
+      end
+
+      private
+
+        def running_time
+          "Ran in #{time_elapsed} seconds"
+        end
+
+        def test_totals
+          "%d test%s, %d assertion%s (%d passed, %d pending, %d failed, %d errored)" % [total_tests,
+                                                                                        total_tests == 1 ? "" : "s",
+                                                                                        assertions,
+                                                                                        assertions == 1 ? "" : "s",
+                                                                                        passes.size,
+                                                                                        pendings.size,
+                                                                                        failures.size,
+                                                                                        errors.size]
+        end
+
+        def indent(strings, size=2, indent_with=" ")
+          # Don't use Array(strings) here in case strings contains line breaks. Here's why:
+          # <Array(strings)> is equivalent to <strings.to_a>
+          # <strings.to_a> is equivalent to <s = ""; strings.each {|x| s << x }; s>
+          # and in Ruby 1.8, String#each is equivalent to String#each_line
+          # so effectively it's equivalent to .split("\n") but keeping the \n's
+          strings = [strings] unless Array === strings
+          strings.map do |str|
+            str.to_s.split("\n").map {|s| indent_with * size + s }.join("\n")
+          end
+        end
+
+        def pad(str, amount)
+          " " * (amount - str.to_s.size) + str.to_s
+        end
+
+        def test_type(test)
+          case test # order is important since ErroredTest < FailedTest
+          when ErroredTest; "Error"
+          when FailedTest;  "Failure"
+          end
+        end
+    end
+  end
+end

data/lib/protest/utils.rb

@@ -0,0 +1,6 @@
+module Protest
+  # Utility mixins used in the framework, or available to Report authors to
+  # provide common functionality to the reports.
+  module Utils
+  end
+end

data/lib/protest.rb

@@ -0,0 +1,108 @@
+module Protest
+  VERSION = "0.2.4"
+
+  # Exception raised when an assertion fails. See TestCase#assert
+  class AssertionFailed < StandardError; end
+
+  # Exception raised to mark a test as pending. See TestCase#pending
+  class Pending < StandardError; end
+
+  # Register a new Report. This will make your report available to Protest,
+  # allowing you to run your tests through this report. For example
+  #
+  #     module Protest
+  #       class Reports::MyAwesomeReport < Report
+  #       end
+  #
+  #       add_report :awesomesauce, MyAwesomeReport
+  #     end
+  #
+  # See Protest.report_with to see how to select which report will be used.
+  def self.add_report(name, report)
+    available_reports[name] = report
+  end
+
+  # Register a test case to be run with Protest. This is done automatically
+  # whenever you subclass Protest::TestCase, so you probably shouldn't pay
+  # much attention to this method.
+  def self.add_test_case(test_case)
+    available_test_cases << test_case
+  end
+
+  # Set to +false+ to avoid running tests +at_exit+. Default is +true+.
+  def self.autorun=(flag)
+    @autorun = flag
+  end
+
+  # Checks to see if tests should be run +at_exit+ or not. Default is +true+.
+  # See Protest.autorun=
+  def self.autorun?
+    !!@autorun
+  end
+
+  # Run all registered test cases through the selected report. You can pass
+  # arguments to the Report constructor here.
+  #
+  # See Protest.add_test_case and Protest.report_with
+  def self.run_all_tests!(*report_args)
+    Runner.new(@report).run(*available_test_cases)
+  end
+
+  # Select the name of the Report to use when running tests. See
+  # Protest.add_report for more information on registering a report.
+  #
+  # Any extra arguments will be forwarded to the report's #initialize method.
+  #
+  # The default report is Protest::Reports::Progress
+  def self.report_with(name, *report_args)
+    @report = report(name, *report_args)
+  end
+
+  # Load a report by name, initializing it with the extra arguments provided.
+  # If the given +name+ doesn't match a report registered via
+  # Protest.add_report then the method will raise IndexError.
+  def self.report(name, *report_args)
+    available_reports.fetch(name).new(*report_args)
+  end
+
+  # Set what object will filter the backtrace. It must respond to
+  # +filter_backtrace+, taking a backtrace array and a prefix path.
+  def self.backtrace_filter=(filter)
+    @backtrace_filter = filter
+  end
+
+  # The object that filters the backtrace
+  def self.backtrace_filter
+    @backtrace_filter
+  end
+
+  def self.available_test_cases
+    @test_cases ||= []
+  end
+  private_class_method :available_test_cases
+
+  def self.available_reports
+    @available_reports ||= {}
+  end
+  private_class_method :available_reports
+end
+
+require "protest/utils"
+require "protest/utils/backtrace_filter"
+require "protest/utils/summaries"
+require "protest/utils/colorful_output"
+require "protest/test_case"
+require "protest/tests"
+require "protest/runner"
+require "protest/report"
+require "protest/reports"
+require "protest/reports/progress"
+require "protest/reports/documentation"
+
+Protest.autorun = true
+Protest.report_with(:progress)
+Protest.backtrace_filter = Protest::Utils::BacktraceFilter.new
+
+at_exit do
+  Protest.run_all_tests! if Protest.autorun?
+end