mirror of
https://github.com/boostorg/test.git
synced 2026-01-26 07:02:12 +00:00
82 lines
3.8 KiB
Plaintext
82 lines
3.8 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003-2014 Gennadiy Rozental
|
|
/
|
|
/ 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 do 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 ``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 methods by default flush the stream once check is performed.
|
|
If you want to perform several checks with the same output, specify parameter `flush_stream`
|
|
with value false. This parameter is supported on all comparison methods.
|
|
[warning Is there any example of `flush_stream` ??]
|
|
|
|
In some cases manual generation of expected output is either too time consuming or is impossible at all bacause
|
|
of sheer volume. What we need in cases like this is to be able to check once manually that the output is as expected
|
|
and to be able in a future check that it stays the same. To help manage this logic the class
|
|
`output_test_stream` allows matching output content versus specified pattern file and produce
|
|
pattern file based on successful test run.
|
|
|
|
|
|
Detailed specification of class `output_test_stream` is covered in reference section.
|
|
[warning Check if this is really the case]
|
|
|
|
[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`]
|
|
|
|
[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 serie 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 serie 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 example28..Pattern file matching with `output_test_stream`]
|
|
|
|
[tip Try to perform checks as frequently as possible, because it allows you to more closely identify possible source
|
|
of failure
|
|
]
|
|
|
|
[warning From what I understood, the matching is against the file and at most the number of characters that are currently
|
|
in the output stream. Is that correct?]
|
|
|
|
|
|
[endsect] [/ output stream testing]
|