test-unit 3.2.0 → 3.3.6

data/lib/test/unit.rb

@@ -3,10 +3,10 @@ require 'test/unit/autorunner'
 
 module Test # :nodoc:
   #
-  # = Test::Unit - Ruby Unit Testing Framework
-  # 
-  # == Introduction
-  # 
+  # # Test::Unit - Ruby Unit Testing Framework
+  #
+  # ## Introduction
+  #
   # Unit testing is making waves all over the place, largely due to the
   # fact that it is a core practice of XP. While XP is great, unit testing
   # has been around for a long time and has always been a good idea. One
@@ -18,19 +18,19 @@ module Test # :nodoc:
   # as possible, you slowly build up a wall of things that cannot break
   # without you immediately knowing about it. This is when unit testing
   # hits its peak usefulness.
-  # 
+  #
   # Enter Test::Unit, a framework for unit testing in Ruby, helping you to
   # design, debug and evaluate your code by making it easy to write and
   # have tests for it.
-  # 
-  # 
-  # == Notes
-  # 
+  #
+  #
+  # ## Notes
+  #
   # Test::Unit has grown out of and superceded Lapidary.
-  # 
-  # 
-  # == Feedback
-  # 
+  #
+  #
+  # ## Feedback
+  #
   # I like (and do my best to practice) XP, so I value early releases,
   # user feedback, and clean, simple, expressive code. There is always
   # room for improvement in everything I do, and Test::Unit is no
@@ -41,79 +41,84 @@ module Test # :nodoc:
   # hear about any successes you have with Test::Unit, and any
   # documentation you might add will be greatly appreciated. My contact
   # info is below.
-  # 
-  # 
-  # == Contact Information
-  # 
-  # A lot of discussion happens about Ruby in general on the ruby-talk
-  # mailing list (http://www.ruby-lang.org/en/ml.html), and you can ask
-  # any questions you might have there. I monitor the list, as do many
-  # other helpful Rubyists, and you're sure to get a quick answer. Of
-  # course, you're also welcome to email me (Nathaniel Talbott) directly
-  # at mailto:testunit@talbott.ws, and I'll do my best to help you out.
-  # 
-  # 
-  # == Credits
-  # 
+  #
+  #
+  # ## Contact Information
+  #
+  #   * [GitHub issues on
+  #     test-unit/test-unit](https://github.com/test-unit/test-unit/issues):
+  #     If you have any issues, please report them to here.
+  #
+  #   * [GitHub pull requests on
+  #     test-unit/test-unit](https://github.com/test-unit/test-unit/pulls):
+  #     If you have any patches, please report them to here.
+  #
+  #   * [ruby-talk mailing
+  #     list](https://www.ruby-lang.org/en/community/mailing-lists/):
+  #     If you have any questions, you can ask them here.
+  #
+  #
+  # ## Credits
+  #
   # I'd like to thank...
-  # 
+  #
   # Matz, for a great language!
-  # 
+  #
   # Masaki Suketa, for his work on RubyUnit, which filled a vital need in
   # the Ruby world for a very long time. I'm also grateful for his help in
   # polishing Test::Unit and getting the RubyUnit compatibility layer
   # right. His graciousness in allowing Test::Unit to supercede RubyUnit
   # continues to be a challenge to me to be more willing to defer my own
   # rights.
-  # 
+  #
   # Ken McKinlay, for his interest and work on unit testing, and for his
   # willingness to dialog about it. He was also a great help in pointing
   # out some of the holes in the RubyUnit compatibility layer.
-  # 
+  #
   # Dave Thomas, for the original idea that led to the extremely simple
   # "require 'test/unit'", plus his code to improve it even more by
   # allowing the selection of tests from the command-line. Also, without
   # RDoc, the documentation for Test::Unit would stink a lot more than it
   # does now.
-  # 
+  #
   # Everyone who's helped out with bug reports, feature ideas,
   # encouragement to continue, etc. It's a real privilege to be a part of
   # the Ruby community.
-  # 
+  #
   # The guys at RoleModel Software, for putting up with me repeating, "But
   # this would be so much easier in Ruby!" whenever we're coding in Java.
-  # 
+  #
   # My Creator, for giving me life, and giving it more abundantly.
-  # 
-  # 
-  # == License
-  # 
+  #
+  #
+  # ## License
+  #
   # Test::Unit is copyright (c) 2000-2003 Nathaniel Talbott. It is free
   # software, and is distributed under the Ruby license. See the COPYING
   # file.
-  # 
+  #
   # Exception: lib/test/unit/diff.rb is copyright (c)
   # 2008-2010 Kouhei Sutou and 2001-2008 Python Software
   # Foundation. It is free software, and is distributed
   # under the Ruby license and/or the PSF license. See the
   # COPYING file and PSFL file.
