Test::Unit::TestCase

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

# File lib/test/unit/testcase.rb, line 292
def description(value, target=nil)
  targets = [target].compact
  attribute(:description, value, {}, *targets)
end

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

# File lib/test/unit/testcase.rb, line 394
def initialize(test_method_name)
  @method_name = test_method_name
  @internal_data = InternalData.new
end

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:

• test_my_class1 (or test_my_class2)

• teardown

• test_my_class2 (or test_my_class1)

• teardown

• shutdown

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

# File lib/test/unit/testcase.rb, line 212
def shutdown
end

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.

# File lib/test/unit/testcase.rb, line 176
def startup
end

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::UnitTestCase
  class TestChild < self
    def test_in_child
    end
  end
end

Syntax sugar:

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

The diffrence 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 evaludated under the newly created sub test
case class context.

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

# File lib/test/unit/testcase.rb, line 332
def sub_test_case(name, &block)
  sub_test_case = Class.new(self) do
    singleton_class = class << self; self; end
    singleton_class.send(:define_method, :name) do
      name
    end
  end
  sub_test_case.class_eval(&block)
  sub_test_case
end

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

# File lib/test/unit/testcase.rb, line 137
def suite
  suite_creator = TestSuiteCreator.new(self)
  suite_creator.create
end

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

# File lib/test/unit/testcase.rb, line 258
def test(*test_description_or_targets, &block)
  if block_given?
    test_description = test_description_or_targets.first
    if test_description.nil?
      raise ArgumentError, "test description is missing"
    end
    n_arguments = test_description_or_targets.size
    if n_arguments > 1
      message = "wrong number of arguments (#{n_arguments} for 1)"
      raise ArgumentError, message
    end
    method_name = "test: #{test_description}"
    define_method(method_name, &block)
    description(test_description, method_name)
    attribute(:test, true, {}, method_name)
    if block.respond_to?(:source_location)
      attribute(:source_location, block.source_location, {}, method_name)
    end
  else
    targets = test_description_or_targets
    attribute(:test, true, {}, *targets)
  end
end

Checkes whether a test that is mathched 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.

# File lib/test/unit/testcase.rb, line 352
def test_defined?(query)
  query_path = query[:path]
  query_line = query[:line]
  query_method_name = query[:method_name]

  available_locations = method_locations
  if query_path
    available_locations = available_locations.find_all do |location|
      location[:path].end_with?(query_path)
    end
  end
  if query_line
    available_location = available_locations.reverse.find do |location|
      query_line >= location[:line]
    end
    return false if available_location.nil?
    available_locations = [available_location]
  end
  if query_method_name
    available_location = available_locations.find do |location|
      query_method_name == location[:method_name]
    end
    return false if available_location.nil?
    available_locations = [available_location]
  end

  not available_locations.empty?
end

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

# File lib/test/unit/testcase.rb, line 219
def test_order
  @@test_orders[self] || AVAILABLE_ORDERS.first
end

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.

# File lib/test/unit/testcase.rb, line 232
def test_order=(order)
  @@test_orders[self] = order
end

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

# File lib/test/unit/testcase.rb, line 624
def ==(other)
  return false unless other.kind_of?(self.class)
  return false unless @method_name == other.method_name
  return false unless data_label == other.data_label
  self.class == other.class
end

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]

# File lib/test/unit/testcase.rb, line 673
def add_pass
  current_result.add_pass
end

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:

• test_my_class

• cleanup callback2

• my_cleanup2

• cleanup callback1

• my_cleanup1

• cleanup

# File lib/test/unit/testcase.rb, line 538
def cleanup
end

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

# File lib/test/unit/testcase.rb, line 595
def data_label
  @internal_data.test_data_label
end

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.

# File lib/test/unit/testcase.rb, line 614
def description
  self[:description] || name
end

Returns elapsed time for the test was ran.

# File lib/test/unit/testcase.rb, line 637
def elapsed_time
  @internal_data.elapsed_time
end

Returns whether the test is interrupted.

# File lib/test/unit/testcase.rb, line 642
def interrupted?
  @internal_data.interrupted?
end

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

# File lib/test/unit/testcase.rb, line 601
def name
  if @internal_data.have_test_data?
    "#{@method_name}[#{data_label}](#{self.class.name})"
  else
    "#{@method_name}(#{self.class.name})"
  end
end

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

# File lib/test/unit/testcase.rb, line 649
def passed?
  @internal_data.passed?
end

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]

# File lib/test/unit/testcase.rb, line 660
def problem_occurred
  @internal_data.problem_occurred
end

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

# File lib/test/unit/testcase.rb, line 423
def run(result)
  begin
    @_result = result
    @internal_data.test_started
    yield(STARTED, name)
    yield(STARTED_OBJECT, self)
    begin
      run_setup
      run_test
      run_cleanup
      add_pass
    rescue Exception
      @internal_data.interrupted
      raise unless handle_exception($!)
    ensure
      begin
        run_teardown
      rescue Exception
        raise unless handle_exception($!)
      end
    end
    @internal_data.test_finished
    result.add_run
    yield(FINISHED, name)
    yield(FINISHED_OBJECT, self)
  ensure
    # @_result = nil # For test-spec's after_all :<
  end
end

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:

• setup

• my_setup1

• setup callback1

• my_setup2

• setup callback2

• test_my_class

# File lib/test/unit/testcase.rb, line 493
def setup
end

Returns a Time at the test was started.

# File lib/test/unit/testcase.rb, line 632
def start_time
  @internal_data.start_time
end

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:

• test_my_class

• teardown callback2

• my_teardown2

• teardown callback1

• my_teardown1

• teardown

# File lib/test/unit/testcase.rb, line 581
def teardown
end

Overridden to return name.

# File lib/test/unit/testcase.rb, line 619
def to_s
  name
end