protest 0.2

data/.gitignore

@@ -0,0 +1,2 @@
+doc
+dist

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2009 Nicolas Sanguinetti
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,190 @@
+= Protest, the simplicity rebel test framework
+
+    require "protest"
+
+    Protest.context("A user") do
+      setup do
+        @user = User.new(:name => "John Doe", :email => "john@example.org")
+      end
+
+      test "has a name" do
+        assert @user.name == "John Doe"
+      end
+
+      test "has an email" do
+        assert @user.email == "john@example.org"
+      end
+    end
+
+Protest is a small, simple, and easy-to-extend testing framework for ruby. It
+was written as a replacement for Test::Unit, given how awful its code is, and
+how difficult it is to extend in order to add new features.
+
+I believe in minimalistic software, which is easily understood, easy to test,
+and specially, easy to extend for third parties. That's where I'm aiming with
+Protest.
+
+== Get it
+
+    gem install protest
+
+Or
+
+    rip install git://github.com/foca/protest.git
+
+== Assertions
+
+You probably wonder why the above example doesn't have any assertion other than
++assert+. Where's +assert_equal+, right? Well, the idea is to keep it slim. If
+you want to use more assertions, you're free to define your own. You can also
+use all the assertions provided by Test::Unit, by just including them:
+
+    require "test/unit/assertions"
+
+    class Protest::TestCase
+      include Test::Unit::Assertions
+    end
+
+You could also define rspec-like matchers if you like that. See +matchers.rb+ in
+the examples directory for an example.
+
+== Setup and teardown
+
+If you need to run code before or after each test, declare a +setup+ or
++teardown+ block (respectively.)
+
+    Protest.context("A user") do
+      setup do # this runs before each test
+        @user = User.create(:name => "John")
+      end
+
+      teardown do # this runs after each test
+        @user.destroy
+      end
+    end
+
++setup+ and +teardown+ blocks are evaluated in the same context as your test,
+which means any instance variables defined in any of them are available in the
+rest.
+
+You can also use +global_setup+ and +global_teardown+ to run code only once per
+test case. +global_setup+ blocks will run once before the first test is run, and
++global_teardown+ will run after all the tests have been run.
+
+These methods, however, are dangerous, and should be used with caution, as
+they might introduce dependencies between your tests if you don't write
+your tests properly. Make sure that any state modified by code run in a
++global_setup+ or +global_teardown+ isn't changed in any of your tests.
+
+Also, you should be aware that the code of +global_setup+ and +global_teardown+
+blocks isn't evaluated in the same context as your tests and normal
++setup+/+teardown+ blocks are, so you can't share instance variables between
+them.
+
+== Nested contexts
+
+Break down your test into logical chunks with nested contexts:
+
+    Protest.context("A user") do
+      setup do
+        @user = User.make
+      end
+
+      context "when validating" do
+        test "validates name" do
+          @user.name = nil
+          assert !@user.valid?
+        end
+
+        # etc, etc
+      end
+
+      context "doing something else" do
+        # your get the idea
+      end
+    end
+
+Any +setup+ or +teardown+ blocks you defined in a context will run in that
+context and in _any_ other context nested in it.
+
+== Pending tests
+
+There are two ways of marking a test as pending. You can declare a test with no
+body:
+
+    Protest.context("Some tests") do
+      test "this test will be marked as pending"
+
+      test "this tests is also pending"
+
+      test "this test isn't pending" do
+        assert true
+      end
+    end
+
+Or you can call the +pending+ method from inside your test.
+
+    Protest.context("Some tests") do
+      test "this test is pending" do
+        pending "oops, this doesn't work"
+        assert false
+      end
+    end
+
+== Reports
+
+Protest can report the output of a test suite in many ways. The library ships
+with a +:progress+ report, and a +:documentation+ report, +:progress+ being the
+default.
+
+=== Progress report
+
+Use this report by calling <tt>Protest.report_with(:progress)</tt> (this isn't
+needed though, since this is the default report.)
+
+The progress report will output the "classic" Test::Unit output of periods for
+passing tests, "F" for failing assertions, "E" for unrescued exceptions, and 
+"P" for pending tests, in full color.
+
+=== Documentation report
+
+Use this report by calling <tt>Protest.report_with(:documentation)</tt>
+
+For each testcase in your suite, this will output the description of the test
+case (whatever you provide TestCase.context), followed by the name of each test
+in that context, one per line. For example:
+
+    Protest.context "A user" do
+      test "has a name"
+      test "has an email"
+
+      context "validations" do
+        test "ensure the email can't be blank"
+      end
+    end
+
+Will output, when run with the +:documentation+ report:
+
+    A user
+    - has a name (Not Yet Implemented)
+    - has an email (Not Yet Implemented)
+
+    A user validations
+    - ensure the email can't be blank (Not Yet Implemented)
+
+(The 'Not Yet Implemented' messages are because the tests have no body. See
+"Pending tests", above.)
+
+This is similar to the specdoc runner in rspec[http://rspec.info].
+
+=== Defining your own reports
+
+This is really, really easy. All you need to do is subclass Report, and
+register your subclass by calling +Protest.add_report+. See the
+documentation for details, or take a look at the source code for
+Protest::Reports::Progress and Protest::Reports::Documentation.
+
+== Legal
+
+Author:: Nicolás Sanguinetti — http://nicolassanguinetti.info
+License:: MIT (see bundled LICENSE file for more info)

data/Rakefile

@@ -0,0 +1,24 @@
+begin
+  require "hanna/rdoctask"
+rescue LoadError
+  require "rake/rdoctask"
+end
+
+require "rake/testtask"
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.title = "API Documentation for Protest"
+  rd.rdoc_files.include("README.rdoc", "LICENSE", "lib/**/*.rb")
+  rd.rdoc_dir = "doc"
+end
+
+begin
+  require "mg"
+  MG.new("protest.gemspec")
+rescue LoadError
+end
+
+Rake::TestTask.new
+
+task :default => :test

data/lib/protest.rb

@@ -0,0 +1,94 @@
+module Protest
+  # 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
+
+  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)
+
+at_exit do
+  Protest.run_all_tests! if Protest.autorun?
+end

