Class: Test::Unit::TestCase
- Inherits:
-
Object
- Object
- Test::Unit::TestCase
- Includes:
- Assertions, Attribute, Data, ErrorHandler, ExceptionHandler, FailureHandler, Fixture, Priority, TestCaseNotificationSupport, TestCaseOmissionSupport, TestCasePendingSupport, Util::BacktraceFilter, Util::Output
- Defined in:
- lib/test/unit/testcase.rb
Overview
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:
-
startup
-
setup
-
test_my_method1
-
cleanup
-
teardown
-
setup
-
test_my_method2
-
cleanup
-
teardown
-
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
Defined Under Namespace
Classes: InternalData
Constant Summary collapse
- STARTED =
:nodoc:
name + "::STARTED"
- FINISHED =
:nodoc:
name + "::FINISHED"
- STARTED_OBJECT =
:nodoc:
name + "::STARTED::OBJECT"
- FINISHED_OBJECT =
:nodoc:
name + "::FINISHED::OBJECT"
- DESCENDANTS =
:nodoc:
[]
- AVAILABLE_ORDERS =
:nodoc:
[:alphabetic, :random, :defined]
- @@added_method_names =
{}
- @@test_orders =
{}
Constants included from Util::BacktraceFilter
Util::BacktraceFilter::POWERASSERT_PREFIX, Util::BacktraceFilter::TESTUNIT_FILE_SEPARATORS, Util::BacktraceFilter::TESTUNIT_PREFIX, Util::BacktraceFilter::TESTUNIT_RB_FILE
Constants included from Assertions
Constants included from ErrorHandler
ErrorHandler::NOT_PASS_THROUGH_EXCEPTIONS, ErrorHandler::NOT_PASS_THROUGH_EXCEPTION_NAMES, ErrorHandler::PASS_THROUGH_EXCEPTIONS, ErrorHandler::PASS_THROUGH_EXCEPTION_NAMES
Instance Attribute Summary collapse
-
#method_name ⇒ Object
readonly
Returns the value of attribute method_name.
Class Method Summary collapse
-
.added_method_names ⇒ Object
:nodoc:.
-
.description(value, target = nil) ⇒ Object
Describes a test.
- .find_locations(query) ⇒ Object
-
.include(*modules, &block) ⇒ Object
:nodoc:.
-
.inherited(sub_class) ⇒ Object
:nodoc:.
-
.method_added(name) ⇒ Object
:nodoc:.
-
.ractor(options = {}) ⇒ void
Declares that the following test uses Ractor.
-
.shutdown ⇒ Object
Called after every test case runs.
-
.startup ⇒ Object
Called before every test case runs.
-
.sub_test_case(name) { ... } ⇒ Test::Unit::TestCase
Defines a sub test case.
-
.suite ⇒ Object
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) ⇒ Object
Defines a test in declarative syntax or marks following method as a test method.
-
.test_defined?(query) ⇒ Boolean
Checks whether a test that is matched the query is defined.
-
.test_order ⇒ Object
Returns the current test order.
-
.test_order=(order) ⇒ Object
Sets the current test order.
Instance Method Summary collapse
-
#==(other) ⇒ Object
It’s handy to be able to compare TestCase instances.
-
#add_pass ⇒ void
Notify that the test is passed.
-
#assign_test_data(label, data) ⇒ Object
Assigns test data to the test.
-
#cleanup ⇒ Object
Called after every test method runs but the test method isn’t marked as ‘passed’.
-
#data ⇒ Object
Returns test data for the test.
-
#data_label ⇒ Object
Returns a label of test data for the test.
- #default_test ⇒ Object
-
#description ⇒ Object
Returns a description for the test.
-
#elapsed_time ⇒ Object
Returns elapsed time for the test was ran.
-
#initialize(test_method_name) ⇒ TestCase
constructor
Creates a new instance of the fixture for running the test represented by test_method_name.
-
#interrupted? ⇒ Boolean
Returns whether the test is interrupted.
-
#local_name ⇒ Object
Returns a human-readable name for the specific test that this instance of TestCase represents.
-
#name ⇒ Object
Returns a human-readable name for the specific test that this instance of TestCase represents.
-
#passed? ⇒ Boolean
Returns whether this individual test passed or not.
-
#problem_occurred ⇒ void
Notify that a problem is occurred in the test.
-
#run(result) ⇒ Object
Runs the individual test method represented by this instance of the fixture, collecting statistics, failures and errors in result.
-
#setup ⇒ Object
Called before every test method runs.
- #size ⇒ Object
-
#start_time ⇒ Object
Returns a Time at the test was started.
-
#teardown ⇒ Object
Called after every test method runs.
-
#to_s ⇒ Object
Overridden to return #name.
-
#valid? ⇒ Boolean
Returns the test is valid test.
Methods included from Util::Output
Methods included from Util::BacktraceFilter
Methods included from Assertions
#assert, #assert_alias_method, #assert_all, #assert_block, #assert_boolean, #assert_compare, #assert_const_defined, #assert_empty, #assert_equal, #assert_fail_assertion, #assert_false, #assert_in_delta, #assert_in_epsilon, #assert_include, #assert_instance_of, #assert_kind_of, #assert_match, #assert_nil, #assert_no_match, #assert_not_const_defined, #assert_not_empty, #assert_not_equal, #assert_not_in_delta, #assert_not_in_epsilon, #assert_not_include, #assert_not_instance_of, #assert_not_kind_of, #assert_not_match, #assert_not_nil, #assert_not_operator, #assert_not_predicate, #assert_not_respond_to, #assert_not_same, #assert_not_send, #assert_nothing_leaked_memory, #assert_nothing_raised, #assert_nothing_thrown, #assert_operator, #assert_path_exist, #assert_path_not_exist, #assert_predicate, #assert_raise, #assert_raise_kind_of, #assert_raise_message, #assert_raise_with_message, #assert_respond_to, #assert_same, #assert_send, #assert_throw, #assert_true, #build_message, #flunk, #refute, use_pp=
Methods included from Data
Methods included from Priority
available_values, default, default=, disable, enable, enabled?, included, #priority_setup, #priority_teardown
Methods included from TestCaseNotificationSupport
Methods included from TestCaseOmissionSupport
included, #omit, #omit_if, #omit_unless
Methods included from TestCasePendingSupport
Methods included from FailureHandler
Methods included from ErrorHandler
Methods included from ExceptionHandler
Methods included from Fixture
Methods included from Attribute
Constructor Details
#initialize(test_method_name) ⇒ TestCase
Creates a new instance of the fixture for running the test represented by test_method_name.
528 529 530 531 |
# File 'lib/test/unit/testcase.rb', line 528 def initialize(test_method_name) @method_name = test_method_name @internal_data = InternalData.new end |
Instance Attribute Details
#method_name ⇒ Object (readonly)
Returns the value of attribute method_name.
524 525 526 |
# File 'lib/test/unit/testcase.rb', line 524 def method_name @method_name end |
Class Method Details
.added_method_names ⇒ Object
:nodoc:
173 174 175 |
# File 'lib/test/unit/testcase.rb', line 173 def added_method_names # :nodoc: (@@added_method_names[self] ||= {}).keys end |
.description(value, target = nil) ⇒ Object
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
349 350 351 352 |
# File 'lib/test/unit/testcase.rb', line 349 def description(value, target=nil) targets = [target].compact attribute(:description, value, {}, *targets) end |
.find_locations(query) ⇒ Object
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 |
# File 'lib/test/unit/testcase.rb', line 441 def find_locations(query) query_path = query[:path] query_line = query[:line] query_method_name = query[:method_name] available_locations = target_method_locations(query_path) if query_line available_locations = available_locations.sort_by do |location| -location[:line] end available_location = available_locations.find do |location| query_line >= location[:line] end return [] if available_location.nil? return [] if available_location[:test_case] != self available_locations = [available_location] end if query_method_name available_location = available_locations.find do |location| location[:test_case] == self and query_method_name == location[:method_name] end return [] if available_location.nil? available_locations = [available_location] end available_locations end |
.include(*modules, &block) ⇒ Object
:nodoc:
133 134 135 136 137 138 139 140 141 |
# File 'lib/test/unit/testcase.rb', line 133 def include(*modules, &block) # :nodoc: result = super modules.each do |mod| mod.public_instance_methods(false).each do |method_name| AutoRunnerLoader.check(self, method_name.to_s) end end result end |
.inherited(sub_class) ⇒ Object
:nodoc:
128 129 130 131 |
# File 'lib/test/unit/testcase.rb', line 128 def inherited(sub_class) # :nodoc: DESCENDANTS << sub_class super end |
.method_added(name) ⇒ Object
:nodoc:
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 |
# File 'lib/test/unit/testcase.rb', line 144 def method_added(name) # :nodoc: super added_method_names = (@@added_method_names[self] ||= {}) stringified_name = name.to_s if added_method_names.key?(stringified_name) attribute(:redefined, {:backtrace => caller}, {}, stringified_name) end source_location = find_attribute(stringified_name, :source_location) if source_location path, line = source_location elsif respond_to?(:caller_locations, true) location = caller_locations(1, 1)[0] path = location.absolute_path || location.path line = location.lineno else # TODO: Remove me when Ruby 1.9 support is dropped path, line, = caller[0].split(/:(\d+)/, 2) line = line.to_i if line end location = { :method_name => stringified_name, :path => File.(path), :line => line, } add_method_location(location) added_method_names[stringified_name] = true AutoRunnerLoader.check(self, stringified_name) end |
.ractor(options = {}) ⇒ void
This method returns an undefined value.
Declares that the following test uses Ractor.
Tests that use Ractor are executed at the end. Because multi Ractor mode is enabled in the current process and it’s not disabled even when only one Ractor is running after running a test that uses Ractor on Ruby 3.0. It will be solved in the future.
This is implemented by setting the ‘:ractor` attribute of the test to `true`.
380 381 382 |
# File 'lib/test/unit/testcase.rb', line 380 def ractor(={}) attribute(:ractor, true, ) end |
.shutdown ⇒ Object
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.
259 260 |
# File 'lib/test/unit/testcase.rb', line 259 def shutdown end |
.startup ⇒ Object
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.
221 222 |
# File 'lib/test/unit/testcase.rb', line 221 def startup end |
.sub_test_case(name) { ... } ⇒ Test::Unit::TestCase
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”.
421 422 423 424 425 |
# File 'lib/test/unit/testcase.rb', line 421 def sub_test_case(name, &block) sub_test_case = sub_test_case_class(name) sub_test_case.class_eval(&block) sub_test_case end |
.suite ⇒ Object
Rolls up all of the test* methods in the fixture into one suite, creating a new instance of the fixture for each method.
180 181 182 183 |
# File 'lib/test/unit/testcase.rb', line 180 def suite suite_creator = TestSuiteCreator.new(self) suite_creator.create end |
.test(*test_description_or_targets, &block) ⇒ Object
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
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 |
# File 'lib/test/unit/testcase.rb', line 312 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 = "wrong number of arguments (#{n_arguments} for 1)" raise ArgumentError, end method_name = "test: #{test_description}" 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 define_method(method_name, &block) else targets = test_description_or_targets attribute(:test, true, {}, *targets) targets.each do |target| AutoRunnerLoader.check(self, target) end end end |
.test_defined?(query) ⇒ Boolean
Checks whether a test that is matched the query is defined.
436 437 438 439 |
# File 'lib/test/unit/testcase.rb', line 436 def test_defined?(query) locations = find_locations(query) not locations.empty? end |
.test_order ⇒ Object
Returns the current test order. This returns ‘:alphabetic` by default.
266 267 268 269 270 271 272 |
# File 'lib/test/unit/testcase.rb', line 266 def test_order ancestors.each do |ancestor| order = @@test_orders[ancestor] return order if order end AVAILABLE_ORDERS.first end |
.test_order=(order) ⇒ Object
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.
286 287 288 |
# File 'lib/test/unit/testcase.rb', line 286 def test_order=(order) @@test_orders[self] = order end |
Instance Method Details
#==(other) ⇒ Object
It’s handy to be able to compare TestCase instances.
794 795 796 797 798 799 |
# File 'lib/test/unit/testcase.rb', line 794 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 ⇒ void
This method returns an undefined value.
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.
843 844 845 |
# File 'lib/test/unit/testcase.rb', line 843 def add_pass current_result.add_pass end |
#assign_test_data(label, data) ⇒ Object
Assigns test data to the test. It is used in internal.
534 535 536 |
# File 'lib/test/unit/testcase.rb', line 534 def assign_test_data(label, data) # :nodoc: @internal_data.assign_test_data(label, data) end |
#cleanup ⇒ Object
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
691 692 |
# File 'lib/test/unit/testcase.rb', line 691 def cleanup end |
#data ⇒ Object
Returns test data for the test. If the test isn’t associated with any test data, it returns ‘nil`.
756 757 758 |
# File 'lib/test/unit/testcase.rb', line 756 def data @internal_data.test_data end |
#data_label ⇒ Object
Returns a label of test data for the test. If the test isn’t associated with any test data, it returns ‘nil`.
750 751 752 |
# File 'lib/test/unit/testcase.rb', line 750 def data_label @internal_data.test_data_label end |
#default_test ⇒ Object
739 740 741 |
# File 'lib/test/unit/testcase.rb', line 739 def default_test flunk("No tests were specified") end |
#description ⇒ Object
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.
784 785 786 |
# File 'lib/test/unit/testcase.rb', line 784 def description self[:description] || name end |
#elapsed_time ⇒ Object
Returns elapsed time for the test was ran.
807 808 809 |
# File 'lib/test/unit/testcase.rb', line 807 def elapsed_time @internal_data.elapsed_time end |
#interrupted? ⇒ Boolean
Returns whether the test is interrupted.
812 813 814 |
# File 'lib/test/unit/testcase.rb', line 812 def interrupted? @internal_data.interrupted? end |
#local_name ⇒ Object
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.
771 772 773 774 775 776 777 |
# File 'lib/test/unit/testcase.rb', line 771 def local_name if @internal_data.have_test_data? "#{@method_name}[#{data_label}]" else @method_name.to_s end end |
#name ⇒ Object
Returns a human-readable name for the specific test that this instance of TestCase represents.
762 763 764 |
# File 'lib/test/unit/testcase.rb', line 762 def name "#{local_name}(#{self.class.name})" end |
#passed? ⇒ Boolean
Returns whether this individual test passed or not. Primarily for use in teardown so that artifacts can be left behind if the test fails.
819 820 821 |
# File 'lib/test/unit/testcase.rb', line 819 def passed? @internal_data.passed? end |
#problem_occurred ⇒ void
This method returns an undefined value.
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.
830 831 832 |
# File 'lib/test/unit/testcase.rb', line 830 def problem_occurred @internal_data.problem_occurred end |
#run(result) ⇒ Object
Runs the individual test method represented by this instance of the fixture, collecting statistics, failures and errors in result.
555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 |
# File 'lib/test/unit/testcase.rb', line 555 def run(result) begin @_result = result @internal_data.test_started yield(STARTED, name) yield(STARTED_OBJECT, self) processed_exception_in_setup = false begin catch do |tag| run_setup do begin run_test run_cleanup add_pass rescue Exception @internal_data.interrupted unless handle_exception($!) processed_exception_in_setup = true raise end throw(tag) end end end rescue Exception if processed_exception_in_setup raise else @internal_data.interrupted raise unless handle_exception($!) end 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 ⇒ Object
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
644 645 |
# File 'lib/test/unit/testcase.rb', line 644 def setup end |
#size ⇒ Object
743 744 745 |
# File 'lib/test/unit/testcase.rb', line 743 def size 1 end |
#start_time ⇒ Object
Returns a Time at the test was started.
802 803 804 |
# File 'lib/test/unit/testcase.rb', line 802 def start_time @internal_data.start_time end |
#teardown ⇒ Object
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
736 737 |
# File 'lib/test/unit/testcase.rb', line 736 def teardown end |
#to_s ⇒ Object
Overridden to return #name.
789 790 791 |
# File 'lib/test/unit/testcase.rb', line 789 def to_s name end |
#valid? ⇒ Boolean
Returns the test is valid test. It is used in internal.
539 540 541 542 543 544 545 546 547 548 549 550 |
# File 'lib/test/unit/testcase.rb', line 539 def valid? # :nodoc: return false unless respond_to?(@method_name) test_method = method(@method_name) unless @internal_data.have_test_data? return false unless test_method.arity <= 0 end owner = Util::MethodOwnerFinder.find(self, @method_name) if owner.class != Module and self.class != owner return false end true end |