mirror of
https://github.com/boostorg/test.git
synced 2026-02-16 01:42:11 +00:00
110 lines
5.0 KiB
Plaintext
110 lines
5.0 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003 Boost.Test team
|
|
/
|
|
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
/]
|
|
|
|
[section:testing_tools Writing unit tests]
|
|
|
|
Once a test case has been declared, the body of this test should be written. A test case is a
|
|
sequence of operations in which *assertions* are inserted. Those assertions evaluate /statements/ that implement the expectation being validated,
|
|
and report failures and/or informations in a uniform manner, depending on the [link boost_test.utf_reference.rt_param_reference.log_level log level].
|
|
|
|
The __UTF__'s supplies a toolbox of assertions to ease the creation and maintenance of test cases and
|
|
provide a uniform error reporting mechanism. The toolbox supplied is in most part in a form of macro declarations.
|
|
An (almost) unique interface to all of them implemented by the macro __BOOST_TEST__.
|
|
|
|
[note All macros arguments are calculated once, so it's safe to pass complex expressions in their place.]
|
|
|
|
All tools automatically supply an error location: a file name and a line number, which can also be overriden.
|
|
|
|
[caution The testing tools are intended for unit test code rather than library or production code, where throwing exceptions, using `assert()`,
|
|
`boost::concept_check` or `BOOST_STATIC_ASSERT()` may be more suitable ways to detect and report errors.]
|
|
|
|
For a list of all supplied testing tools and usage examples, see the [link boost_test.testing_tools.summary summary]
|
|
or the [link boost_test.utf_reference.testing_tool_ref reference].
|
|
|
|
[h3 Assertion severity level]
|
|
There are three kind of assertions and all the testing tools are supplied in these three flavours/levels. These levels
|
|
have different meaning on the consistency of the test case:
|
|
|
|
* `REQUIRE` which implements a *requirements* : this is a strong condition for the operations following the assertion to be valid.
|
|
This type of assertions should be used when a pre-condition for running the test is not met or when the test-case cannot continue.
|
|
If such as assertion fails, the test case execution stops immediately, and the test-case is flagged as /failed/.
|
|
* `CHECK` for standard *checks*: this is the most commonly used assertion level. If the statement evaluates to `false`, the test case is
|
|
flagged as failed but its execution continues.
|
|
* `WARN` which stands for *warnings*: this is an assertion providing information. The test case execution continues and a warning message is logged.
|
|
The warning does not change the success status of a test case. This level of assertion can be used
|
|
to validate aspects less important then correctness: performance, portability, usability, etc.
|
|
|
|
For example:
|
|
|
|
* [link boost_test.utf_reference.testing_tool_ref.assertion_boost_level_throw `BOOST_REQUIRE_THROW`]
|
|
* `BOOST_CHECK_THROW`
|
|
* `BOOST_WARN_THROW`
|
|
|
|
These three levels of assertions are filtered by the framework and reported into the test log and output:
|
|
|
|
# If an assertion designated by the tool passes, confirmation message can be printed in log output
|
|
[footnote to manage what messages appear in the test log stream, set the proper [link boost_test.test_output.log_runtime_config log level]].
|
|
# If an assertion designated by the tool fails, the following will happen, depending on the assertion level
|
|
[footnote in some cases log message can be slightly different to reflect failed tool specifics, see [link boost_test.testing_tools.reports here]]:
|
|
|
|
[table:assertions_severity_levels Assertions severity levels
|
|
[
|
|
[Level]
|
|
[Test log content]
|
|
[Errors counter]
|
|
[Test execution]
|
|
]
|
|
|
|
[
|
|
[WARN]
|
|
[warning in `<test-case-name>`: condition `<assertion description>` is not satisfied]
|
|
[not affected]
|
|
[continues]
|
|
]
|
|
[
|
|
[CHECK]
|
|
[error in `<test-case-name>`: test `<assertion description>` failed]
|
|
[increased]
|
|
[continues]
|
|
]
|
|
[
|
|
[REQUIRE]
|
|
[fatal error in `<test-case-name>`: critical test `<assertion description>` failed]
|
|
[increased]
|
|
[aborts]
|
|
]
|
|
]
|
|
|
|
The granularity of the report depends on the current [link boost_test.utf_reference.rt_param_reference.log_level log level] and
|
|
[link boost_test.utf_reference.rt_param_reference.report_level report level].
|
|
|
|
[note in the above table, the ['test execution] is related to the current test case ['only]. Hence ['"aborts"] means
|
|
that the current test case is aborted, but other test cases in the test tree are still executed.]
|
|
|
|
[include boost_test_universal_macro.qbk]
|
|
[/[include assertions_severity_levels.qbk]]
|
|
[include boost_test_acceptable_statements.qbk]
|
|
[include boost_test_reported_information.qbk]
|
|
|
|
[section:extended_comparison Extended comparisons support]
|
|
[include testing_floating_points.qbk]
|
|
[include boost_test_string_comparison.qbk]
|
|
[include boost_test_collection_comparison.qbk]
|
|
[include boost_test_bitwise_comparison.qbk]
|
|
[endsect]
|
|
|
|
[include timeout.qbk]
|
|
[include expected_failures.qbk]
|
|
[include custom_predicates.qbk]
|
|
[include testing_output_streams.qbk]
|
|
|
|
[include boost_test_technical_details.qbk]
|
|
[include testing_tools_summary.qbk]
|
|
|
|
|
|
[endsect] [/ testing tools]
|