12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879 |
- [/
- / 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]
|