mcmire-protest 0.2.4

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,200 @@
+= 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_equal "John Doe", @user.name
+      end
+
+      test "has an email" do
+        assert_equal "john@example.org", @user.email
+      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 v0.2.3
+
+== 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
+
+== Custom assertions
+
+By default Protest bundles all the assertions defined in Test::Unit (it
+literally requires them), so check its documentation for all the goodness.
+
+If you want to add assertions, just define methods that rely on +assert+ or
++assert_block+. The former takes a boolean and an optional error message as
+arguments, while the latter takes an optional error message as an argument and
+a block. The assertions is considered to fail if the block evaluates to neither
++false+ nor +nil+.
+
+For example:
+
+    module AwesomenessAssertions
+      def assert_awesomeness(object)
+        assert object.awesome?, "#{object.inspect} is not awesome enough"
+      end
+    end
+
+    class Protest::TestCase
+      include AwesomenessAssertions
+    end
+
+You could also define rspec-like matchers if you like that style. See
+<tt>matchers.rb</tt> in the examples directory for an example.
+
+== Reports
+
+Protest can report the output of a test suite in many ways. The library ships
+with a <tt>:progress</tt> report, and a <tt>:documentation</tt> report,
+<tt>:progress</tt> being the default.
+
+=== Progress report
+
+This is the default option, but you can force this by calling 
+<tt>Protest.report_with(:progress)</tt>.
+
+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 <tt>:documentation</tt> 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/rails.rb

@@ -0,0 +1,80 @@
+require "protest"
+require "test/unit/assertions"
+require "action_controller/test_case"
+
+begin
+  require "webrat"
+rescue LoadError
+  $no_webrat = true
+end
+
+module Protest
+  module Rails
+    # Exclude rails' files from the errors
+    class BacktraceFilter < Utils::BacktraceFilter
+      include ::Rails::BacktraceFilterForTestUnit
+
+      def filter_backtrace(backtrace, prefix=nil)
+        super(backtrace, prefix).reject do |line|
+          line.starts_with?("/")
+        end
+      end
+    end
+
+    # 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 unless $no_webrat
+    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
+
+  self.backtrace_filter = Rails::BacktraceFilter.new
+end

data/lib/protest/report.rb

@@ -0,0 +1,121 @@
+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 :test do |report, test|
+      report.tests << test
+    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
+
+    def tests
+      @tests ||= []
+    end
+
+    # Amount ot tests run (whether passed, pending, failed, or errored.)
+    def total_tests
+      tests.size
+    end
+
+    # Seconds taken since the test suite started running
+    def time_elapsed
+      Time.now - @started_at
+    end
+  end
+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/reports.rb

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

data/lib/protest/runner.rb

@@ -0,0 +1,39 @@
+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. By passing +true+ as the second argument, you
+    # force any exceptions to be re-raied and the test not reported as a pass
+    # after it finishes (for global setup/teardown blocks)
+    def report(test, running_global_setup_or_teardown=false)
+      @report.on_test(Test.new(test)) if @report.respond_to?(:on_test) && !running_global_setup_or_teardown
+      test.run(@report)
+      @report.on_pass(PassedTest.new(test)) unless running_global_setup_or_teardown
+    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))
+      raise if running_global_setup_or_teardown
+    end
+  end
+end