data/lib/protest/rails.rb

@@ -0,0 +1,62 @@
+require "protest"
+require "test/unit/assertions"
+require "action_controller/test_case"
+require "webrat"
+
+module Protest
+  module Rails
+    # Wrap all tests in a database transaction.
+    #
+    # TODO: make this optional somehow (yet enabled by default) so users of
+    # other ORMs don't run into problems.
+    module TransactionalTests
+      def run(*args, &block)
+        ActiveRecord::Base.connection.transaction do
+          super(*args, &block)
+          raise ActiveRecord::Rollback
+        end
+      end
+    end
+
+    # You should inherit from this TestCase in order to get rails' helpers
+    # loaded into Protest. These include all the assertions bundled with rails
+    # and your tests being wrapped in a transaction.
+    class TestCase < ::Protest::TestCase
+      include ::Test::Unit::Assertions
+      include ActiveSupport::Testing::Assertions
+      include TransactionalTests
+    end
+
+    class RequestTest < TestCase #:nodoc:
+      %w(response selector tag dom routing model).each do |kind|
+        include ActionController::Assertions.const_get("#{kind.camelize}Assertions")
+      end
+    end
+
+    # Make your integration tests inherit from this class, which bundles the
+    # integration runner included with rails, and webrat's test methods. You
+    # should use webrat for integration tests. Really.
+    class IntegrationTest < RequestTest
+      include ActionController::Integration::Runner
+      include Webrat::Methods
+    end
+  end
+
+  # The preferred way to declare a context (top level) is to use
+  # +Protest.describe+ or +Protest.context+, which will ensure you're using
+  # rails adapter with the helpers you need.
+  def self.context(description, &block)
+    Rails::TestCase.context(description, &block)
+  end
+
+  # Use +Protest.story+ to declare an integration test for your rails app. Note
+  # that the files should still be called 'test/integration/foo_test.rb' if you
+  # want the 'test:integration' rake task to pick them up.
+  def self.story(description, &block)
+    Rails::IntegrationTest.story(description, &block)
+  end
+
+  class << self
+    alias_method :describe, :context
+  end
+end

data/lib/protest/report.rb

