The Test Tools

Boost.Test > Components > The Test Tools > Output operations testing

# Output operations testing

## Introduction

How do you perform correctness test for operator<<( std::ostream&, ... ) operations. You may print into the standard output stream and manually check that everything is as you expected. But this is not really fit for regression testing. You may use stringstream and compare resulting output buffer with the expected pattern string. But you are required to perform several extra operations with every check you do, so you it becomes tedious really soon. The class output_test_stream automate this task for you. This is a simple, but powerful tool for testing standard std::ostream based output operation. The class output_test_stream comply to std::ostream interface so it can be used in place of any std::ostream parameter. It provides several methods to validate output content - you may compare with expected pattern string or perform only length check. Flushing, synchronizing, string comparison is automated for you by this tool

In some cases it may not be good enough. It becomes even more obvious when it's difficult to generate the expected pattern. What we need is to be able to check once manually that the output is as expected and to be able in a future check that is stays the same. To help manage this logic the class output_test_stream also allows to match/save output content versus/into specified file.

For detailed description of the facilities provided by the output_test_stream see it's specification.

## Usage

There are two ways to employ the output_test_stream tool: explicit output checks and pattern file matching.

### Explicit output checks

    using boost::test_tools::output_test_stream;

    int test_main( int, char* [] ) {
        output_test_stream output;
        int i=2;
        output << "i=" << i;
        BOOST_CHECK( !output.is_empty( false ) );
        BOOST_CHECK( output.check_length( 3, false ) );
        BOOST_CHECK( output.is_equal( "i=2" ) );

        return 0;
    }

As simple as that: just use instance of output_test_stream as an output stream and then check output content using supplied tool's methods. Note use of false to prevent output flashing 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 testing will look like a serious of output operators followed by check one. And so on again. Try to perform checks as frequently as possible. It's not only simplify patters you compare with, but also allows you to more closely identify possible source of failure.

### Pattern file matching

    using boost::test_tools::output_test_stream;

    int test_main( int argc, char* [] ) {
        output_test_stream output( "pattern_file", argc == 1);
        int i=2;
        output << "i=" << i;
        BOOST_CHECK( output.match_pattern() );

        output << "File: " << __FILE__ << " Line: " << __LINE__;
        BOOST_CHECK( output.match_pattern() );

        ...

        return 0;
    }

Even more simpler: no need to generate expected patterns. Though you need to keep the pattern file all the time somewhere around. Your testing will look like a serious of output operators followed by match pattern checks. And so on again. Try to perform checks as frequently as possible,cause it allows you to more closely identify possible source of failure.

## Example and test programs

output_test_stream_test
result_report_test
test_tools_test
errors_handling_test