protest 0.4.2 → 0.5.0

data/.gitignore

@@ -1,2 +1,4 @@
 doc
 dist
+tmp
+*.rbc

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+### v0.5.0
+
+* Added ability of defining the report to be used in the `PROTEST_REPORT`
+  environment variable.
+* `Documentation` is the new default report.
+* Deprecated `global_setup` and `global_teardown` methods.
+* Deprecated `before` and `after` aliases for `setup` and `teardown`.
+* Deprecated `story` and `scenario` aliases.
+* Removed `Stories` report.
+* Removed `Protest::Stories` module.
+* Refactored reports.
+* Modified Summaries module to include the full filtered backtrace in all reports.

data/LICENSE

@@ -1,7 +1,7 @@
 (The MIT License)
 
 Copyright (c) 2009 Nicolas Sanguinetti
-Copyright (c) 2010 Matías Flores
+Copyright (c) 2010-2013 Matías Flores
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,256 @@
+# Protest [<img src="https://secure.travis-ci.org/matflores/protest.png?branch=master" alt="Build Status" />](http://travis-ci.org/matflores/protest)
+
+Protest is a tiny, simple, and easy-to-extend testing framework for ruby.
+
+## Get it
+
+```
+gem install protest
+```
+
+## Usage
+
+```ruby
+require "protest"
+
+Protest.describe "A user" do
+  setup do
+    @user = User.new(name: "John Doe", email: "john@example.org")
+  end
+
+  it "has a name" do
+    assert_equal "John Doe", @user.name
+  end
+
+  it "has an email" do
+    assert_equal "john@example.org", @user.email
+  end
+end
+```
+
+Use `Protest.context` or `Protest.describe` at the top level to define
+a new test case. Inside the block, you can use `test`, `it` or `should`
+for defining each individual test.
+
+## Setup and teardown
+
+If you need to run code before or after each test, declare a `setup` or
+`teardown` block:
+
+```ruby
+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.
+
+## Nested contexts
+
+Break down your test into logical chunks with nested contexts:
+
+```ruby
+Protest.describe "A user" do
+  setup do
+    @user = User.make
+  end
+
+  context "when validating" do
+    it "validates name" do
+      @user.name = nil
+      assert !@user.valid?
+    end
+
+    # etc, etc
+  end
+
+  context "doing something else" do
+    # you 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:
+
+```ruby
+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:
+
+```ruby
+Protest.context "Some tests" do
+  test "this test is pending" do
+    pending "oops, this doesn't work"
+    assert false
+  end
+end
+```
+
+## Assertions
+
+Protest includes just three basic assertion methods:
+
+* assert(condition, message)
+
+  Ensure that a condition is met, otherwise it raises an `AssertionFailed`
+exception. The second argument is optional and it is used to override
+the default failure message.
+
+* assert_equal(expected, actual, message)
+
+  Syntax sugar for `assert(expected == actual, message)`.
+
+* assert_raise(exception, message) do ... end
+
+  Passes if the code block raises the specified exception. If no exception
+is specified, this assertion passes if _any_ exception is raised inside
+the block. The second argument is optional and it is used to override
+the default failure message.
+
+## Custom assertions
+
+If you want to add more assertion methods, just define new methods that
+rely on `assert`.
+
+For example:
+
+```ruby
+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
+`matchers.rb` 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 few reports defined by default.
+
+You can select which report to use using the `report_with` method:
+
+```ruby
+Protest.report_with(:documentation)
+Protest.report_with(:progress)
+Protest.report_with(:my_awesome_custom_report)
+```
+
+By default, Protest will use the report defined in the `PROTEST_REPORT`
+environment variable. If this variable is not defined, the Documentation
+report will be used.
+
+### Progress report
+
+Use this report by calling `Protest.report_with(:progress)`.
+
+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 `Protest.report_with(:progress)`.
+
+For each testcase in your suite, this will output the description of the test
+case (whatever you passed to `TestCase.context`), followed by the name of each
+test in that context, one per line. For example:
+
+```ruby
+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).
+
+### Summary report
+
+Use this report by calling `Protest.report_with(:summary)`.
+
+This report will output a brief summary with the total number of tests,
+assertions, passed tests, pending tests, failed tests and errors.
+
+### Turn report
+
+Use this report by calling `Protest.report_with(:turn)`.
+
+This report displays each test on a separate line with failures being displayed
+immediately instead of at the end of the tests.
+
+You might find this useful when running a large test suite, as it can be very
+frustrating to see a failure (....F...) and then have to wait until all the
+tests finish before you can see what the exact failure was.
+
+This report is based on the output displayed by [TURN](http://github.com/TwP/turn),
+Test::Unit Reporter (New) by Tim Pease.
+
+### 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`.
+
+## Using Rails?
+
+If you are using Rails you may want to take a look at [protest-rails](http://github.com/matflores/protest-rails).
+
+## Credits
+
+Protest was created by [Nicolás Sanguinetti](http://nicolassanguinetti.info)
+and is currently maintained by [Matías Flores](http://matflores.com).
+
+## License
+
+Distributed under the terms of the MIT license.
+See bundled [LICENSE](https://github.com/matflores/protest/blob/master/LICENSE)
+file for more info.

data/Rakefile

@@ -1,24 +1,5 @@
-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 do |t|
   t.libs << "test"
 end

data/lib/protest.rb

@@ -1,6 +1,4 @@
 module Protest
-  VERSION = "0.4.2"
-
   # Exception raised when an assertion fails. See TestCase#assert
   class AssertionFailed < StandardError; end
 
@@ -19,14 +17,7 @@ module Protest
   #
   # 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
+    reports[name] = report
   end
 
   # Set to +false+ to avoid running tests +at_exit+. Default is +true+.
@@ -45,7 +36,7 @@ module Protest
   #
   # See Protest.add_test_case and Protest.report_with
   def self.run_all_tests!(*report_args)
-    Runner.new(@report).run(*available_test_cases)
+    Runner.new(@report).run(*test_cases)
   end
 
   # Select the name of the Report to use when running tests. See
@@ -53,7 +44,7 @@ module Protest
   #
   # Any extra arguments will be forwarded to the report's #initialize method.
   #
-  # The default report is Protest::Reports::Progress
+  # The default report is Protest::Reports::Documentation
   def self.report_with(name, *report_args)
     @report = report(name, *report_args)
   end
@@ -62,7 +53,7 @@ module Protest
   # 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)
+    reports.fetch(name).new(*report_args)
   end
 
   # Set what object will filter the backtrace. It must respond to
@@ -76,17 +67,17 @@ module Protest
     @backtrace_filter
   end
 
-  def self.available_test_cases
+  def self.test_cases
     @test_cases ||= []
   end
-  private_class_method :available_test_cases
 
-  def self.available_reports
-    @available_reports ||= {}
+  def self.reports
+    @reports ||= {}
   end
-  private_class_method :available_reports
+  private_class_method :reports
 end
 
+require "protest/version"
 require "protest/utils"
 require "protest/utils/backtrace_filter"
 require "protest/utils/summaries"
@@ -100,10 +91,9 @@ require "protest/reports/progress"
 require "protest/reports/documentation"
 require "protest/reports/turn"
 require "protest/reports/summary"
-require "protest/reports/stories"
 
 Protest.autorun = true
-Protest.report_with(:progress)
+Protest.report_with((ENV["PROTEST_REPORT"] || "documentation").to_sym)
 Protest.backtrace_filter = Protest::Utils::BacktraceFilter.new
 
 at_exit do

data/lib/protest/report.rb

@@ -1,5 +1,15 @@
 module Protest
   class 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
+
     # Define an event handler for your report. The different events fired in a
     # report's life cycle are:
     #

data/lib/protest/reports/documentation.rb

@@ -30,16 +30,6 @@ module Protest
   #
   # 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

data/lib/protest/reports/progress.rb

@@ -7,16 +7,6 @@ module Protest
   # 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

data/lib/protest/reports/summary.rb

@@ -3,16 +3,6 @@ module Protest
   # of tests, assertions, passed tests, pending tests, failed tests and
   # errors.
   class Reports::Summary < 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.summarize_test_totals
     end