ceph/src/boost/libs/test/doc/testing_tools/testing_output_streams.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:output_stream_testing Output streams testing tool]
   9
  10 How would you perform correctness test for ``operator<< ( std::ostream &, ... )`` operations?
  11
  12 You can print into the standard output stream and manually check that it is matching your expectations.
  13 Unfortunately, this is not really acceptable for the regression testing and doesn't serve a long term purpose of a
  14 unit test.
  15
  16 You can use `std::stringstream` and compare resulting output buffer with the
  17 expected pattern string, but you are required to perform several additional operations with every check you do. So it
  18 becomes tedious very fast.
  19
  20 The class [classref boost::test_tools::output_test_stream] is designed to automate these tasks for you. This is a simple,
  21 but powerful tool for testing standard `std::ostream` based output operation. The class `output_test_stream`
  22 complies to `std::ostream` interface so it can be used in place of any
  23 `std::ostream` parameter. It provides several test methods to validate output content,
  24 including test for match to expected output content or test for expected output length. Flushing, synchronizing,
  25 string comparison and error message generation is automated by the tool implementation.
  26
  27 All `output_test_stream` validation member functions by default flush the stream once the check is performed.
  28 If you want to perform several checks with the same output, specify parameter `flush_stream`
  29 with value `false` [footnote This parameter is supported on all comparison methods, see the class
  30 [classref boost::test_tools::output_test_stream documentation.] ].
  31
  32 In some cases manual generation of expected output is either too time consuming or is impossible at all because
  33 of sheer volume. A possible way to address that issue is to split the test in two steps:
  34
  35 # first by checking the expected output manually
  36 # second to save this output to ensure that future checks produce the same output
  37
  38 The class `output_test_stream` allows both the matching of the output content versus a /pattern file/ and generation
  39 of this pattern file. The command line parameter [link boost_test.utf_reference.rt_param_reference.save_pattern `save_pattern`]
  40 may be used to either generate a new pattern file, or to check against an existing pattern.
  41
  42 [h3:usages Usage]
  43 There are two ways to employ the class `output_test_stream`:
  44
  45 # explicit output checks and
  46 # pattern file matching
  47
  48 [h4 Explicit output checks]
  49
  50 Use the instance of class `output_test_stream` as an output stream and check output content using tool's methods.
  51
  52 [bt_example example28..Explicit output checks with `output_test_stream`..run-fail]
  53
  54 [note Use of `false` to prevent output flushing in first two invocation of check functions. Unless
  55 you want to perform several different checks for the same output you wouldn't need to use it though. Your
  56 test will look like a sequence of output operators followed by one check.]
  57
  58 [tip Try to perform checks as
  59 frequently as possible. It not only simplifies patterns you compare with, but also allows you to more closely
  60 identify possible source of failure.]
  61
  62 [h4 Pattern file matching]
  63 The ['pattern file] is a companion file containing the patterns that the stream should match. Your testing will look
  64 like a series of output operators followed by match pattern checks repeated several times.
  65
  66 In the example below, the file `pattern_file` contains the patterns that should match.
  67 [pre
  68 i=2
  69 File: test.cpp Line:XXX
  70 ]
  71
  72 [bt_example example29..Pattern file matching with `output_test_stream`..run-fail]
  73
  74 [tip Try to perform checks as frequently as possible, because it allows you to more closely identify possible source
  75     of failure
  76 ]
  77
  78
  79 [endsect] [/ output stream testing]