-  # 
-  # == Warranty
-  # 
+  #
+  # ## Warranty
+  #
   # This software is provided "as is" and without any express or
   # implied warranties, including, without limitation, the implied
   # warranties of merchantibility and fitness for a particular
   # purpose.
-  # 
-  # 
-  # == Author
-  # 
+  #
+  #
+  # ## Author
+  #
   # Nathaniel Talbott.
   # Copyright (c) 2000-2003, Nathaniel Talbott
   #
   # ----
   #
-  # = Usage
+  # # Usage
   #
   # The general idea behind unit testing is that you write a _test_
   # _method_ that makes certain _assertions_ about your code, working
@@ -125,7 +130,7 @@ module Test # :nodoc:
   # pieces.
   #
   #
-  # == Assertions
+  # ## Assertions
   #
   # These are the heart of the framework. Think of an assertion as a
   # statement of expected outcome, i.e. "I assert that x should be equal
@@ -137,7 +142,7 @@ module Test # :nodoc:
   # of the current assertions, see Test::Unit::Assertions.
   #
   #
-  # == Test Method & Test Fixture
+  # ## Test Method & Test Fixture
   #
   # Obviously, these assertions have to be called within a context that
   # knows about them and can do something meaningful with their
@@ -197,7 +202,7 @@ module Test # :nodoc:
   #     end
   #
   #
-  # == Test Runners
+  # ## Test Runners
   #
   # So, now you have this great test class, but you still
   # need a way to run it and view any failures that occur
@@ -208,10 +213,10 @@ module Test # :nodoc:
   # runner simply set default test runner ID to
   # Test::Unit::AutoRunner:
   #
-  #    require 'test/unit'
-  #    Test::Unit::AutoRunner.default_runner = "gtk2"
+  #     require 'test/unit'
+  #     Test::Unit::AutoRunner.default_runner = "gtk2"
   #
-  # == Test Suite
+  # ## Test Suite
   #
   # As more and more unit tests accumulate for a given project, it
   # becomes a real drag running them one at a time, and it also
@@ -228,17 +233,17 @@ module Test # :nodoc:
   # 'test/unit'. What does this mean? It means you could
   # write the above test case like this instead:
   #
-  #  require 'test/unit'
-  #  require 'test_myfirsttests'
-  #  require 'test_moretestsbyme'
-  #  require 'test_anothersetoftests'
+  #     require 'test/unit'
+  #     require 'test_myfirsttests'
+  #     require 'test_moretestsbyme'
+  #     require 'test_anothersetoftests'
   #
   # Test::Unit is smart enough to find all the test cases existing in
   # the ObjectSpace and wrap them up into a suite for you. It then runs
   # the dynamic suite using the console TestRunner.
   #
   #
-  # == Configuration file
+  # ## Configuration file
   #
   # Test::Unit reads 'test-unit.yml' in the current working
   # directory as Test::Unit's configuration file. It can
@@ -254,53 +259,58 @@ module Test # :nodoc:
   #
   # Here are sample color scheme definitions:
   #
-  #   color_schemes:
-  #     inverted:
-  #       success:
-  #         name: red
-  #         bold: true
-  #       failure:
-  #         name: green
-  #         bold: true
-  #     other_scheme:
-  #       ...
+  #     color_schemes:
+  #       inverted:
+  #         success:
+  #           name: red
+  #           bold: true
+  #         failure:
+  #           name: green
+  #           bold: true
+  #       other_scheme:
+  #         ...
   #
   # Here are the syntax of color scheme definitions:
   #
-  #  color_schemes:
-  #    SCHEME_NAME:
-  #      EVENT_NAME:
-  #        name: COLOR_NAME
-  #        intensity: BOOLEAN
-  #        bold: BOOLEAN
-  #        italic: BOOLEAN
-  #        underline: BOOLEAN
-  #      ...
-  #    ...
-  #
-  # SCHEME_NAME:: the name of the color scheme
-  # EVENT_NAME:: one of [success, failure, pending,
-  #              omission, notification, error]
-  # COLOR_NAME:: one of [black, red, green, yellow, blue,
-  #              magenta, cyan, white]
-  # BOOLEAN:: true or false
+  #     color_schemes:
+  #       SCHEME_NAME:
+  #         EVENT_NAME:
+  #           name: COLOR_NAME
+  #           intensity: BOOLEAN
+  #           bold: BOOLEAN
+  #           italic: BOOLEAN
+  #           underline: BOOLEAN
+  #         ...
+  #       ...
+  #
+  # SCHEME_NAME
+  # : the name of the color scheme
+  #
+  # EVENT_NAME
+  # : one of [success, failure, pending, omission, notification, error]
+  #
+  # COLOR_NAME
+  # : one of [black, red, green, yellow, blue, magenta, cyan, white]
+  #
+  # BOOLEAN
+  # : true or false
   #
   # You can use the above 'inverted' color scheme with the
   # following configuration:
   #
