bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / test / doc / testing_tools / testing_output_streams.qbk

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