ae01c8387c
- section about command line argument filtering for template test cases - many typos fixes - remove reference to bjam
80 lines
3.8 KiB
Plaintext
80 lines
3.8 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003 Boost.Test contributors
|
|
/
|
|
/ 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:output_stream_testing Output streams testing tool]
|
|
|
|
How would you perform correctness test for ``operator<< ( std::ostream &, ... )`` operations?
|
|
|
|
You can print into the standard output stream and manually check that it is matching your expectations.
|
|
Unfortunately, this is not really acceptable for the regression testing and doesn't serve a long term purpose of a
|
|
unit test.
|
|
|
|
You can use `std::stringstream` and compare resulting output buffer with the
|
|
expected pattern string, but you are required to perform several additional operations with every check you do. So it
|
|
becomes tedious very fast.
|
|
|
|
The class [classref boost::test_tools::output_test_stream] is designed to automate these tasks for you. This is a simple,
|
|
but powerful tool for testing standard `std::ostream` based output operation. The class `output_test_stream`
|
|
complies to `std::ostream` interface so it can be used in place of any
|
|
`std::ostream` parameter. It provides several test methods to validate output content,
|
|
including test for match to expected output content or test for expected output length. Flushing, synchronizing,
|
|
string comparison and error message generation is automated by the tool implementation.
|
|
|
|
All `output_test_stream` validation member functions by default flush the stream once the check is performed.
|
|
If you want to perform several checks with the same output, specify parameter `flush_stream`
|
|
with value `false` [footnote This parameter is supported on all comparison methods, see the class
|
|
[classref boost::test_tools::output_test_stream documentation.] ].
|
|
|
|
In some cases manual generation of expected output is either too time consuming or is impossible at all because
|
|
of sheer volume. A possible way to address that issue is to split the test in two steps:
|
|
|
|
# first by checking the expected output manually
|
|
# second to save this output to ensure that future checks produce the same output
|
|
|
|
The class `output_test_stream` allows both the matching of the output content versus a /pattern file/ and generation
|
|
of this pattern file. The command line parameter [link boost_test.utf_reference.rt_param_reference.save_pattern `save_pattern`]
|
|
may be used to either generate a new pattern file, or to check against an existing pattern.
|
|
|
|
[h3:usages Usage]
|
|
There are two ways to employ the class `output_test_stream`:
|
|
|
|
# explicit output checks and
|
|
# pattern file matching
|
|
|
|
[h4 Explicit output checks]
|
|
|
|
Use the instance of class `output_test_stream` as an output stream and check output content using tool's methods.
|
|
|
|
[bt_example example28..Explicit output checks with `output_test_stream`..run-fail]
|
|
|
|
[note Use of `false` to prevent output flushing in first two invocation of check functions. Unless
|
|
you want to perform several different checks for the same output you wouldn't need to use it though. Your
|
|
test will look like a sequence of output operators followed by one check.]
|
|
|
|
[tip Try to perform checks as
|
|
frequently as possible. It not only simplifies patterns you compare with, but also allows you to more closely
|
|
identify possible source of failure.]
|
|
|
|
[h4 Pattern file matching]
|
|
The ['pattern file] is a companion file containing the patterns that the stream should match. Your testing will look
|
|
like a series of output operators followed by match pattern checks repeated several times.
|
|
|
|
In the example below, the file `pattern_file` contains the patterns that should match.
|
|
[pre
|
|
i=2
|
|
File: test.cpp Line:XXX
|
|
]
|
|
|
|
[bt_example example29..Pattern file matching with `output_test_stream`..run-fail]
|
|
|
|
[tip Try to perform checks as frequently as possible, because it allows you to more closely identify possible source
|
|
of failure
|
|
]
|
|
|
|
|
|
[endsect] [/ output stream testing]
|