@@ -0,0 +1,113 @@
+module Protest
+  class Report
+    # Define an event handler for your report. The different events fired in a
+    # report's life cycle are:
+    #
+    # :start::     Fired by the runner when starting the whole test suite.
+    # :enter::     Fired by the runner when starting a particular test case. It
+    #              will get the test case as an argument.
+    # :test::      Fired by a test before it starts running. It will get the
+    #              instance of TestCase for the given test as an argument.
+    # :assertion:: Fired by a test each time an assertion is run.
+    # :pass::      Fired by a test after it runs successfully without errors.
+    #              It will get an instance of PassedTest as an argument.
+    # :pending::   Fired by a test which doesn't provide a test block or which
+    #              calls TestCase#pending. It will get an instance of
+    #              PendingTest as an argument.
+    # :failure::   Fired by a test in which an assertion failed. It will get an
+    #              instance of FailedTest as an argument.
+    # :error::     Fired by a test where an uncaught exception was found. It
+    #              will get an instance of ErroredTest as an argument.
+    # :exit::      Fired by the runner each time a test case finishes. It will
+    #              take the test case as an argument.
+    # :end::       Fired by the runner at the end of the whole test suite.
+    #
+    # The event handler will receive the report as a first argument, plus any
+    # arguments documented above (depending on the event). It will also ensure
+    # that any handler for the same event declared on an ancestor class is run.
+    def self.on(event, &block)
+      define_method(:"on_#{event}") do |*args|
+        begin
+          super(*args)
+        rescue NoMethodError
+        end
+
+        block.call(self, *args)
+      end
+    end
+
+    on :start do |report|
+      report.instance_eval { @started_at = Time.now }
+    end
+
+    on :pass do |report, passed_test|
+      report.passes << passed_test
+    end
+
+    on :pending do |report, pending_test|
+      report.pendings << pending_test
+    end
+
+    on :failure do |report, failed_test|
+      report.failures << failed_test
+      report.failures_and_errors << failed_test
+    end
+
+    on :error do |report, errored_test|
+      report.errors << errored_test
+      report.failures_and_errors << errored_test
+    end
+
+    on :assertion do |report|
+      report.add_assertion
+    end
+
+    # List all the tests (as PendingTest instances) that were pending.
+    def pendings
+      @pendings ||= []
+    end
+
+    # List all the tests (as PassedTest instances) that passed.
+    def passes
+      @passes ||= []
+    end
+
+    # List all the tests (as FailedTest instances) that failed an assertion.
+    def failures
+      @failures ||= []
+    end
+
+    # List all the tests (as ErroredTest instances) that raised an unrescued
+    # exception.
+    def errors
+      @errors ||= []
+    end
+
+    # Aggregated and ordered list of tests that either failed an assertion or
+    # raised an unrescued exception. Useful for displaying back to the user.
+    def failures_and_errors
+      @failures_and_errors ||= []
+    end
+
+    # Log an assertion was run (whether it succeeded or failed.)
+    def add_assertion
+      @assertions ||= 0
+      @assertions += 1
+    end
+
+    # Number of assertions run during the report.
+    def assertions
+      @assertions || 0
+    end
+
+    # Amount ot tests run (whether passed, pending, failed, or errored.)
+    def total_tests
+      passes.size + failures.size + errors.size + pendings.size
+    end
+
+    # Seconds taken since the test suite started running
+    def time_elapsed
+      Time.now - @started_at
+    end
+  end
+end

data/lib/protest/reports.rb

@@ -0,0 +1,2 @@
+module Protest::Reports # :nodoc:
+end

data/lib/protest/reports/documentation.rb

