Class Test::Unit::TestCase
In: lib/test/unit/testcase.rb
Parent: Object

Ties everything together. If you subclass and add your own test methods, it takes care of making them into tests and wrapping those tests into a suite. It also does the nitty-gritty of actually running an individual test and collecting its results into a Test::Unit::TestResult object.

You can run two hooks before/after a TestCase run.

Example: 

    class TestMyClass < Test::Unit::TestCase
      class << self
        def startup
          ...
        end

        def shutdown
          ...
        end
      end

      def setup
        ...
      end

      def cleanup
        ...
      end

      def teardown
        ...
      end

      def test_my_method1
        ...
      end

      def test_my_method2
        ...
      end
    end

Here is a call order:

  1. startup
  2. setup
  3. test_my_method1
  4. cleanup
  5. teardown
  6. setup
  7. test_my_method2
  8. cleanup
  9. teardown
  10. shutdown

You can set an attribute to each test.

Example: 

    class TestMyClass < Test::Unit::TestCase
      attribute :speed, :fast
      def test_my_fast_method
        # You can get the attribute via `self[]`
        self[:speed] # => :fast
        ...
      end

      attribute :speed, :slow
      def test_my_slow_method
        self[:speed] # => :slow
        ...
      end
    end

Methods

==   add_pass   cleanup   data   data_label   default_test   description   description   elapsed_time   find_locations   interrupted?   local_name   name   new   passed?   problem_occurred   run   setup   shutdown   size   start_time   startup   sub_test_case   suite   teardown   test   test_defined?   test_order   test_order=   to_s  

Included Modules

Attribute Fixture ExceptionHandler ErrorHandler FailureHandler TestCasePendingSupport TestCaseOmissionSupport TestCaseNotificationSupport Priority Data Assertions Util::BacktraceFilter Util::Output

Classes and Modules

Class Test::Unit::TestCase::InternalData

Attributes

method_name  [R] 

Public Class methods

description(value, target=nil)

Describes a test.

The following example associates "register a normal user" description with "test_register" test. 

  description "register a normal user"
  def test_register
    ...
  end
new(test_method_name)

Creates a new instance of the fixture for running the test represented by test_method_name.

shutdown()

Called after every test case runs. Can be used to tear down fixture information used in test case scope.

Here is an example test case: 

  class TestMyClass < Test::Unit::TestCase
    class << self
      def shutdown
        ...
      end
    end

    def teardown
      ...
    end

    def test_my_class1
      ...
    end

    def test_my_class2
      ...
    end
  end

Here is a call order:

Note that you should not assume test order. Tests should be worked in any order.

startup()

Called before every test case runs. Can be used to set up fixture information used in test case scope.

Here is an example test case: 

  class TestMyClass < Test::Unit::TestCase
    class << self
      def startup
        ...
      end
    end

    def setup
      ...
    end

    def test_my_class1
      ...
    end

    def test_my_class2
      ...
    end
  end

Here is a call order:

  • startup
  • setup
  • test_my_class1 (or test_my_class2)
  • setup
  • test_my_class2 (or test_my_class1)

Note that you should not assume test order. Tests should be worked in any order.

sub_test_case(name, &block)

Defines a sub test case.

This is a syntax sugar. The both of the following codes are the same in meaning:

Standard: 

  class TestParent < Test::Unit::TestCase
    class TestChild < self
      def test_in_child
      end
    end
  end

Syntax sugar: 

  class TestParent < Test::Unit::TestCase
    sub_test_case("TestChild") do
      def test_in_child
      end
    end
  end

The difference of them are the following:

  • Test case created by {sub_test_case} is an anonymous class. So you can‘t refer the test case by name.
  • The class name of class style must follow constant naming rule in Ruby. But the name of test case created by {sub_test_case} doesn‘t need to follow the rule. For example, you can use a space in name such as "child test".

@param name [String] The name of newly created sub test case. @yield 

  The block is evaluated under the newly created sub test
  case class context.

@return [Test::Unit::TestCase] Created sub test case class.

suite()

Rolls up all of the test* methods in the fixture into one suite, creating a new instance of the fixture for each method.

