class Test::Unit::TestCase

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:

Attributes

method_name[R]

Public Class Methods

description(value, target=nil) click to toggle source

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
new(test_method_name) click to toggle source

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
shutdown() click to toggle source

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
startup() click to toggle source

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
sub_test_case(name, &block) click to toggle source

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
suite() click to toggle source

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
test(*test_description_or_targets, &block) click to toggle source

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
test_defined?(query) click to toggle source

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
test_order() click to toggle source

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
test_order=(order) click to toggle source

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

Private Class Methods

method_locations() click to toggle source

@private

# File lib/test/unit/testcase.rb, line 385
def method_locations
  @@method_locations[self] ||= []
end

Public Instance Methods

==(other) click to toggle source

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
add_pass() click to toggle source

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
cleanup() click to toggle source

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
data_label() click to toggle source

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
default_test() click to toggle source
# File lib/test/unit/testcase.rb, line 584
def default_test
  flunk("No tests were specified")
end
description() click to toggle source

Returns a description for the test. A description will be associated by ::test or ::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
elapsed_time() click to toggle source

Returns elapsed time for the test was ran.

# File lib/test/unit/testcase.rb, line 637
def elapsed_time
  @internal_data.elapsed_time
end
interrupted?() click to toggle source

Returns whether the test is interrupted.

# File lib/test/unit/testcase.rb, line 642
def interrupted?
  @internal_data.interrupted?
end
name() click to toggle source

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
passed?() click to toggle source

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
problem_occurred() click to toggle source

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
run(result) { |STARTED, name| ... } click to toggle source

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
setup() click to toggle source

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
size() click to toggle source
# File lib/test/unit/testcase.rb, line 588
def size
  1
end
start_time() click to toggle source

Returns a Time at the test was started.

# File lib/test/unit/testcase.rb, line 632
def start_time
  @internal_data.start_time
end
teardown() click to toggle source

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
to_s() click to toggle source

Overridden to return name.

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

Private Instance Methods

add_assertion() click to toggle source
# File lib/test/unit/testcase.rb, line 707
def add_assertion
  current_result.add_assertion
end
current_result() click to toggle source
# File lib/test/unit/testcase.rb, line 678
def current_result
  @_result
end
handle_exception(exception) click to toggle source
# File lib/test/unit/testcase.rb, line 695
def handle_exception(exception)
  self.class.exception_handlers.each do |handler|
    if handler.respond_to?(:call)
      handled = handler.call(self, exception)
    else
      handled = send(handler, exception)
    end
    return true if handled
  end
  false
end
run_test() click to toggle source
# File lib/test/unit/testcase.rb, line 682
def run_test
  redefined_info = self[:redefined]
  if redefined_info
    notify("#{self.class}\##{@method_name} was redefined",
           :backtrace => redefined_info[:backtrace])
  end
  if @internal_data.have_test_data?
    __send__(@method_name, @internal_data.test_data)
  else
    __send__(@method_name)
  end
end