@@ -0,0 +1,77 @@
+module Protest
+  # For each testcase in your suite, this will output the description of the test
+  # case (whatever you provide TestCase.context), followed by the name of each test
+  # in that context, one per line. For example:
+  #
+  #     Protest.context "A user" do
+  #       test "has a name" do
+  #         ...
+  #       end
+  #
+  #       test "has an email" do
+  #         ...
+  #       end
+  #
+  #       context "validations" do
+  #         test "ensure the email can't be blank" do
+  #           ...
+  #         end
+  #       end
+  #     end
+  #
+  # Will output, when run with the +:documentation+ report:
+  #
+  #     A user
+  #     - has a name
+  #     - has an email
+  #
+  #     A user validations
+  #     - ensure the email can't be blank
+  #
+  # This is based on the specdoc runner in rspec[http://rspec.info].
+  class Reports::Documentation < Report
+    include Utils::Summaries
+    include Utils::ColorfulOutput
+
+    attr_reader :stream #:nodoc:
+
+    # Set the stream where the report will be written to. STDOUT by default.
+    def initialize(stream=STDOUT)
+      @stream = stream
+    end
+
+    on :enter do |report, context|
+      report.puts context.description unless context.tests.empty?
+    end
+
+    on :pass do |report, passed_test|
+      report.puts "- #{passed_test.test_name}", :passed
+    end
+
+    on :failure do |report, failed_test|
+      position = report.failures_and_errors.index(failed_test) + 1
+      report.puts "- #{failed_test.test_name} (#{position})", :failed
+    end
+
+    on :error do |report, errored_test|
+      position = report.failures_and_errors.index(errored_test) + 1
+      report.puts "- #{errored_test.test_name} (#{position})", :errored
+    end
+
+    on :pending do |report, pending_test|
+      report.puts "- #{pending_test.test_name} (#{pending_test.pending_message})", :pending
+    end
+
+    on :exit do |report, context|
+      report.puts unless context.tests.empty?
+    end
+
+    on :end do |report|
+      report.summarize_pending_tests
+      report.summarize_errors
+      report.summarize_test_totals
+    end
+  end
+
+  add_report :documentation, Reports::Documentation
+end

data/lib/protest/reports/progress.rb

@@ -0,0 +1,46 @@
+module Protest
+  # The +:progress+ report will output a +.+ for each passed test in the suite,
+  # a +P+ for each pending test, an +F+ for each test that failed an assertion,
+  # and an +E+ for each test that raised an unrescued exception.
+  #
+  # At the end of the suite it will output a list of all pending tests, with
+  # files and line numbers, and after that a list of all failures and errors,
+  # which also contains the first 3 lines of the backtrace for each.
+  class Reports::Progress < Report
+    include Utils::Summaries
+    include Utils::ColorfulOutput
+
+    attr_reader :stream #:nodoc:
+
+    # Set the stream where the report will be written to. STDOUT by default.
+    def initialize(stream=STDOUT)
+      @stream = stream
+    end
+
+    on :end do |report|
+      report.puts
+      report.puts
+      report.summarize_pending_tests
+      report.summarize_errors
+      report.summarize_test_totals
+    end
+
+    on :pass do |report, pass|
+      report.print ".", :passed
+    end
+
+    on :pending do |report, pending|
+      report.print "P", :pending
+    end
+
+    on :failure do |report, failure|
+      report.print "F", :failed
+    end
+
+    on :error do |report, error|
+      report.print "E", :errored
+    end
+  end
+
+  add_report :progress, Reports::Progress
+end

data/lib/protest/runner.rb

@@ -0,0 +1,42 @@
+module Protest
+  class Runner
+    # Set up the test runner. Takes in a report that will be passed to test
+    # cases for reporting.
+    def initialize(report)
+      @report = report
+    end
+
+    # Run a set of test cases, provided as arguments. This will fire relevant
+    # events on the runner's report, at the +start+ and +end+ of the test run,
+    # and before and after each test case (+enter+ and +exit+.)
+    def run(*test_cases)
+      @report.on_start if @report.respond_to?(:on_start)
+      test_cases.each do |test_case|
+        @report.on_enter(test_case) if @report.respond_to?(:on_enter)
+        test_case.run(self)
+        @report.on_exit(test_case) if @report.respond_to?(:on_exit)
+      end
+      @report.on_end if @report.respond_to?(:on_end)
+    end
+
+    # Run a test and report if it passes, fails, or is pending. Takes the name
+    # of the test as an argument. You can avoid reporting a passed test by
+    # passing +false+ as a second argument.
+    def report(test, report_success=true)
+      @report.on_test(Test.new(test)) if @report.respond_to?(:on_test)
+      yield
+      @report.on_pass(PassedTest.new(test)) if report_success
+    rescue Pending => e
+      @report.on_pending(PendingTest.new(test, e))
+    rescue AssertionFailed => e
+      @report.on_failure(FailedTest.new(test, e))
+    rescue Exception => e
+      @report.on_error(ErroredTest.new(test, e))
+    end
+
+    def assert(condition, message) #:nodoc:
+      @report.add_assertion
+      raise AssertionFailed, message unless condition
+    end
+  end
+end