test(*test_description_or_targets, &block)

Defines a test in declarative syntax or marks following method as a test method.

In declarative syntax usage, the following two test definitions are the almost same: 

  description "register user"
  def test_register_user
    ...
  end

  test "register user" do
    ...
  end

In test method mark usage, the "my_test_method" is treated as a test method: 

  test
  def my_test_method
    assert_equal("call me", ...)
  end
test_defined?(query)

Checks whether a test that is matched the query is defined.

@option query [String] :path (nil) 

  the path where a test is defined in.

@option query [Numeric] :line (nil) 

  the line number where a test is defined at.

@option query [String] :method_name (nil) 

  the method name for a test.
test_order()

Returns the current test order. This returns +:alphabetic+ by default.

test_order=(order)

Sets the current test order.

Here are the available order:

:alphabetic
Default. Tests are sorted in alphabetic order.
:random
Tests are sorted in random order.
:defined
Tests are sorted in defined order.

Public Instance methods

==(other)

It‘s handy to be able to compare TestCase instances.

add_pass()

Notify that the test is passed. Normally, it is not needed because run calls it automatically. If you want to override run, it is not a good idea. Please contact test-unit developers. We will help you without your custom run. For example, we may add a new hook in run.

This is a public API for developers who extend test-unit.

@return [void]

cleanup()

Called after every test method runs but the test method isn‘t marked as ‘passed’. Can be used to clean up and/or verify tested condition. e.g. Can be used to verify mock.

You can add additional cleanup tasks by the following code: 

  class TestMyClass < Test::Unit::TestCase
    def cleanup
      ...
    end

    cleanup
    def my_cleanup1
      ...
    end

    cleanup do
      ... # cleanup callback1
    end

    cleanup
    def my_cleanup2
      ...
    end

    cleanup do
      ... # cleanup callback2
    end

    def test_my_class
      ...
    end
  end

Here is a call order:

data()

Returns test data for the test. If the test isn‘t associated with any test data, it returns nil.

data_label()

Returns a label of test data for the test. If the test isn‘t associated with any test data, it returns nil.

description()

Returns a description for the test. A description will be associated by Test::Unit::TestCase.test or Test::Unit::TestCase.description.

Returns a name for the test for no description test.

elapsed_time()

Returns elapsed time for the test was ran.

interrupted?()

Returns whether the test is interrupted.

local_name()

Returns a human-readable name for the specific test that this instance of TestCase represents.

`local_name` doesn‘t include class name. `name` includes class name.

name()

Returns a human-readable name for the specific test that this instance of TestCase represents.

passed?()

Returns whether this individual test passed or not. Primarily for use in teardown so that artifacts can be left behind if the test fails.

problem_occurred()

Notify that a problem is occurred in the test. It means that the test is a failed test. If any failed tests exist in test suites, the test process exits with failure exit status.

This is a public API for developers who extend test-unit.

@return [void]

run(result) {|STARTED, name| ...}

Runs the individual test method represented by this instance of the fixture, collecting statistics, failures and errors in result.

setup()

Called before every test method runs. Can be used to set up fixture information.

You can add additional setup tasks by the following code: 

  class TestMyClass < Test::Unit::TestCase
    def setup
      ...
    end

    setup
    def my_setup1
      ...
    end

    setup do
      ... # setup callback1
    end

    setup
    def my_setup2
      ...
    end

    setup do
      ... # setup callback2
    end

    def test_my_class
      ...
    end
  end

Here is a call order:

start_time()

Returns a Time at the test was started.

teardown()

Called after every test method runs. Can be used to tear down fixture information.

You can add additional teardown tasks by the following code: 

  class TestMyClass < Test::Unit::TestCase
    def teardown
      ...
    end

    teardown
    def my_teardown1
      ...
    end

    teardown do
      ... # teardown callback1
    end

    teardown
    def my_teardown2
      ...
    end

    teardown do
      ... # teardown callback2
    end

    def test_my_class
      ...
    end
  end

Here is a call order:

to_s()

Overridden to return name.

[Validate]