-  #   runner: console
-  #   console_options:
-  #     color_scheme: inverted
-  #   color_schemes:
-  #     inverted:
-  #       success:
-  #         name: red
-  #         bold: true
-  #       failure:
-  #         name: green
-  #         bold: true
+  #     runner: console
+  #     console_options:
+  #       color_scheme: inverted
+  #     color_schemes:
+  #       inverted:
+  #         success:
+  #           name: red
+  #           bold: true
+  #         failure:
+  #           name: green
+  #           bold: true
   #
-  # == Questions?
+  # ## Questions?
   #
   # I'd really like to get feedback from all levels of Ruby
   # practitioners about typos, grammatical errors, unclear statements,
@@ -331,51 +341,53 @@ module Test # :nodoc:
       # To register multiple hooks, call this method multiple times.
       #
       # Here is an example test case:
-      #   Test::Unit.at_start do
-      #     # ...
-      #   end
-      #
-      #   class TestMyClass1 < Test::Unit::TestCase
-      #     class << self
-      #       def startup
-      #         # ...
-      #       end
-      #     end
       #
-      #     def setup
+      #     Test::Unit.at_start do
       #       # ...
       #     end
       #
-      #     def test_my_class1
-      #       # ...
-      #     end
+      #     class TestMyClass1 < Test::Unit::TestCase
+      #       class << self
+      #         def startup
+      #           # ...
+      #         end
+      #       end
       #
-      #     def test_my_class2
-      #       # ...
-      #     end
-      #   end
+      #       def setup
+      #         # ...
+      #       end
       #
-      #   class TestMyClass2 < Test::Unit::TestCase
-      #     class << self
-      #       def startup
+      #       def test_my_class1
       #         # ...
       #       end
-      #     end
       #
-      #     def setup
-      #       # ...
+      #       def test_my_class2
+      #         # ...
+      #       end
       #     end
       #
-      #     def test_my_class1
-      #       # ...
-      #     end
+      #     class TestMyClass2 < Test::Unit::TestCase
+      #       class << self
+      #         def startup
+      #           # ...
+      #         end
+      #       end
       #
-      #     def test_my_class2
-      #       # ...
+      #       def setup
+      #         # ...
+      #       end
+      #
+      #       def test_my_class1
+      #         # ...
+      #       end
+      #
+      #       def test_my_class2
+      #         # ...
+      #       end
       #     end
-      #   end
       #
       # Here is a call order:
+      #
       # * at_start
       # * TestMyClass1.startup
       # * TestMyClass1#setup
@@ -415,51 +427,53 @@ module Test # :nodoc:
       # To register multiple hooks, call this method multiple times.
       #
       # Here is an example test case:
-      #   Test::Unit.at_exit do
-      #     # ...
-      #   end
-      #
-      #   class TestMyClass1 < Test::Unit::TestCase
-      #     class << self
-      #       def shutdown
-      #         # ...
-      #       end
-      #     end
       #
-      #     def teardown
+      #     Test::Unit.at_exit do
       #       # ...
       #     end
       #
-      #     def test_my_class1
-      #       # ...
-      #     end
+      #     class TestMyClass1 < Test::Unit::TestCase
+      #       class << self
+      #         def shutdown
+      #           # ...
+      #         end
+      #       end
       #
-      #     def test_my_class2
-      #       # ...
-      #     end
-      #   end
+      #       def teardown
+      #         # ...
+      #       end
       #
-      #   class TestMyClass2 < Test::Unit::TestCase
-      #     class << self
-      #       def shutdown
+      #       def test_my_class1
       #         # ...
       #       end
-      #     end
       #
-      #     def teardown
-      #       # ...
+      #       def test_my_class2
+      #         # ...
+      #       end
       #     end
       #
-      #     def test_my_class1
-      #       # ...
-      #     end
+      #     class TestMyClass2 < Test::Unit::TestCase
+      #       class << self
+      #         def shutdown
+      #           # ...
+      #         end
+      #       end
       #
-      #     def test_my_class2
-      #       # ...
+      #       def teardown
+      #         # ...
+      #       end
+      #
+      #       def test_my_class1
+      #         # ...
+      #       end
+      #
+      #       def test_my_class2
+      #         # ...
+      #       end
       #     end
-      #   end
       #
       # Here is a call order:
+      #
       # * TestMyClass1#test_my_class1
       # * TestMyClass1#teardown
       # * TestMyClass1#test_my_class2