data/lib/protest/test_case.rb

@@ -0,0 +1,221 @@
+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
+    # Run all tests in this context. Takes a Report instance in order to
+    # provide output.
+    def self.run(result)
+      result.report("#{description} global setup", false) { do_global_setup }
+      tests.each {|test| test.run(result) }
+      result.report("#{description} global teardown", false) { do_global_teardown }
+    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, &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, &block)
+      @test = block
+      @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(runner)
+      @runner = runner
+
+      runner.report(self) do
+        pending if test.nil?
+
+        setup
+        instance_eval(&test)
+        teardown
+      end
+    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")
+      @runner.assert(condition, message)
+    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
+    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
+  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 ||= Utils::BacktraceFilter.filter(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.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/utils/backtrace_filter.rb

@@ -0,0 +1,19 @@
+module Protest
+  module Utils
+    # Small utility object to filter an error's backtrace and remove any mention
+    # of Testicle's own files.
+    module BacktraceFilter
+      # Path to the library's 'lib' dir.
+      BASE_PATH = /^#{Regexp.escape(File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__)))))}/
+
+      # Filter the backtrace, removing any reference to files located in
+      # BASE_PATH.
+      def self.filter(backtrace)
+        backtrace.reject do |line|
+          file = line.split(":").first
+          File.expand_path(file) =~ BASE_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,116 @@
+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
+          puts indent("With `#{error.error_message}'", 6 + pad_indexes), colorize_as
+          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=" ")
+          Array(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/protest.gemspec

@@ -0,0 +1,38 @@
+Gem::Specification.new do |s|
+  s.name    = "protest"
+  s.version = "0.2"
+  s.date    = "2009-09-11"
+
+  s.description = "Protest is a tiny, simple, and easy-to-extend test framework"
+  s.summary     = s.description
+  s.homepage    = "http://github.com/foca/protest"
+
+  s.authors = ["Nicolás Sanguinetti"]
+  s.email   = "contacto@nicolassanguinetti.info"
+
+  s.require_paths     = ["lib"]
+  s.rubyforge_project = "protest"
+  s.has_rdoc          = true
+  s.rubygems_version  = "1.3.1"
+
+  s.files = %w[
+.gitignore
+LICENSE
+README.rdoc
+Rakefile
+protest.gemspec
+lib/protest.rb
+lib/protest/utils.rb
+lib/protest/utils/backtrace_filter.rb
+lib/protest/utils/summaries.rb
+lib/protest/utils/colorful_output.rb
+lib/protest/test_case.rb
+lib/protest/tests.rb
+lib/protest/runner.rb
+lib/protest/report.rb
+lib/protest/reports.rb
+lib/protest/reports/progress.rb
+lib/protest/reports/documentation.rb
+lib/protest/rails.rb
+]
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: protest
+version: !ruby/object:Gem::Version 
+  version: "0.2"
+platform: ruby
+authors: 
+- "Nicol\xC3\xA1s Sanguinetti"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-11 00:00:00 -03:00
+default_executable: 
+dependencies: []
+
+description: Protest is a tiny, simple, and easy-to-extend test framework
+email: contacto@nicolassanguinetti.info
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- protest.gemspec
+- lib/protest.rb
+- lib/protest/utils.rb
+- lib/protest/utils/backtrace_filter.rb
+- lib/protest/utils/summaries.rb
+- lib/protest/utils/colorful_output.rb
+- lib/protest/test_case.rb
+- lib/protest/tests.rb
+- lib/protest/runner.rb
+- lib/protest/report.rb
+- lib/protest/reports.rb
+- lib/protest/reports/progress.rb
+- lib/protest/reports/documentation.rb
+- lib/protest/rails.rb
+has_rdoc: true
+homepage: http://github.com/foca/protest
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: protest
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 3
+summary: Protest is a tiny, simple, and easy-to-extend test framework
+test_files: []
+