|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r75007 - in trunk/libs/test/doc/src: . examples xsl
From: gennadiy.rozental_at_[hidden]
Date: 2011-10-17 07:13:58
Author: rogeeff
Date: 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
New Revision: 75007
URL: http://svn.boost.org/trac/boost/changeset/75007
Log:
latest state of sources
Fixes #4982
Added:
trunk/libs/test/doc/src/examples/example.vcxproj (contents, props changed)
trunk/libs/test/doc/src/utf.examples.xml (contents, props changed)
trunk/libs/test/doc/src/utf.user-guide.fixture.xml
- copied unchanged from r73722, /trunk/libs/test/doc/src/utf.users-guide.fixture.xml
trunk/libs/test/doc/src/utf.user-guide.glossary.xml (contents, props changed)
trunk/libs/test/doc/src/utf.user-guide.initialization.xml (contents, props changed)
trunk/libs/test/doc/src/utf.user-guide.test-organization.xml
- copied, changed from r73722, /trunk/libs/test/doc/src/utf.users-guide.test-organization.xml
trunk/libs/test/doc/src/utf.user-guide.test-output.xml
- copied, changed from r73722, /trunk/libs/test/doc/src/utf.users-guide.test-output.xml
trunk/libs/test/doc/src/utf.user-guide.test-runners.xml (contents, props changed)
trunk/libs/test/doc/src/utf.user-guide.testing-tools.xml (contents, props changed)
trunk/libs/test/doc/src/utf.user-guide.usage-variants.xml (contents, props changed)
trunk/libs/test/doc/src/utf.user-guide.xml
- copied, changed from r73722, /trunk/libs/test/doc/src/utf.users-guide.xml
Removed:
trunk/libs/test/doc/src/UTF.log.xsd
trunk/libs/test/doc/src/UTF.report.xsd
trunk/libs/test/doc/src/examples/example.vcproj
trunk/libs/test/doc/src/utf.users-guide.fixture.xml
trunk/libs/test/doc/src/utf.users-guide.test-organization.xml
trunk/libs/test/doc/src/utf.users-guide.test-output.xml
trunk/libs/test/doc/src/utf.users-guide.xml
Text files modified:
trunk/libs/test/doc/src/btl-toc.xml | 161 ++++----
trunk/libs/test/doc/src/btl.xml | 5
trunk/libs/test/doc/src/examples/example.sln | 6
trunk/libs/test/doc/src/examples/example25.cpp | 2
trunk/libs/test/doc/src/examples/example38.cpp | 4
trunk/libs/test/doc/src/examples/example38.output | 2
trunk/libs/test/doc/src/execution-monitor.xml | 6
trunk/libs/test/doc/src/faq.xml | 4
trunk/libs/test/doc/src/minimal-testing.xml | 4
trunk/libs/test/doc/src/program-execution-monitor.xml | 2
trunk/libs/test/doc/src/utf.tutorials.xml | 4
trunk/libs/test/doc/src/utf.user-guide.runtime-config.xml | 126 ++++++
trunk/libs/test/doc/src/utf.user-guide.test-organization.xml | 374 ++++++++++---------
trunk/libs/test/doc/src/utf.user-guide.test-output.xml | 8
trunk/libs/test/doc/src/utf.user-guide.xml | 714 ++-------------------------------------
trunk/libs/test/doc/src/utf.xml | 24
trunk/libs/test/doc/src/xsl/html.xsl | 2
17 files changed, 475 insertions(+), 973 deletions(-)
Deleted: trunk/libs/test/doc/src/UTF.log.xsd
==============================================================================
--- trunk/libs/test/doc/src/UTF.log.xsd 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,146 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
- <xs:attributeGroup name="TestUnitAttributes">
- <xs:attribute name="name" type="xs:string" use="required">
- <xs:annotation>
- <xs:documentation>name of the test unit</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="skipped" type="xs:string" use="optional" fixed="yes">
- <xs:annotation>
- <xs:documentation>Specified with value "yes" only if test unit was skipped during execution</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- </xs:attributeGroup>
- <xs:complexType name="LogEntry">
- <xs:simpleContent>
- <xs:extension base="xs:string">
- <xs:attribute name="line" type="xs:integer" use="required">
- <xs:annotation>
- <xs:documentation>Line number corresponding to the log entry</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="file" type="xs:anyURI" use="required">
- <xs:annotation>
- <xs:documentation>file name corresponding to the log entry</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- </xs:extension>
- </xs:simpleContent>
- </xs:complexType>
- <xs:complexType name="ExceptionEntry" mixed="true">
- <xs:annotation>
- <xs:documentation>Exception description</xs:documentation>
- </xs:annotation>
- <xs:sequence>
- <xs:element name="LastCheckpoint" type="LogEntry">
- <xs:annotation>
- <xs:documentation>Location of last checkpoint before exception occured</xs:documentation>
- </xs:annotation>
- </xs:element>
- </xs:sequence>
- <xs:attribute name="name" type="xs:string" use="optional">
- <xs:annotation>
- <xs:documentation>obsolete?</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- </xs:complexType>
- <xs:element name="TestCase">
- <xs:complexType>
- <xs:sequence>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:annotation>
- <xs:documentation>different log entries</xs:documentation>
- </xs:annotation>
- <xs:element name="Info" type="LogEntry">
- <xs:annotation>
- <xs:documentation>Log entry corresponding to the successfully passed assertion</xs:documentation>
- </xs:annotation>
- </xs:element>
- <xs:element name="Message" type="LogEntry">
- <xs:annotation>
- <xs:documentation>Log entry corresponding to the message generated during test execution</xs:documentation>
- </xs:annotation>
- </xs:element>
- <xs:element name="Warning" type="LogEntry">
- <xs:annotation>
- <xs:documentation>Log entry corresponding to the warning generated during test execution</xs:documentation>
- </xs:annotation>
- </xs:element>
- <xs:element name="Error" type="LogEntry">
- <xs:annotation>
- <xs:documentation>Log entry corresponding to the non-fatal error occured during test execution</xs:documentation>
- </xs:annotation>
- </xs:element>
- <xs:element name="FatalError" type="LogEntry">
- <xs:annotation>
- <xs:documentation>Log entry corresponding to the fatal error occured during test execution</xs:documentation>
- </xs:annotation>
- </xs:element>
- <xs:element name="Exception" type="ExceptionEntry">
- <xs:annotation>
- <xs:documentation>Log entry corresponding to an exception occured during test execution</xs:documentation>
- </xs:annotation>
- </xs:element>
- </xs:choice>
- <xs:element name="TestingTime" type="xs:float">
- <xs:annotation>
- <xs:documentation>approximate time spent on test unit execution</xs:documentation>
- </xs:annotation>
- </xs:element>
- </xs:sequence>
- <xs:attributeGroup ref="TestUnitAttributes"/>
- </xs:complexType>
- </xs:element>
- <xs:element name="TestSuite">
- <xs:complexType>
- <xs:sequence>
- <xs:annotation>
- <xs:documentation>List of test units composing test suite</xs:documentation>
- </xs:annotation>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:element ref="TestCase"/>
- <xs:element ref="TestSuite"/>
- </xs:choice>
- </xs:sequence>
- <xs:attributeGroup ref="TestUnitAttributes"/>
- </xs:complexType>
- </xs:element>
- <xs:element name="TestLog">
- <xs:annotation>
- <xs:documentation>Holds whole unit test log content</xs:documentation>
- </xs:annotation>
- <xs:complexType>
- <xs:sequence>
- <xs:element name="BuildInfo" minOccurs="0">
- <xs:annotation>
- <xs:documentation>Optional build information for the unit test. </xs:documentation>
- </xs:annotation>
- <xs:complexType>
- <xs:attribute name="platform" type="xs:string">
- <xs:annotation>
- <xs:documentation>unique identifier for the platform unit test was compiled on</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="compiler" type="xs:string">
- <xs:annotation>
- <xs:documentation>unique identifier for the compiler unit test was compiled with</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="stl" type="xs:string">
- <xs:annotation>
- <xs:documentation>unique identifier for the STL implementation used during unit test compilation</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="boost" type="xs:string">
- <xs:annotation>
- <xs:documentation>version of the boost used</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- </xs:complexType>
- </xs:element>
- <xs:element ref="TestSuite"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-</xs:schema>
Deleted: trunk/libs/test/doc/src/UTF.report.xsd
==============================================================================
--- trunk/libs/test/doc/src/UTF.report.xsd 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,82 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- edited with XMLSpy v2007 (http://www.altova.com) by rogeeff (boost) -->
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
- <xs:simpleType name="StatusType">
- <xs:restriction base="xs:string">
- <xs:enumeration value="passed"/>
- <xs:enumeration value="skipped"/>
- <xs:enumeration value="aborted"/>
- <xs:enumeration value="failed"/>
- </xs:restriction>
- </xs:simpleType>
- <xs:attributeGroup name="TestUnitResult">
- <xs:attribute name="name" type="xs:string">
- <xs:annotation>
- <xs:documentation>name of the test unit</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="result" type="StatusType">
- <xs:annotation>
- <xs:documentation>result status for the test unit: passed, failed, skipped or aborted</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="assertions_passed" type="xs:string">
- <xs:annotation>
- <xs:documentation>number of assertions that passed during execution of the test unit</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="assertions_failed" type="xs:string">
- <xs:annotation>
- <xs:documentation>number of assertion that failed during execution of the test unit</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="expected_failures" type="xs:string">
- <xs:annotation>
- <xs:documentation>number of assertions that expected to fail in the test unit</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- </xs:attributeGroup>
- <xs:element name="TestCase">
- <xs:complexType>
- <xs:attributeGroup ref="TestUnitResult"/>
- </xs:complexType>
- </xs:element>
- <xs:element name="TestSuite">
- <xs:complexType>
- <xs:sequence>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:element ref="TestSuite"/>
- <xs:element ref="TestCase"/>
- </xs:choice>
- </xs:sequence>
- <xs:attributeGroup ref="TestUnitResult"/>
- <xs:attribute name="test_cases_passed" type="xs:integer">
- <xs:annotation>
- <xs:documentation>number of test cases that passed in the test suite</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="test_cases_failed" type="xs:integer">
- <xs:annotation>
- <xs:documentation>number of test cases that failed in the test suite</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="test_cases_skipped" type="xs:integer">
- <xs:annotation>
- <xs:documentation>number of test cases that were skipped in the test suite</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- <xs:attribute name="test_cases_aborted" type="xs:integer">
- <xs:annotation>
- <xs:documentation>number of test cases in the test suite that were aborted during execution by an exception or a fatal error</xs:documentation>
- </xs:annotation>
- </xs:attribute>
- </xs:complexType>
- </xs:element>
- <xs:element name="TestResult">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="TestSuite"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-</xs:schema>
Modified: trunk/libs/test/doc/src/btl-toc.xml
==============================================================================
--- trunk/libs/test/doc/src/btl-toc.xml (original)
+++ trunk/libs/test/doc/src/btl-toc.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -20,38 +20,6 @@
</tocentry>
</tocentry>
- <tocentry linkend="execution-monitor">
- <?dbhtml filename="execution-monitor.html"?>
-
- <tocentry linkend="execution-monitor.compilation">
- <?dbhtml filename="execution-monitor/compilation.html"?>
- </tocentry>
-
- <tocentry linkend="execution-monitor.user-guide">
- <?dbhtml filename="execution-monitor/user-guide.html"?>
- </tocentry>
-
- <tocentry linkend="execution-monitor.reference">
- <?dbhtml filename="execution-monitor/reference.html"?>
- </tocentry>
- </tocentry>
-
- <tocentry linkend="pem">
- <?dbhtml filename="prg-exec-monitor.html"?>
-
- <tocentry linkend="pem.impl">
- <?dbhtml filename="prg-exec-monitor/impl.html"?>
- </tocentry>
-
- <tocentry linkend="pem.compilation">
- <?dbhtml filename="prg-exec-monitor/compilation.html"?>
- </tocentry>
- </tocentry>
-
- <tocentry linkend="minimal">
- <?dbhtml filename="minimal.html"?>
- </tocentry>
-
<tocentry linkend="utf">
<?dbhtml filename="utf.html"?>
<tocentry linkend="utf.intro">
@@ -104,46 +72,37 @@
<?dbhtml filename="utf/user-guide/usage-variants/extern-test-runner-variant.html"?>
</tocentry>
</tocentry>
- <tocentry linkend="utf.user-guide.test-runners">
- <?dbhtml filename="utf/user-guide/test-runners.html"?>
- <tocentry linkend="utf.user-guide.external-test-runner">
- <?dbhtml filename="utf/user-guide/usage-variants/extern-test-runner.html"?>
- </tocentry>
- </tocentry>
- <tocentry linkend="utf.user-guide.initialization">
- <?dbhtml filename="utf/user-guide/initialization.html"?>
- </tocentry>
<tocentry linkend="utf.user-guide.test-organization">
<?dbhtml filename="utf/user-guide/test-organization.html"?>
<tocentry linkend="utf.user-guide.test-organization.nullary-test-case">
<?dbhtml filename="utf/user-guide/test-organization/nullary-test-case.html"?>
- <tocentry linkend="utf.user-guide.test-organization.manual-nullary-test-case">
- <?dbhtml filename="utf/user-guide/test-organization/manual-nullary-test-case.html"?>
- </tocentry>
<tocentry linkend="utf.user-guide.test-organization.auto-nullary-test-case">
<?dbhtml filename="utf/user-guide/test-organization/auto-nullary-test-case.html"?>
</tocentry>
+ <tocentry linkend="utf.user-guide.test-organization.manual-nullary-test-case">
+ <?dbhtml filename="utf/user-guide/test-organization/manual-nullary-test-case.html"?>
+ </tocentry>
</tocentry>
<tocentry linkend="utf.user-guide.test-organization.unary-test-case">
<?dbhtml filename="utf/user-guide/test-organization/unary-test-case.html"?>
</tocentry>
<tocentry linkend="utf.user-guide.test-organization.test-case-template">
<?dbhtml filename="utf/user-guide/test-organization/test-case-template.html"?>
- <tocentry linkend="utf.user-guide.test-organization.manual-test-case-template">
- <?dbhtml filename="utf/user-guide/test-organization/manual-test-case-template.html"?>
- </tocentry>
<tocentry linkend="utf.user-guide.test-organization.auto-test-case-template">
<?dbhtml filename="utf/user-guide/test-organization/auto-test-case-template.html"?>
</tocentry>
+ <tocentry linkend="utf.user-guide.test-organization.manual-test-case-template">
+ <?dbhtml filename="utf/user-guide/test-organization/manual-test-case-template.html"?>
+ </tocentry>
</tocentry>
<tocentry linkend="utf.user-guide.test-organization.test-suite">
<?dbhtml filename="utf/user-guide/test-organization/test-suite.html"?>
- <tocentry linkend="utf.user-guide.test-organization.manual-test-suite">
- <?dbhtml filename="utf/user-guide/test-organization/manual-test-suite.html"?>
- </tocentry>
<tocentry linkend="utf.user-guide.test-organization.auto-test-suite">
<?dbhtml filename="utf/user-guide/test-organization/auto-test-suite.html"?>
</tocentry>
+ <tocentry linkend="utf.user-guide.test-organization.manual-test-suite">
+ <?dbhtml filename="utf/user-guide/test-organization/manual-test-suite.html"?>
+ </tocentry>
<tocentry linkend="utf.user-guide.test-organization.master-test-suite">
<?dbhtml filename="utf/user-guide/test-organization/master-test-suite.html"?>
</tocentry>
@@ -152,21 +111,27 @@
<?dbhtml filename="utf/user-guide/test-organization/expected-failures.html"?>
</tocentry>
</tocentry>
- <tocentry linkend="utf.user-guide.fixture">
- <?dbhtml filename="utf/user-guide/fixture.html"?>
- <tocentry linkend="utf.user-guide.fixture.model">
- <?dbhtml filename="utf/user-guide/fixture/model.html"?>
+
+ <tocentry linkend="utf.user-guide.testing-tools">
+ <?dbhtml filename="utf/user-guide/testing-tools.html"?>
+
+ <tocentry linkend="utf.user-guide.testing-tools.output-test">
+ <?dbhtml filename="utf/user-guide/testing-tools/output-test.html"?>
</tocentry>
- <tocentry linkend="utf.user-guide.fixture.per-test-case">
- <?dbhtml filename="utf/user-guide/fixture/per-test-case.html"?>
+
+ <tocentry linkend="utf.user-guide.testing-tools.custom-predicate">
+ <?dbhtml filename="utf/user-guide/testing-tools/custom-predicate.html"?>
</tocentry>
- <tocentry linkend="utf.user-guide.fixture.test-suite-shared">
- <?dbhtml filename="utf/user-guide/fixture/test-suite-shared.html"?>
+
+ <tocentry linkend="utf.user-guide.testing-tools.fpv-comparison">
+ <?dbhtml filename="utf/user-guide/testing-tools/floating_point_comparison.html"?>
</tocentry>
- <tocentry linkend="utf.user-guide.fixture.global">
- <?dbhtml filename="utf/user-guide/fixture/global.html"?>
+
+ <tocentry linkend="utf.user-guide.testing-tools.reference">
+ <?dbhtml filename="utf/user-guide/testing-tools/reference.html"?>
</tocentry>
</tocentry>
+
<tocentry linkend="utf.user-guide.test-output">
<?dbhtml filename="utf/user-guide/test-output.html"?>
<tocentry linkend="utf.user-guide.test-output.log">
@@ -211,25 +176,32 @@
<?dbhtml filename="utf/user-guide/runtime-config/reference.html"?>
</tocentry>
</tocentry>
- </tocentry>
-
- <tocentry linkend="utf.testing-tools">
- <?dbhtml filename="utf/testing-tools.html"?>
-
- <tocentry linkend="utf.testing-tools.output-test">
- <?dbhtml filename="utf/testing-tools/output-test.html"?>
+ <tocentry linkend="utf.user-guide.fixture">
+ <?dbhtml filename="utf/user-guide/fixture.html"?>
+ <tocentry linkend="utf.user-guide.fixture.model">
+ <?dbhtml filename="utf/user-guide/fixture/model.html"?>
+ </tocentry>
+ <tocentry linkend="utf.user-guide.fixture.per-test-case">
+ <?dbhtml filename="utf/user-guide/fixture/per-test-case.html"?>
+ </tocentry>
+ <tocentry linkend="utf.user-guide.fixture.test-suite-shared">
+ <?dbhtml filename="utf/user-guide/fixture/test-suite-shared.html"?>
+ </tocentry>
+ <tocentry linkend="utf.user-guide.fixture.global">
+ <?dbhtml filename="utf/user-guide/fixture/global.html"?>
+ </tocentry>
</tocentry>
-
- <tocentry linkend="utf.testing-tools.custom-predicate">
- <?dbhtml filename="utf/testing-tools/custom-predicate.html"?>
+ <tocentry linkend="utf.user-guide.initialization">
+ <?dbhtml filename="utf/user-guide/initialization.html"?>
</tocentry>
-
- <tocentry linkend="utf.testing-tools.fpv-comparison">
- <?dbhtml filename="utf/testing-tools/floating_point_comparison.html"?>
+ <tocentry linkend="utf.user-guide.test-runners">
+ <?dbhtml filename="utf/user-guide/test-runners.html"?>
+ <tocentry linkend="utf.user-guide.external-test-runner">
+ <?dbhtml filename="utf/user-guide/usage-variants/extern-test-runner.html"?>
+ </tocentry>
</tocentry>
-
- <tocentry linkend="utf.testing-tools.reference">
- <?dbhtml filename="utf/testing-tools/reference.html"?>
+ <tocentry linkend="utf.user-guide.glossary">
+ <?dbhtml filename="utf/user-guide/glossary.html"?>
</tocentry>
</tocentry>
@@ -248,6 +220,43 @@
<?dbhtml filename="utf/usage-recommendations/command-line-specific.html"?>
</tocentry>
</tocentry>
+
+ <tocentry linkend="utf.examples">
+ <?dbhtml filename="utf/examples-collection.html"?>
+ </tocentry>
+
+ </tocentry>
+
+ <tocentry linkend="execution-monitor">
+ <?dbhtml filename="execution-monitor.html"?>
+
+ <tocentry linkend="execution-monitor.compilation">
+ <?dbhtml filename="execution-monitor/compilation.html"?>
+ </tocentry>
+
+ <tocentry linkend="execution-monitor.user-guide">
+ <?dbhtml filename="execution-monitor/user-guide.html"?>
+ </tocentry>
+
+ <tocentry linkend="execution-monitor.reference">
+ <?dbhtml filename="execution-monitor/reference.html"?>
+ </tocentry>
+ </tocentry>
+
+ <tocentry linkend="pem">
+ <?dbhtml filename="prg-exec-monitor.html"?>
+
+ <tocentry linkend="pem.impl">
+ <?dbhtml filename="prg-exec-monitor/impl.html"?>
+ </tocentry>
+
+ <tocentry linkend="pem.compilation">
+ <?dbhtml filename="prg-exec-monitor/compilation.html"?>
+ </tocentry>
+ </tocentry>
+
+ <tocentry linkend="minimal">
+ <?dbhtml filename="minimal.html"?>
</tocentry>
</tocentry>
</toc>
Modified: trunk/libs/test/doc/src/btl.xml
==============================================================================
--- trunk/libs/test/doc/src/btl.xml (original)
+++ trunk/libs/test/doc/src/btl.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -18,6 +18,9 @@
<year>2006</year>
<year>2007</year>
<year>2008</year>
+ <year>2009</year>
+ <year>2010</year>
+ <year>2011</year>
<holder>Gennadiy Rozental</holder>
</copyright>
@@ -156,10 +159,10 @@
</section>
</section>
+ <xi:include href="utf.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="execution-monitor.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="program-execution-monitor.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="minimal-testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<!-- TO FIX: index -->
</library>
Modified: trunk/libs/test/doc/src/examples/example.sln
==============================================================================
--- trunk/libs/test/doc/src/examples/example.sln (original)
+++ trunk/libs/test/doc/src/examples/example.sln 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -1,7 +1,7 @@

-Microsoft Visual Studio Solution File, Format Version 9.00
-# Visual Studio 2005
-Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "example", "example.vcproj", "{9C8197C8-60ED-4D4F-9FFE-F3DFC4C57AE5}"
+Microsoft Visual Studio Solution File, Format Version 11.00
+# Visual C++ Express 2010
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "example", "example.vcxproj", "{9C8197C8-60ED-4D4F-9FFE-F3DFC4C57AE5}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Deleted: trunk/libs/test/doc/src/examples/example.vcproj
==============================================================================
--- trunk/libs/test/doc/src/examples/example.vcproj 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,196 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<VisualStudioProject
- ProjectType="Visual C++"
- Version="8.00"
- Name="example"
- ProjectGUID="{9C8197C8-60ED-4D4F-9FFE-F3DFC4C57AE5}"
- Keyword="Win32Proj"
- >
- <Platforms>
- <Platform
- Name="Win32"
- />
- </Platforms>
- <ToolFiles>
- </ToolFiles>
- <Configurations>
- <Configuration
- Name="Debug|Win32"
- OutputDirectory="Debug"
- IntermediateDirectory="Debug"
- ConfigurationType="1"
- >
- <Tool
- Name="VCPreBuildEventTool"
- />
- <Tool
- Name="VCCustomBuildTool"
- />
- <Tool
- Name="VCXMLDataGeneratorTool"
- />
- <Tool
- Name="VCWebServiceProxyGeneratorTool"
- />
- <Tool
- Name="VCMIDLTool"
- />
- <Tool
- Name="VCCLCompilerTool"
- Optimization="0"
- AdditionalIncludeDirectories="../../../../../"
- PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE;"
- MinimalRebuild="true"
- BasicRuntimeChecks="3"
- RuntimeLibrary="3"
- UsePrecompiledHeader="0"
- WarningLevel="3"
- Detect64BitPortabilityProblems="true"
- DebugInformationFormat="4"
- />
- <Tool
- Name="VCManagedResourceCompilerTool"
- />
- <Tool
- Name="VCResourceCompilerTool"
- />
- <Tool
- Name="VCPreLinkEventTool"
- />
- <Tool
- Name="VCLinkerTool"
- LinkIncremental="2"
- GenerateDebugInformation="true"
- SubSystem="1"
- TargetMachine="1"
- />
- <Tool
- Name="VCALinkTool"
- />
- <Tool
- Name="VCManifestTool"
- />
- <Tool
- Name="VCXDCMakeTool"
- />
- <Tool
- Name="VCBscMakeTool"
- />
- <Tool
- Name="VCFxCopTool"
- />
- <Tool
- Name="VCAppVerifierTool"
- />
- <Tool
- Name="VCWebDeploymentTool"
- />
- <Tool
- Name="VCPostBuildEventTool"
- CommandLine=""$(TargetDir)\$(TargetName).exe" --result_code=no"
- />
- </Configuration>
- <Configuration
- Name="Release|Win32"
- OutputDirectory="Release"
- IntermediateDirectory="Release"
- ConfigurationType="1"
- >
- <Tool
- Name="VCPreBuildEventTool"
- />
- <Tool
- Name="VCCustomBuildTool"
- />
- <Tool
- Name="VCXMLDataGeneratorTool"
- />
- <Tool
- Name="VCWebServiceProxyGeneratorTool"
- />
- <Tool
- Name="VCMIDLTool"
- />
- <Tool
- Name="VCCLCompilerTool"
- AdditionalIncludeDirectories="../../../../../"
- PreprocessorDefinitions="WIN32;NDEBUG;_CONSOLE;"
- RuntimeLibrary="2"
- UsePrecompiledHeader="0"
- WarningLevel="3"
- Detect64BitPortabilityProblems="true"
- DebugInformationFormat="3"
- />
- <Tool
- Name="VCManagedResourceCompilerTool"
- />
- <Tool
- Name="VCResourceCompilerTool"
- />
- <Tool
- Name="VCPreLinkEventTool"
- />
- <Tool
- Name="VCLinkerTool"
- LinkIncremental="2"
- GenerateDebugInformation="true"
- SubSystem="1"
- OptimizeReferences="2"
- EnableCOMDATFolding="2"
- TargetMachine="1"
- />
- <Tool
- Name="VCALinkTool"
- />
- <Tool
- Name="VCManifestTool"
- />
- <Tool
- Name="VCXDCMakeTool"
- />
- <Tool
- Name="VCBscMakeTool"
- />
- <Tool
- Name="VCFxCopTool"
- />
- <Tool
- Name="VCAppVerifierTool"
- />
- <Tool
- Name="VCWebDeploymentTool"
- />
- <Tool
- Name="VCPostBuildEventTool"
- />
- </Configuration>
- </Configurations>
- <References>
- </References>
- <Files>
- <Filter
- Name="Header Files"
- Filter="h;hpp;hxx;hm;inl;inc;xsd"
- UniqueIdentifier="{93995380-89BD-4b04-88EB-625FBE52EBFB}"
- >
- </Filter>
- <Filter
- Name="Resource Files"
- Filter="rc;ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe;resx"
- UniqueIdentifier="{67DA6AB6-F800-4c08-8B7A-83BB121AAD01}"
- >
- </Filter>
- <Filter
- Name="Source Files"
- Filter="cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx"
- UniqueIdentifier="{4FC737F1-C7A5-4376-A066-2A32D752A2FF}"
- >
- <File
- RelativePath="..\snippet\snippet18.cpp"
- >
- </File>
- </Filter>
- </Files>
- <Globals>
- </Globals>
-</VisualStudioProject>
Added: trunk/libs/test/doc/src/examples/example.vcxproj
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/examples/example.vcxproj 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+ <ItemGroup Label="ProjectConfigurations">
+ <ProjectConfiguration Include="Debug|Win32">
+ <Configuration>Debug</Configuration>
+ <Platform>Win32</Platform>
+ </ProjectConfiguration>
+ <ProjectConfiguration Include="Release|Win32">
+ <Configuration>Release</Configuration>
+ <Platform>Win32</Platform>
+ </ProjectConfiguration>
+ </ItemGroup>
+ <ItemGroup>
+ <ClCompile Include="example38.cpp" />
+ </ItemGroup>
+ <PropertyGroup Label="Globals">
+ <ProjectGuid>{9C8197C8-60ED-4D4F-9FFE-F3DFC4C57AE5}</ProjectGuid>
+ <Keyword>Win32Proj</Keyword>
+ </PropertyGroup>
+ <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+ <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'" Label="Configuration">
+ <ConfigurationType>Application</ConfigurationType>
+ </PropertyGroup>
+ <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" Label="Configuration">
+ <ConfigurationType>Application</ConfigurationType>
+ </PropertyGroup>
+ <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+ <ImportGroup Label="ExtensionSettings">
+ </ImportGroup>
+ <ImportGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'" Label="PropertySheets">
+ <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+ </ImportGroup>
+ <ImportGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" Label="PropertySheets">
+ <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+ </ImportGroup>
+ <PropertyGroup Label="UserMacros" />
+ <PropertyGroup>
+ <_ProjectFileVersion>10.0.30319.1</_ProjectFileVersion>
+ <OutDir Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">Debug\</OutDir>
+ <IntDir Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">Debug\</IntDir>
+ <LinkIncremental Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</LinkIncremental>
+ <OutDir Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">Release\</OutDir>
+ <IntDir Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">Release\</IntDir>
+ <LinkIncremental Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">true</LinkIncremental>
+ </PropertyGroup>
+ <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+ <ClCompile>
+ <Optimization>Disabled</Optimization>
+ <AdditionalIncludeDirectories>../../../../../;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+ <PreprocessorDefinitions>WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+ <MinimalRebuild>true</MinimalRebuild>
+ <BasicRuntimeChecks>EnableFastChecks</BasicRuntimeChecks>
+ <RuntimeLibrary>MultiThreadedDebugDLL</RuntimeLibrary>
+ <PrecompiledHeader>
+ </PrecompiledHeader>
+ <WarningLevel>Level3</WarningLevel>
+ <DebugInformationFormat>EditAndContinue</DebugInformationFormat>
+ </ClCompile>
+ <Link>
+ <GenerateDebugInformation>true</GenerateDebugInformation>
+ <SubSystem>Console</SubSystem>
+ <TargetMachine>MachineX86</TargetMachine>
+ </Link>
+ <PostBuildEvent>
+ <Command>"$(TargetDir)\$(TargetName).exe" --result_code=no</Command>
+ </PostBuildEvent>
+ </ItemDefinitionGroup>
+ <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+ <ClCompile>
+ <AdditionalIncludeDirectories>../../../../../;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+ <PreprocessorDefinitions>WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+ <RuntimeLibrary>MultiThreadedDLL</RuntimeLibrary>
+ <PrecompiledHeader>
+ </PrecompiledHeader>
+ <WarningLevel>Level3</WarningLevel>
+ <DebugInformationFormat>ProgramDatabase</DebugInformationFormat>
+ </ClCompile>
+ <Link>
+ <GenerateDebugInformation>true</GenerateDebugInformation>
+ <SubSystem>Console</SubSystem>
+ <OptimizeReferences>true</OptimizeReferences>
+ <EnableCOMDATFolding>true</EnableCOMDATFolding>
+ <TargetMachine>MachineX86</TargetMachine>
+ </Link>
+ </ItemDefinitionGroup>
+ <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+ <ImportGroup Label="ExtensionTargets">
+ </ImportGroup>
+</Project>
\ No newline at end of file
Modified: trunk/libs/test/doc/src/examples/example25.cpp
==============================================================================
--- trunk/libs/test/doc/src/examples/example25.cpp (original)
+++ trunk/libs/test/doc/src/examples/example25.cpp 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -3,7 +3,7 @@
//____________________________________________________________________________//
-int foo() { throw std::runtime_exception( "big trouble" ); }
+int foo() { throw std::runtime_error( "big trouble" ); }
//____________________________________________________________________________//
Modified: trunk/libs/test/doc/src/examples/example38.cpp
==============================================================================
--- trunk/libs/test/doc/src/examples/example38.cpp (original)
+++ trunk/libs/test/doc/src/examples/example38.cpp 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -7,9 +7,9 @@
BOOST_AUTO_TEST_CASE( test )
{
- double res = std::sin( 45. );
+ double res = std::sin( 45. ); // sin 45 radians is actually ~ 0.85, sin 45 degrees is ~0.707
- BOOST_WARN_MESSAGE( res > 1, "sin(45){" << res << "} is <= 1. Hmm.. Strange. " );
+ BOOST_WARN_MESSAGE( res < 0.71, "sin(45){" << res << "} is > 0.71. Arg is not in radian?" );
}
//____________________________________________________________________________//
Modified: trunk/libs/test/doc/src/examples/example38.output
==============================================================================
--- trunk/libs/test/doc/src/examples/example38.output (original)
+++ trunk/libs/test/doc/src/examples/example38.output 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -1,5 +1,5 @@
> example --log_level=warning
Running 1 test case...
-test.cpp(12): warning in "test": sin(45){0.850904} is <= 1. Hmm.. Strange.
+test.cpp(12): warning in "test": sin(45){0.850904} is > 0.71. Arg is not in radian?
*** No errors detected
\ No newline at end of file
Modified: trunk/libs/test/doc/src/execution-monitor.xml
==============================================================================
--- trunk/libs/test/doc/src/execution-monitor.xml (original)
+++ trunk/libs/test/doc/src/execution-monitor.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -256,7 +256,7 @@
second and so on). Unfortunately this feature is, at the moment, implemented only for the Microsoft family of
compilers (and Intel, if it employs Microsoft C Runtime Library). Also it can not be tuned per instance of the
monitor and is only triggered globally and reported after the whole program execution is done. In a future this
- ought to be improved. An interface is composed from two free functions residing in namespace boost:
+ ought to be improved. An interface is composed from two free functions residing in namespace boost::debug:
</para>
<!-- TO FIX -->
@@ -266,8 +266,8 @@
<para role="first-line-indented">
Use function detect_memory_leaks to switch memory leaks detection on/off. Use break_memory_alloc to break a
program execution at allocation specified by mem_alloc_order_num argument. The Unit Test Framework
- provides a runtime parameter (--detect_memory_leak=yes or no) allowing you to manage this feature during monitored
- unit tests.
+ provides a runtime parameter (--detect_memory_leaks=0 or 1 or N>1, where N is memory allocation number)
+ allowing you to manage this feature during monitored unit tests.
</para>
</section>
</section>
Modified: trunk/libs/test/doc/src/faq.xml
==============================================================================
--- trunk/libs/test/doc/src/faq.xml (original)
+++ trunk/libs/test/doc/src/faq.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -30,7 +30,7 @@
<answer>
<para role="first-line-indented">
You can send a bug report to the boost users' mailing list and/or directly to
- <ulink url="mailto:boost-test -at- emailacocunt -dot- com">Gennadiy Rozental</ulink>.
+ <ulink url="mailto:boost-test =at= emailaccount =dot= com">Gennadiy Rozental</ulink>.
</para>
</answer>
</qandaentry>
@@ -44,7 +44,7 @@
<answer>
<para role="first-line-indented">
You can send a request to the boost developers' mailing list and/or directly to
- <ulink url="mailto:boost-test -at- emailacocunt -dot- com">Gennadiy Rozental</ulink>.
+ <ulink url="mailto:boost-test =at= emailaccount -dot- com">Gennadiy Rozental</ulink>.
</para>
</answer>
</qandaentry>
Modified: trunk/libs/test/doc/src/minimal-testing.xml
==============================================================================
--- trunk/libs/test/doc/src/minimal-testing.xml (original)
+++ trunk/libs/test/doc/src/minimal-testing.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -14,7 +14,7 @@
original version of Boost.Test. As the name suggest, it provides only minimal basic facilities for test creation. It
have no configuration parameters (either command line arguments or environment variables) and it supplies
a limited set of <link linkend="minimal.tools">testing tools</link> which behaves similarly to ones defined amount
- the Unit Test Framework <link linkend="utf.testing-tools">Testing tools</link>. The &mtf; supplies its own function
+ the Unit Test Framework <link linkend="utf.user-guide.testing-tools">Testing tools</link>. The &mtf; supplies its own function
main() (so can not be used for multi unit testing) and will execute the test program in a monitored environment.
</para>
@@ -131,7 +131,7 @@
</inline-synopsis>
<para role="first-line-indented">
- Their behavior is modeled after the <link linkend="utf.testing-tools.reference">similarly named tools</link>
+ Their behavior is modeled after the <link linkend="utf.user-guide.testing-tools.reference">similarly named tools</link>
implemented by the Unit Test Framework.
</para>
</section>
Modified: trunk/libs/test/doc/src/program-execution-monitor.xml
==============================================================================
--- trunk/libs/test/doc/src/program-execution-monitor.xml (original)
+++ trunk/libs/test/doc/src/program-execution-monitor.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -40,7 +40,7 @@
<para role="first-line-indented">
Uniform error reporting can be also useful in test environments such as the Boost regression tests. Be aware though
in such case it might be preferable to use the <link linkend="utf">Unit Test Framework</link>, cause it allows one
- to use the <link linkend="utf.testing-tools">Testing tools</link> and generate more detailed error information.
+ to use the <link linkend="utf.user-guide.testing-tools">Testing tools</link> and generate more detailed error information.
</para>
</section>
Added: trunk/libs/test/doc/src/utf.examples.xml
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/utf.examples.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,304 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
+ <!ENTITY utf "<acronym>UTF</acronym>">
+]>
+<section id="utf.examples">
+ <title>The &utf; usage examples collection</title>
+ <titleabbrev>Examples collection</titleabbrev>
+
+ <itemizedlist mark ="square">
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.auto-nullary-test-case.example06"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example01"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example02"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example03"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example04"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example05"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.unary-test-case.example07"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.unary-test-case.example08"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.auto-test-case-template.example10"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-test-case-template.example09"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.auto-test-suite.example12"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-test-suite.example11"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.cla-access.example13"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.master-test-suite-name.example14"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.master-test-suite-name.example15"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.manual-expected-failures.example16"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.auto-expected-failures.example17"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.testing-tools.output-test.example28"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.testing-tools.output-test.example29"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.testing-tools.custom-predicate.example30"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.testing-tools.custom-predicate.example31"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example33"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.testing-tool-args.example32"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.BOOST_TEST_MESSAGE.example21"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.BOOST_TEST_CHECKPOINT.example22"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.BOOST_TEST_PASSPOINT.example23"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.fixture.per-test-case.example18"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.fixture.test-suite-shared.example19"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.fixture.global.example20"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="pem.usage.example24"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="pem.usage.example25"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="pem.usage.example26"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="minimal.example.example27"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example34"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example35"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example36"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example37"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example38"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example39"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example40"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example41"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example42"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example43"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example44"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example45"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example46"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example47"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example48"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.progress.example49"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.ct-config.output-stream.example50"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.ct-config.log-level.example51"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-output.log.ct-config.log-format.example52"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend="utf.user-guide.test-organization.auto-test-suite.example53"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example54"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example55"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example56"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example57"/>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <xref linkend=".example58"/>
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+
+
+</section>
\ No newline at end of file
Modified: trunk/libs/test/doc/src/utf.tutorials.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.tutorials.xml (original)
+++ trunk/libs/test/doc/src/utf.tutorials.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -8,7 +8,9 @@
<para role="first-line-indented">
You think writing tests is difficult, annoying and fruitless work? I beg to differ. Read through these tutorials
- and I am sure you will agree.
+ and I am sure you will agree. One other thing I do suggest you to take a look is
+ <link linkend="utf.compilation">compilation instructions</link>, especially if you plan to build and use standalone
+ library.
</para>
<xi:include href="tutorial.intro-in-testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
Added: trunk/libs/test/doc/src/utf.user-guide.glossary.xml
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/utf.user-guide.glossary.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,235 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
+ <!ENTITY utf "<acronym>UTF</acronym>">
+]>
+ <section id="utf.user-guide.glossary">
+ <title>Introduction … or what's your name?</title><titleabbrev>Introduction</titleabbrev>
+
+ <para role="first-line-indented">
+ Without further ado, let's define terms regularly used by the &utf;.
+ </para>
+ <variablelist>
+ <?dbhtml term-width="16%" list-width="100%"?>
+ <?dbhtml term-separator=":"?>
+ <?dbhtml table-summary="utf terms definition"?>
+
+ <varlistentry id="test-module.def">
+ <term><firstterm>The test module</firstterm></term>
+ <listitem>
+ <simpara>
+ This is a single binary that performs the test. Physically a test module consists of one or more test source files,
+ which can be built into an executable or a dynamic library. A test module that consists of a single test source
+ file is called <firstterm id="single-file-test-module.def">single-file test module</firstterm>. Otherwise
+ it's called <firstterm id="multi-file-test-module.def">multi-file test module</firstterm>. Logically a test
+ module consists of four parts: <link linkend="test-setup.def">test setup</link> (or test initialization),
+ <link linkend="test-body.def">test body</link>, <link linkend="test-cleanup.def">test cleanup</link> and
+ <link linkend="test-runner.def">test runner</link>. The test runner part is optional. If a test module is built as
+ an executable the test runner is built-in. If a test module is built as a dynamic library, it is run by an
+ external test runner.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-body.def">
+ <term><firstterm>The test body</firstterm></term>
+ <listitem>
+ <simpara>
+ This is the part of a test module that actually performs the test.
+ Logically test body is a collection of <link linkend="test-assertion.def">test assertions</link> wrapped in
+ <link linkend="test-case.def">test cases</link>, which are organized in a <link linkend="test-tree.def">test tree
+ </link>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-tree.def">
+ <term><firstterm>The test tree</firstterm></term>
+ <listitem>
+ <simpara>
+ This is a hierarchical structure of <link linkend="test-suite.def">test suites</link> (non-leaf nodes) and
+ <link linkend="test-case.def">test cases</link> (leaf nodes).
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-unit.def">
+ <term><firstterm>The test unit</firstterm></term>
+ <listitem>
+ <simpara>
+ This is a collective name when referred to either <link linkend="test-suite.def">test suite</link> or
+ <link linkend="test-case.def">test case</link>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-assertion.def">
+ <term><firstterm>Test assertion</firstterm></term>
+ <listitem>
+ <simpara>
+ This is a single binary condition (binary in a sense that is has two outcomes: pass and fail) checked
+ by a test module.
+ </simpara>
+ <simpara>
+ There are different schools of thought on how many test assertions a test case should consist of. Two polar
+ positions are the one advocated by TDD followers - one assertion per test case; and opposite of this - all test
+ assertions within single test case - advocated by those only interested in the first error in a
+ test module. The &utf; supports both approaches.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-case.def">
+ <term><firstterm>The test case</firstterm></term>
+ <listitem>
+ <simpara>
+ This is an independently monitored function within a test module that
+ consists of one or more test assertions. The term "independently monitored" in the definition above is
+ used to emphasize the fact, that all test cases are monitored independently. An uncaught exception or other normal
+ test case execution termination doesn't cause the testing to cease. Instead the error is caught by the test
+ case execution monitor, reported by the &utf; and testing proceeds to the next test case. Later on you are going
+ to see that this is on of the primary reasons to prefer multiple small test cases to a single big test function.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-suite.def">
+ <term><firstterm>The test suite</firstterm></term>
+ <listitem>
+ <simpara>
+ This is a container for one or more test cases. The test suite gives you an ability to group
+ test cases into a single referable entity. There are various reasons why you may opt to do so, including:
+ </simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>To group test cases per subsystems of the unit being tested.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>To share test case setup/cleanup code.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>To run selected group of test cases only.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>To see test report split by groups of test cases</simpara>
+ </listitem>
+ <listitem>
+ <simpara>To skip groups of test cases based on the result of another test unit in a test tree.</simpara>
+ </listitem>
+ </itemizedlist>
+ <simpara>
+ A test suite can also contain other test suites, thus allowing a hierarchical test tree structure to be formed.
+ The &utf; requires the test tree to contain at least one test suite with at least one test case. The top level
+ test suite - root node of the test tree - is called the master test suite.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-setup.def">
+ <term><firstterm>The test setup</firstterm></term>
+ <listitem>
+ <simpara>
+ This is the part of a test module that is responsible for the test
+ preparation. It includes the following operations that take place prior to a start of the test:
+ </simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ The &utf; initialization
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Test tree construction
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Global test module setup code
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <simpara>
+ Per test case" setup code, invoked for every test case it's assigned to, is also attributed to the
+ test initialization, even though it's executed as a part of the test case.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-cleanup.def">
+ <term><firstterm>The test cleanup</firstterm></term>
+ <listitem>
+ <simpara>
+ This is the part of test module that is responsible for cleanup operations.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-fixture.def">
+ <term><firstterm>The test fixture</firstterm></term>
+ <listitem>
+ <simpara>
+ Matching setup and cleanup operations are frequently united into a single entity called test fixture.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-runner.def">
+ <term><firstterm>The test runner</firstterm></term>
+ <listitem>
+ <simpara>
+ This is an "executive manager" that runs the show. The test runner's functionality should include
+ the following interfaces and operations:
+ </simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Entry point to a test module. This is usually either the function main() itself or single function that can be
+ invoked from it to start testing.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Initialize the &utf; based on runtime parameters
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Select an output media for the test log and the test results report
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Select test cases to execute based on runtime parameters
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Execute all or selected test cases
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Produce the test results report
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Generate a test module result code.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <para role="first-line-indented">
+ An advanced test runner may provide additional features, including interactive <acronym>GUI</acronym> interfaces,
+ test coverage and profiling support.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-log.def">
+ <term><firstterm>The test log</firstterm></term>
+ <listitem>
+ <simpara>
+ This is the record of all events that occur during the testing.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="test-results-report.def">
+ <term><firstterm>The test results report</firstterm></term>
+ <listitem>
+ <simpara>
+ This is the report produced by the &utf; after the testing is completed, that indicates which test cases/test
+ suites passed and which failed.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
Added: trunk/libs/test/doc/src/utf.user-guide.initialization.xml
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/utf.user-guide.initialization.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
+ <!ENTITY utf "<acronym>UTF</acronym>">
+]>
+ <section id="utf.user-guide.initialization">
+ <title>Test module initialization … or ready, set …</title>
+ <titleabbrev>Test module initialization</titleabbrev>
+
+ <para role="first-line-indented">
+ There are two tasks that you may need to perform before actual testing can start:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ The test tree needs to be built (unless you are using automated test units registration).
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Custom test module initialization needs to be performed. This includes
+ initialization of the code under test and custom tune-up of the &utf; parameters (for example the test log or the
+ test results report output streams redirection).
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para role="first-line-indented">
+ The function dedicated for this purpose is called <firstterm>the test module initialization function</firstterm>. Alternatively you can
+ employ global fixtures, covered in details, including differences in two approaches, in
+ <xref linkend="utf.user-guide.fixture"/>.
+ </para>
+
+ <para role="first-line-indented">
+ The &utf; requires you to implement the test module initialization function. The test runner supplied with the static
+ library or single-header variants of the &utf; requires the specific function specification. The test runner supplied
+ with the dynamic library variant of the &utf; requires the specific initialization function signature only. <!-- TO FIX: specific specification -->
+ </para>
+
+ <para role="first-line-indented">
+ For many <link linkend="test-module.def">test modules</link> you don't need to do any custom initialization
+ and test tree construction is automated. In this case you don't really need the initialization function and
+ the &utf; provides a way to automatically generate an empty one for you.
+ </para>
+
+ <para role="first-line-indented">
+ Original design of the &utf; supported the manual test tree construction only. Later versions introduced the
+ automated registration of test units. In later versions of the &utf; the original initialization function
+ specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification
+ was introduced. This change is not backward compatible. The test runners supplied with the static library and
+ single-header variants of the &utf; by default still require original initialization function specification, but
+ support <link linkend="utf.compilation.flags">compilation flags</link> that switch to the alternative one. The test
+ runner supplied with dynamic library variant of the &utf; requires new specification and doesn't support
+ original one. The plan is to deprecate the original initialization function specification in one of the future
+ releases and ultimately to stop supporting it.
+ </para>
+
+ <para role="first-line-indented">
+ The initialization function invocation is monitored by the &utf; the same way as all the test cases. An unexpected
+ exception or system error detected during initialization function invocation is treated as initialization error and
+ is reported as such.
+ </para>
+
+ <section id="utf.user-guide.initialization.orig-signature">
+ <title>Original initialization function signature and name</title>
+ <titleabbrev>Original initialization function</titleabbrev>
+
+ <para role="first-line-indented">
+ The original design of the &utf; initialization required you to implement the function with the following
+ specification:
+ </para>
+
+ <programlisting><classname>boost::unit_test::test_suite</classname>* init_unit_test_suite( int argc, char* argv[] );</programlisting>
+
+ <para role="first-line-indented">
+ This function was intended to initialize and return a master test suite. The null value was considered an initialization
+ error. The current design of the &utf; maintains master test suite instance internally and does not treat the null result
+ value as an initialization error. In fact it's recommended to return null value always and register test units in the
+ master test suite using the regular test suite add interface. The only way to indicate an initialization error is to throw the
+ <classname>boost::unit_test::framework::setup_error</classname> exception.
+ </para>
+
+ <para role="first-line-indented">
+ The initialization function parameters argc, argv provide the command line arguments specified during test
+ module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be
+ consisted with the alternative initialization function specification it's recommended though to access the
+ command line arguments using the master test suite interface.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.initialization.alt-signature">
+ <title>Alternative initialization function signature and name</title>
+ <titleabbrev>Alternative initialization function</titleabbrev>
+
+ <para role="first-line-indented">
+ The alternative design of the &utf; initialization requires you to implement a function with the following
+ specification:
+ </para>
+
+ <programlisting>bool init_unit_test();</programlisting>
+
+ <para role="first-line-indented">
+ The result value of this function indicates whether or not initialization was successful. To register test
+ units in a master test suite use the test suite add interface. To access command line arguments use the master
+ test suite interface. It's guarantied that any framework-specific command line arguments are excluded.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.initialization.signature-typedef">
+ <title>Initialization function signature access</title>
+
+ <para role="first-line-indented">
+ The test runner interface needs to refer to the initialization function signature. The &utf; provides the typedef
+ that resolves to proper signature in all configurations:
+ </para>
+
+ <programlisting>namespace boost {
+namespace unit_test {
+#ifdef BOOST_TEST_ALTERNATIVE_INIT_API
+typedef bool (*init_unit_test_func)();
+#else
+typedef test_suite* (*init_unit_test_func)( int, char* [] );
+#endif
+}
+}</programlisting>
+
+ </section>
+
+ <section id="utf.user-guide.initialization.auto-generation">
+ <title>Automated generation of the test module initialization function</title>
+ <titleabbrev>Automated generation</titleabbrev>
+
+ <para role="first-line-indented">
+ To automatically generate an empty test module initialization function you need to define
+ <xref linkend="utf.flag.main" endterm="utf.flag.main"/> before including the
+ <filename class="headerfile">boost/test/unit_test.hpp</filename> header. The value of this define is ignored.
+ Alternatively you can define the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/> to be equal to
+ any string (not necessarily in quotes). This macro causes the same result as
+ <xref linkend="utf.flag.main" endterm="utf.flag.main"/>, and in addition the macro value becomes the name of the
+ master test suite.
+ </para>
+
+ <important>
+ <simpara>
+ For a test module consisting of multiple source files you have to define these flags in a single test file only.
+ Otherwise you end up with multiple instances of the initialization function.
+ </simpara>
+ </important>
+ </section>
+ </section>
Modified: trunk/libs/test/doc/src/utf.user-guide.runtime-config.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.user-guide.runtime-config.xml (original)
+++ trunk/libs/test/doc/src/utf.user-guide.runtime-config.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -265,6 +265,24 @@
</descr>
</refentry>
+ <refentry name="break_exec_path">
+ <name>Break execution path</name>
+ <env>BOOST_TEST_BREAK_EXEC_PATH</env>
+ <cla>break_exec_path"</cla>
+ <vals>
+ <simplelist>
+ <member>string consisting of space separate test_name:execution_path_number pairs</member>
+ </simplelist>
+ </vals>
+ <descr>
+ <simpara>
+ this runtime parameter is used by exception safety tester. By default exception safety tester only reports index of
+ execution path and test case name where failure occurred. Using this parameter you can make the tester to break the
+ execution right before entering this path.
+ </simpara>
+ </descr>
+ </refentry>
+
<refentry name="build_info">
<name>Print build info</name>
<env>BOOST_TEST_BUILD_INFO</env>
@@ -301,25 +319,20 @@
</descr>
</refentry>
- <refentry name="detect_memory_leak">
- <name>Detect memory leaks</name>
- <env>BOOST_TEST_DETECT_MEMORY_LEAK</env>
- <cla>detect_memory_leaks</cla>
+ <refentry name="color_output">
+ <name>Produce color output</name>
+ <env>BOOST_TEST_COLOR_OUTPUT</env>
+ <cla>color_output</cla>
<vals>
<simplelist>
- <member>0</member>
- <member><emphasis role="bold">1</emphasis></member>
- <member>integer value > 1</member>
+ <member><emphasis role="bold">no</emphasis></member>
+ <member>yes</member>
</simplelist>
</vals>
<descr>
<simpara>
- positive value tells the framework to detect the memory leaks (if any). Any value greater then 1 in addition
- is treated as leak allocation number and setup runtime breakpoint. In other words setting this parameter to
- the positive value N greater than 1 causes the framework to set a breakpoint at Nth memory allocation (don't
- do that from the command line - only when you are under debugger). Note: if your test program produce memory
- leaks notifications, they are combined with allocation number values you could use to set a breakpoint.
- Currently only applies to MS family of compilers.
+ The &utf; is able to produce color output on systems which supports it. To enable this behavior set the parameter to
+ 'yes'. By default the output produces in not colored.
</simpara>
</descr>
</refentry>
@@ -340,7 +353,30 @@
</simpara>
</descr>
</refentry>
-
+
+ <refentry name="detect_memory_leaks">
+ <name>Detect memory leaks</name>
+ <env>BOOST_TEST_DETECT_MEMORY_LEAK</env>
+ <cla>detect_memory_leaks</cla>
+ <vals>
+ <simplelist>
+ <member>0</member>
+ <member><emphasis role="bold">1</emphasis></member>
+ <member>integer value > 1</member>
+ </simplelist>
+ </vals>
+ <descr>
+ <simpara>
+ positive value tells the framework to detect the memory leaks (if any). Any value greater then 1 in addition
+ is treated as leak allocation number and setups runtime breakpoint. In other words setting this parameter to
+ the positive value N greater than 1 causes the framework to set a breakpoint at Nth memory allocation (don't
+ do that from the command line - only when you are under debugger). Note: if your test program produce memory
+ leaks notifications, they are combined with allocation number values you could use to set a breakpoint.
+ Currently only applies to MS family of compilers.
+ </simpara>
+ </descr>
+ </refentry>
+
<refentry name="log_format">
<name>The log format</name>
<env>BOOST_TEST_LOG_FORMAT</env>
@@ -419,6 +455,27 @@
</descr>
</refentry>
+ <refentry name="log_sink">
+ <name>The log sink name</name>
+ <env>BOOST_TEST_LOG_SINK</env>
+ <cla>log_sink</cla>
+ <vals>
+ <simplelist>
+ <member><emphasis role="bold">stdout</emphasis></member>
+ <member>stderr</member>
+ <member>arbitrary file name</member>
+ </simplelist>
+ </vals>
+ <descr>
+ <simpara>
+ This parameter allows easily redirect the test log. The parameter value is the string containing either a file
+ name, in which case the &utf; will redirect log into file with that name, or 'stdout', in which case log is
+ redirected into standard output stream, or 'stderr' , in which case log is redirected into standard error stream.
+ Default is 'stdout'
+ </simpara>
+ </descr>
+ </refentry>
+
<refentry name="output_format">
<name>The output format</name>
<env>BOOST_TEST_OUTPUT_FORMAT</env>
@@ -495,6 +552,27 @@
</descr>
</refentry>
+ <refentry name="report_sink">
+ <name>The report sink name</name>
+ <env>BOOST_TEST_REPORT_SINK</env>
+ <cla>report_sink</cla>
+ <vals>
+ <simplelist>
+ <member><emphasis role="bold">stderr</emphasis></member>
+ <member>stdout</member>
+ <member>arbitrary file name</member>
+ </simplelist>
+ </vals>
+ <descr>
+ <simpara>
+ This parameter allows easily redirect the test results report. The parameter value is the string containing either
+ a file name, in which case the &utf; will redirect results report into file with that name, or 'stdout', in which case
+ report is redirected into standard output stream, or 'stderr', in which case report is redirected into standard error
+ stream. Default is 'stderr'.
+ </simpara>
+ </descr>
+ </refentry>
+
<refentry name="result_code">
<name>[Do not] return result code</name>
<env>BOOST_TEST_RESULT_CODE</env>
@@ -532,6 +610,26 @@
</descr>
</refentry>
+ <refentry name="save_patterm">
+ <name>Save patterm</name>
+ <env>BOOST_TEST_SAVE_PATTERN</env>
+ <cla>save_pattern</cla>
+ <vals>
+ <simplelist>
+ <member><emphasis role="bold">no</emphasis></member>
+ <member>yes</member>
+ </simplelist>
+ </vals>
+ <descr>
+ <simpara>
+ this parameter serves no particular purpose within the framework itself. It can be used by test modules relying
+ on output_test_stream to implement testing logic. output_test_stream has two modes of operation: save the pattern
+ file and match against stored pattern. You can use this parameter to switch between these modes, by passing the
+ parameter value to the output_test_stream constructor.
+ </simpara>
+ </descr>
+ </refentry>
+
<refentry name="show_progress">
<name>Show progress</name>
<env>BOOST_TEST_SHOW_PROGRESS</env>
Copied: trunk/libs/test/doc/src/utf.user-guide.test-organization.xml (from r73722, /trunk/libs/test/doc/src/utf.users-guide.test-organization.xml)
==============================================================================
--- /trunk/libs/test/doc/src/utf.users-guide.test-organization.xml (original)
+++ trunk/libs/test/doc/src/utf.user-guide.test-organization.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -113,16 +113,47 @@
<itemizedlist>
<listitem>
<simpara>
- <link linkend="utf.user-guide.test-organization.manual-nullary-test-case">Manually registered test case</link>
+ <link linkend="utf.user-guide.test-organization.auto-nullary-test-case">Test case with automated registration</link>
</simpara>
</listitem>
<listitem>
<simpara>
- <link linkend="utf.user-guide.test-organization.auto-nullary-test-case">Test case with automated registration</link>
+ <link linkend="utf.user-guide.test-organization.manual-nullary-test-case">Manually registered test case</link>
</simpara>
</listitem>
</itemizedlist>
+ <section id="utf.user-guide.test-organization.auto-nullary-test-case">
+ <title>Nullary function based test case with automated registration</title>
+ <titleabbrev>Automated registration</titleabbrev>
+
+ <para role="first-line-indented">
+ To create a nullary free function cased test case, which is registered in place of implementation, employ the
+ macro BOOST_AUTO_TEST_CASE.
+ </para>
+
+ <inline-synopsis>
+ <macro name="BOOST_AUTO_TEST_CASE" kind="functionlike">
+ <macro-parameter name="test_case_name"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ The macro is designed to closely mimic nullary free function syntax. Changes that are required to make an
+ existing test case, implemented as a free function, registered in place are illustrated in the following
+ example (compare with <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example01"/>):
+ </para>
+
+ <btl-example name="example06">
+ <title>Nullary function based test case with automated registration</title>
+ </btl-example>
+
+ <para role="first-line-indented">
+ With this macro you don't need to implement the initialization function at all. The macro creates and
+ registers the test case with the name free_test_function automatically.
+ </para>
+ </section>
+
<section id="utf.user-guide.test-organization.manual-nullary-test-case">
<title>Manually registered nullary function based test case</title>
<titleabbrev>Manual registration</titleabbrev>
@@ -212,37 +243,6 @@
<xref linkend="utf.user-guide.test-organization.unary-test-case"/>.
</para>
</section>
-
- <section id="utf.user-guide.test-organization.auto-nullary-test-case">
- <title>Nullary function based test case with automated registration</title>
- <titleabbrev>Automated registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a nullary free function cased test case, which is registered in place of implementation, employ the
- macro BOOST_AUTO_TEST_CASE.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_AUTO_TEST_CASE" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The macro is designed to closely mimic nullary free function syntax. Changes that are required to make an
- existing test case, implemented as a free function, registered in place are illustrated in the following
- example (compare with <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example01"/>):
- </para>
-
- <btl-example name="example06">
- <title>Nullary function based test case with automated registration</title>
- </btl-example>
-
- <para role="first-line-indented">
- With this macro you don't need to implement the initialization function at all. The macro creates and
- registers the test case with the name free_test_function automatically.
- </para>
- </section>
</section>
<section id="utf.user-guide.test-organization.unary-test-case">
<title>Unary function based test case</title>
@@ -331,18 +331,74 @@
<itemizedlist>
<listitem>
<simpara>
- <link linkend="utf.user-guide.test-organization.manual-test-case-template">Manually registered test case
- template</link>
+ <link linkend="utf.user-guide.test-organization.auto-test-case-template">Test case template with automated
+ registration</link>
</simpara>
</listitem>
<listitem>
<simpara>
- <link linkend="utf.user-guide.test-organization.auto-test-case-template">Test case template with automated
- registration</link>
+ <link linkend="utf.user-guide.test-organization.manual-test-case-template">Manually registered test case
+ template</link>
</simpara>
</listitem>
</itemizedlist>
+ <section id="utf.user-guide.test-organization.auto-test-case-template">
+ <title>Test case template with automated registration</title>
+ <titleabbrev>Automated registration</titleabbrev>
+
+ <para role="first-line-indented">
+ To create a test case template registered in place of implementation, employ the macro
+ BOOST_AUTO_TEST_CASE_TEMPLATE. This facility is also called <firstterm>auto test case template</firstterm>.
+ </para>
+
+ <inline-synopsis>
+ <macro name="BOOST_AUTO_TEST_CASE_TEMPLATE" kind="functionlike">
+ <macro-parameter name="test_case_name"/>
+ <macro-parameter name="formal_type_parameter_name"/>
+ <macro-parameter name="collection_of_types"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ The macro BOOST_AUTO_TEST_CASE_TEMPLATE requires three arguments:
+ </para>
+ <variablelist>
+ <?dbhtml list-presentation="list"?>
+ <?dbhtml term-width="60%" list-width="100%"?>
+ <?dbhtml term-separator=" - "?> <!-- TO FIX: where separator? -->
+
+ <varlistentry>
+ <term>The test case template name</term>
+ <listitem>
+ <simpara>
+ unique test cases template identifier
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>The name of a formal template parameter</term>
+ <listitem>
+ <simpara>
+ name of the type the test case template is instantiated with
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>The collection of types to instantiate test case template with</term>
+ <listitem>
+ <simpara>
+ arbitrary MPL sequence
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <btl-example name="example10">
+ <title>Test case template with automated registration</title>
+ </btl-example>
+ </section>
+
<section id="utf.user-guide.test-organization.manual-test-case-template">
<title>Manually registered test case template</title>
<titleabbrev>Manual registration</titleabbrev>
@@ -438,62 +494,6 @@
<title>Manually registered test case template</title>
</btl-example>
</section>
-
- <section id="utf.user-guide.test-organization.auto-test-case-template">
- <title>Test case template with automated registration</title>
- <titleabbrev>Automated registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a test case template registered in place of implementation, employ the macro
- BOOST_AUTO_TEST_CASE_TEMPLATE. This facility is also called <firstterm>auto test case template</firstterm>.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_AUTO_TEST_CASE_TEMPLATE" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- <macro-parameter name="formal_type_parameter_name"/>
- <macro-parameter name="collection_of_types"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The macro BOOST_AUTO_TEST_CASE_TEMPLATE requires three arguments:
- </para>
- <variablelist>
- <?dbhtml list-presentation="list"?>
- <?dbhtml term-width="60%" list-width="100%"?>
- <?dbhtml term-separator=" - "?> <!-- TO FIX: where separator? -->
-
- <varlistentry>
- <term>The test case template name</term>
- <listitem>
- <simpara>
- unique test cases template identifier
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>The name of a formal template parameter</term>
- <listitem>
- <simpara>
- name of the type the test case template is instantiated with
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>The collection of types to instantiate test case template with</term>
- <listitem>
- <simpara>
- arbitrary MPL sequence
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <btl-example name="example10">
- <title>Test case template with automated registration</title>
- </btl-example>
- </section>
</section>
<section id="utf.user-guide.test-organization.test-suite">
@@ -510,99 +510,22 @@
<itemizedlist>
<listitem>
<simpara>
- <link linkend="utf.user-guide.test-organization.manual-test-suite">Manually registered test suite</link>
+ <link linkend="utf.user-guide.test-organization.auto-test-suite">Test suite with automated registration</link>
</simpara>
</listitem>
<listitem>
<simpara>
- <link linkend="utf.user-guide.test-organization.auto-test-suite">Test suite with automated registration</link>
+ <link linkend="utf.user-guide.test-organization.manual-test-suite">Manually registered test suite</link>
</simpara>
</listitem>
</itemizedlist>
- <section id="utf.user-guide.test-organization.test-suite-registration-interface">
- <title>Test unit registration interface</title>
-
- <para role="first-line-indented">
- The &utf; models the notion of test case container - test suite - using class boost::unit_test::test_suite. For
- complete class interface reference check advanced section of this documentation. Here you should only be
- interested in a single test unit registration interface:
- </para>
-
- <programlisting>void test_suite::add( test_unit* tc, counter_t expected_failures = 0, int timeout = 0 );</programlisting>
-
- <para role="first-line-indented">
- The first parameter is a pointer to a newly created test unit. The second optional parameter -
- expected_failures - defines the number of test assertions that are expected to fail within the test unit. By
- default no errors are expected.
- </para>
-
- <caution>
- <simpara>
- Be careful when supplying a number of expected failures for test suites. By default the &utf; calculates the
- number of expected failures in test suite as the sum of appropriate values in all test units that constitute
- it. And it rarely makes sense to change this.
- </simpara>
- </caution>
-
- <para role="first-line-indented">
- The third optional parameter - timeout - defines the timeout value for the test unit. As of now the &utf;
- isn't able to set a timeout for the test suite execution, so this parameter makes sense only for test case
- registration. By default no timeout is set. See the method
- <methodname>boost::execution_monitor::execute</methodname> for more details about the timeout value.
- </para>
-
- <para role="first-line-indented">
- To register group of test units in one function call the boost::unit_test::test_suite provides another add
- interface covered in the advanced section of this documentation.
- </para>
- </section>
-
- <section id="utf.user-guide.test-organization.manual-test-suite">
- <title>Manually registered test suites</title>
- <titleabbrev>Manual registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a test suite manually, employ the macro BOOST_TEST_SUITE:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_SUITE" kind="functionlike">
- <macro-parameter name="test_suite_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- BOOST_TEST_SUITE creates an instance of the class boost::unit_test::test_suite and returns a pointer to the
- constructed instance. Alternatively you can create an instance of class boost::unit_test::test_suite yourself.
- </para>
-
- <note>
- <simpara>
- boost::unit_test::test_suite instances have to be allocated on the heap and the compiler won't allow you
- to create one on the stack.
- </simpara>
- </note>
-
- <para role="first-line-indented">
- Newly created test suite has to be registered in a parent one using add interface. Both test suite creation and
- registration is performed in the test module initialization function.
- </para>
-
- <btl-example name="example11">
- <title>Manually registered test suites</title>
- </btl-example>
-
- <para role="first-line-indented">
- This example creates a test tree, which can be represented by the following hierarchy:
- </para>
-
- <mediaobject>
- <imageobject>
- <imagedata format="jpg" fileref="../img/class-hier.jpg"/>
- </imageobject>
- </mediaobject>
- </section>
+ <para role="first-line-indented">
+ In addition the &utf; presents a notion of
+ <link linkend="utf.user-guide.test-organization.master-test-suite">Master Test Suite</link>. The most important
+ reason to learn about this component is that it provides an ability to access command line arguments supplied
+ to a test module.
+ </para>
<section id="utf.user-guide.test-organization.auto-test-suite">
<title>Test suites with automated registration</title>
@@ -656,6 +579,101 @@
</btl-example>
</section>
+
+ <section id="utf.user-guide.test-organization.manual-test-suite">
+ <title>Manually registered test suites</title>
+ <titleabbrev>Manual registration</titleabbrev>
+
+ <para role="first-line-indented">
+ To create a test suite manually you need to create an instance of boost::unit_test::test_suite class, register
+ it in test tree and populate it with test cases (or lower level test suites).
+ </para>
+
+ <section id="utf.user-guide.test-organization.test-suite-registration-interface">
+ <title>Test unit registration interface</title>
+
+ <para role="first-line-indented">
+ The &utf; models the notion of test case container - test suite - using class boost::unit_test::test_suite. For
+ complete class interface reference check advanced section of this documentation. Here you should only be
+ interested in a single test unit registration interface:
+ </para>
+
+ <programlisting>void test_suite::add( test_unit* tc, counter_t expected_failures = 0, int timeout = 0 );</programlisting>
+
+ <para role="first-line-indented">
+ The first parameter is a pointer to a newly created test unit. The second optional parameter -
+ expected_failures - defines the number of test assertions that are expected to fail within the test unit. By
+ default no errors are expected.
+ </para>
+
+ <caution>
+ <simpara>
+ Be careful when supplying a number of expected failures for test suites. By default the &utf; calculates the
+ number of expected failures in test suite as the sum of appropriate values in all test units that constitute
+ it. And it rarely makes sense to change this.
+ </simpara>
+ </caution>
+
+ <para role="first-line-indented">
+ The third optional parameter - timeout - defines the timeout value for the test unit. As of now the &utf;
+ isn't able to set a timeout for the test suite execution, so this parameter makes sense only for test case
+ registration. By default no timeout is set. See the method
+ <methodname>boost::execution_monitor::execute</methodname> for more details about the timeout value.
+ </para>
+
+ <para role="first-line-indented">
+ To register group of test units in one function call the boost::unit_test::test_suite provides another add
+ interface covered in the advanced section of this documentation.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.test-organization.test-suite-instance-construction">
+ <title>Test suite instance construction</title>
+
+ <para role="first-line-indented">
+ To create a test suite instance manually, employ the macro BOOST_TEST_SUITE. It hides all implementation
+ details and you only required to specify the test suite name:
+ </para>
+
+ <inline-synopsis>
+ <macro name="BOOST_TEST_SUITE" kind="functionlike">
+ <macro-parameter name="test_suite_name"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ BOOST_TEST_SUITE creates an instance of the class boost::unit_test::test_suite and returns a pointer to the
+ constructed instance. Alternatively you can create an instance of class boost::unit_test::test_suite yourself.
+ </para>
+
+ <note>
+ <simpara>
+ boost::unit_test::test_suite instances have to be allocated on the heap and the compiler won't allow you
+ to create one on the stack.
+ </simpara>
+ </note>
+
+ <para role="first-line-indented">
+ Newly created test suite has to be registered in a parent one using add interface. Both test suite creation and
+ registration is performed in the test module initialization function.
+ </para>
+ </section>
+
+ <btl-example name="example11">
+ <title>Manually registered test suites</title>
+ </btl-example>
+
+ <para role="first-line-indented">
+ This example creates a test tree, which can be represented by the following hierarchy:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata format="jpg" fileref="../img/class-hier.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+
<section id="utf.user-guide.test-organization.master-test-suite">
<title>Master Test Suite</title>
Copied: trunk/libs/test/doc/src/utf.user-guide.test-output.xml (from r73722, /trunk/libs/test/doc/src/utf.users-guide.test-output.xml)
==============================================================================
--- /trunk/libs/test/doc/src/utf.users-guide.test-output.xml (original)
+++ trunk/libs/test/doc/src/utf.user-guide.test-output.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -16,7 +16,7 @@
<simpara>All test errors are reported uniformly</simpara>
<simpara>
The test execution monitor along with standardized output from all included
- <link linkend="utf.testing-tools">testing tools</link> provides uniform reporting for all errors including fatal
+ <link linkend="utf.user-guide.testing-tools">testing tools</link> provides uniform reporting for all errors including fatal
errors, like memory assess violation and uncaught exceptions.
</simpara>
</listitem>
@@ -175,10 +175,10 @@
<title>Logging tool arguments</title>
<para role="first-line-indented">
- Most of the <link linkend="utf.testing-tools">testing tools</link> print values of their arguments to the output
+ Most of the <link linkend="utf.user-guide.testing-tools">testing tools</link> print values of their arguments to the output
stream in some form of log statement. If arguments type does not support <code>operator<<(std::ostream&,
ArgumentType const&)</code> interface you will get a compilation error. You can either implement above
- interface or prohibit the <link linkend="utf.testing-tools">testing tools</link> from logging argument values for
+ interface or prohibit the <link linkend="utf.user-guide.testing-tools">testing tools</link> from logging argument values for
specified type. To do so use following statement on file level before first test case that includes statement
failing to compile:
</para>
@@ -473,7 +473,7 @@
</segmentedlist>
<para role="first-line-indented">
- Advanced <link linkend="utf.testing-tools">testing tools</link> may produce more complicated error messages.
+ Advanced <link linkend="utf.user-guide.testing-tools">testing tools</link> may produce more complicated error messages.
</para>
</section>
Added: trunk/libs/test/doc/src/utf.user-guide.test-runners.xml
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/utf.user-guide.test-runners.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
+ <!ENTITY utf "<acronym>UTF</acronym>">
+]>
+
+ <section id="utf.user-guide.test-runners">
+ <title>The supplied test runners … or where is the entrance?</title>
+ <titleabbrev>Supplied test runners</titleabbrev>
+
+ <para role="first-line-indented">
+ All usage variants of the &utf;, excluding the
+ <link linkend="utf.user-guide.external-test-runner">external test runner</link>, supply the test runner in a form of
+ free function named unit_test_main with the following signature:
+ </para>
+
+ <programlisting>int unit_test_main( init_unit_test_func init_func, int argc, char* argv[] );</programlisting>
+
+ <para role="first-line-indented">
+ To invoke the test runner you are required to supply the pointer to the <link linkend="test-module.def">test module</link>
+ initialization function as the first argument to the test runner function. In majority of the cases this function is
+ invoked directly from test executable entry point - function main(). In most usage variants the &utf; can
+ automatically generate default function main() implementation as either part of the library or test module itself.
+ Since the function main needs to refer to the initialization function by name, it is predefined by the default
+ implementation and you are required to match both specific signature and name, when implementing initialization
+ function. If you for any reason prefer more flexibility you can opt to implement the function main() yourself, in
+ which case it's going to be your responsibility to invoke the test runner, but the initialization function name is
+ not enforces the &utf;. See below for flags that needs to be defined/undefined in each usage variant to enable this.
+ </para>
+
+ <warning>
+ <simpara>
+ In spite syntactic similarity the signatures of the test runner function in fact are different for different usage
+ variants. The cause is different signature of the test module initialization function referred by the
+ <link linkend="utf.user-guide.initialization.signature-typedef">typedef init_unit_test_func</link>. This makes static
+ and dynamic library usage variants incompatible and they can't be easily switched on a fly.
+ </simpara>
+ </warning>
+
+ <section id="utf.user-guide.static-lib-runner">
+ <title>Static library variant of the &utf;</title>
+ <titleabbrev>Static library</titleabbrev>
+
+ <para role="first-line-indented">
+ By default this variant supplies the function main() as part of static library. If this is for any reason undesirable
+ you need to define the flag <xref linkend="utf.flag.no-main" endterm="utf.flag.no-main"/> during the library
+ compilation and the function main() implementation won't be generated.
+ </para>
+
+ <para role="first-line-indented">
+ In addition to the <link linkend="utf.user-guide.static-lib-variant">initialization function signature requirement</link>
+ default function main() implementation assumes the name of initialization function is init_unit_test_suite
+ </para>
+
+ </section>
+
+ <section id="utf.user-guide.dynamic-lib-runner">
+ <title>Dynamic library variant of the &utf;</title>
+ <titleabbrev>Dynamic library</titleabbrev>
+
+ <para role="first-line-indented">
+ Unlike the static library variant function main() can't reside in the dynamic library body. Instead this variant
+ supplies default function main() implementation as part of the header
+ <filename class="headerfile">boost/test/unit_test.hpp</filename> to be generated as part of your test file body.
+ The function main() is generated only if either the <xref linkend="utf.flag.main" endterm="utf.flag.main"/> or
+ the <xref linkend="utf.flag.module" endterm="utf.flag.module"/> flags are defined during a test module compilation.
+ For <link linkend="single-file-test-module.def">single-file test module</link> flags can be defined either in a
+ test module's makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
+ inclusion. For a <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/> flags can't
+ be defined in makefile and have to be defined in only one of the test files to avoid duplicate copies of the
+ function main().
+ </para>
+
+ <important>
+ <simpara>
+ The same flags also govern generation of an empty
+ <link linkend="utf.user-guide.initialization">test module initialization function</link>. This means that if you
+ need to implement either function main() or initialization function manually, you can't define the above flags
+ and are required to manually implement both of them.
+ </simpara>
+ </important>
+ </section>
+
+ <section id="utf.user-guide.single-header-runner">
+ <title>Single-header variant of the &utf;</title>
+ <titleabbrev>Single header</titleabbrev>
+
+ <para role="first-line-indented">
+ By default this variant supplies function main() as part of the header
+ <filename class="headerfile">boost/test/included/unit_test.hpp</filename> to be generated as part of your test file
+ body. If this is for any reason undesirable you need to define the flag
+ <xref linkend="utf.flag.no-main" endterm="utf.flag.no-main"/> during test module compilation and the function main()
+ implementation won't be generated.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.external-test-runner">
+ <title>External test runner variant of the &utf;</title>
+ <titleabbrev>External test runner</titleabbrev>
+
+ <para role="first-line-indented">
+ The external test runner variant of the &utf; supplies the test runner in a form of standalone utility
+ boost_test_runner. You are free to implement different, more advanced, test runners that can be used with this
+ variant.
+ </para>
+
+ <simpara>
+ <!-- TO FIX -->
+ </simpara>
+ </section>
+
+ <section id="utf.user-guide.runners-exit-status">
+ <title>Generated exit status values</title>
+
+ <para role="first-line-indented">
+ Once testing is finished, all supplied test runners report the results and returns an exit status value. Here are
+ the summary of all possible generated values:
+ </para>
+
+ <table id="utf.user-guide.runners-exit-status-summary">
+ <title>Generated exit status values</title>
+ <tgroup cols="2">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>boost::exit_success</entry>
+ <entry>
+ No errors occurred during the test or the success result code was explicitly requested with the no_result_code
+ parameter.
+ </entry>
+ </row>
+ <row>
+ <entry>boost::exit_test_failure</entry>
+ <entry>
+ Non-fatal errors detected and no uncaught exceptions were thrown during testing or the &utf; fails during
+ initialization.
+ </entry>
+ </row>
+ <row>
+ <entry>boost::exit_exception_failure</entry>
+ <entry>
+ Fatal errors were detected or uncaught exceptions thrown during testing.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
Added: trunk/libs/test/doc/src/utf.user-guide.testing-tools.xml
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/utf.user-guide.testing-tools.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,1168 @@
+<?xml version="1.0" encoding="utf-8" ?><!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
+ <!ENTITY utf "<acronym>UTF</acronym>">
+]>
+<section id="utf.user-guide.testing-tools" last-revision="$Date$">
+ <title>The &utf; testing tools … or tester's toolbox for all occasions</title>
+ <titleabbrev>Testing tools</titleabbrev>
+
+ <section id="utf.user-guide.testing-tools.intro">
+ <title>Introduction</title>
+
+ <para role="first-line-indented">
+ The &utf;'s supplies a toolbox of testing tools to ease creation and maintenance of test programs and
+ provide a uniform error reporting mechanism. The toolbox supplied in most part in a form of macro and function
+ declarations. While the functions can be called directly, the usual way to use testing tools is via convenience
+ macros. All macros arguments are calculated once, so it's safe to pass complex expressions in their place.
+ All tools automatically supply an error location: a file name and a line number. The testing tools are intended
+ for unit test code rather than library or production code, where throwing exceptions, using assert(),
+ <classname>boost::concept_check</classname> or <macroname>BOOST_STATIC_ASSERT</macroname>() may be more suitable
+ ways to detect and report errors. For list of all supplied testing tools and usage examples see the reference.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.testing-tools.flavors">
+ <title>Testing tools flavors</title>
+
+ <para role="first-line-indented">
+ All the tools are supplied in three flavors(levels): <firstterm>WARN</firstterm>, <firstterm>CHECK</firstterm> and
+ <firstterm>REQUIRE</firstterm>. For example: <macroname>BOOST_WARN_EQUAL</macroname>,
+ <macroname>BOOST_CHECK_EQUAL</macroname>, <macroname>BOOST_REQUIRE_EQUAL</macroname>. If an assertion designated by
+ the tool passes, confirmation message can be printed in log output<footnote><simpara>to manage what messages appear
+ in the test log stream set the proper <link linkend="utf.user-guide.test-output.log">log
+ level</link></simpara></footnote>. If an assertion designated by the tool failed, depending on the level following
+ will happened<footnote><simpara>in some cases log message can be slightly different to reflect failed tool
+ specifics</simpara></footnote>:
+ </para>
+
+ <table id="utf.user-guide.testing-tools.levels-diffs">
+ <title>Testing tools levels differences</title>
+
+ <tgroup cols="4">
+ <colspec colnum="1" colname="col1" />
+ <colspec colnum="2" colname="col2" />
+ <colspec colnum="3" colname="col3" />
+ <colspec colnum="4" colname="col4" />
+ <thead>
+ <row>
+ <entry>Level</entry>
+ <entry>Test log content</entry>
+ <entry>Errors counter</entry>
+ <entry>Test execution</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>WARN</entry>
+ <entry>
+ warning in <replaceable><test case name></replaceable>: condition
+ <replaceable><assertion description></replaceable> is not satisfied
+ </entry>
+ <entry>not affected</entry>
+ <entry>continues</entry>
+ </row>
+
+ <row>
+ <entry>CHECK</entry>
+ <entry>
+ error in <replaceable><test case name></replaceable>: test
+ <replaceable><assertion description></replaceable> failed
+ </entry>
+ <entry>increased</entry>
+ <entry>continues</entry>
+ </row>
+
+ <row>
+ <entry>REQUIRE</entry>
+ <entry>
+ fatal error in <replaceable><test case name></replaceable>: critical test
+ <replaceable><assertion description></replaceable> failed
+ </entry>
+ <entry>increased</entry>
+ <entry>aborts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para role="first-line-indented">
+ Regularly you should use CHECK level tools to implement your assertions. You can use WARN level tools to validate
+ aspects less important then correctness: performance, portability, usability etc. You should use REQUIRE level
+ tools only if continuation of the test case doesn't make sense if this assertions fails.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.testing-tools.output-test">
+ <title>Output testing tool</title>
+
+ <para role="first-line-indented">
+ How do you perform correctness test for <code>operator<<( <classname>std::ostream</classname>&, ... )</code>
+ 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 <classname>std::stringstream</classname> 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 <firstterm><classname>output_test_stream</classname></firstterm> is designed to
+ automate these tasks for you. This is a simple, but powerful tool for testing standard
+ <classname>std::ostream</classname> based output operation. The class <classname>output_test_stream</classname>
+ complies to <classname>std::ostream</classname> interface so it can be used in place of any
+ <classname>std::ostream</classname> 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.
+ </para>
+
+ <para role="first-line-indented">
+ All <classname>output_test_stream</classname> validation methods by default flush the stream once check is performed.
+ If you want to perform several checks with the same output, specify parameter <firstterm>flush_stream</firstterm>
+ with value false. This parameter is supported on all comparison methods.
+ </para>
+
+ <para role="first-line-indented">
+ 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
+ <classname>output_test_stream</classname> allows matching output content versus specified pattern file and produce
+ pattern file based on successful test run.
+ </para>
+
+ <para role="first-line-indented">
+ Detailed specification of class <classname>output_test_stream</classname> is covered in reference section.
+ </para>
+
+ <section id="utf.user-guide.testing-tools.output-test.usage">
+ <title>Usage</title>
+
+ <para role="first-line-indented">
+ There are two ways to employ the class <classname>output_test_stream</classname>: explicit output checks and
+ pattern file matching.
+ </para>
+ </section>
+
+ <btl-example name="example28">
+ <title>output_test_stream usage with explicit output checks</title>
+
+ <para role="first-line-indented">
+ Use the instance of class output_test_stream as an output stream and check output content using tool's methods.
+ Note use of <literal>false</literal> 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 serious of output operators followed by one check. And so on again. 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.
+ </para>
+ </btl-example>
+
+ <btl-example name="example29">
+ <title>output_test_stream usage for pattern file matching</title>
+
+ <para role="first-line-indented">
+ Even 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 repeated several
+ times. Try to perform checks as frequently as possible, because it allows you to more closely identify possible source
+ of failure. Content of the pattern file is:
+ </para>
+ <simpara>
+ <literallayout>i=2
+File: test.cpp Line: 14</literallayout>
+ </simpara>
+ </btl-example>
+ </section>
+
+ <section id="utf.user-guide.testing-tools.custom-predicate">
+ <title>Custom predicate support</title>
+
+ <para role="first-line-indented">
+ Even though supplied testing tools cover wide range of possible checks and provide detailed report on cause of error
+ in some cases you may want to implement and use custom predicate that perform complex check and produce intelligent
+ report on failure. To satisfy this need testing tools implement custom predicate support. There two layers of custom
+ predicate support implemented by testing tools toolbox: with and without custom error message generation.
+ </para>
+
+ <para role="first-line-indented">
+ The first layer is supported by BOOST_CHECK_PREDICATE family of testing tools. You can use it to check any custom
+ predicate that reports the result as boolean value. The values of the predicate arguments are reported by the tool
+ automatically in case of failure.
+ </para>
+
+ <btl-example name="example30">
+ <title>Custom predicate support using BOOST_CHECK_PREDICATE</title>
+ </btl-example>
+
+ <para role="first-line-indented">
+ To use second layer your predicate have to return
+ <classname>boost::test_tools::predicate_result</classname>. This class encapsulates boolean result value along
+ with any error or information message you opt to report.
+ </para>
+
+ <para role="first-line-indented">
+ Usually you construct the instance of class <classname>boost::test_tools::predicate_result</classname> inside your
+ predicate function and return it by value. The constructor expects one argument - the boolean result value. The
+ constructor is implicit, so you can simply return boolean value from your predicate and
+ <classname>boost::test_tools::predicate_result</classname> is constructed automatically to hold your value and empty
+ message. You can also assign boolean value to the constructed instance. You can check the current predicate value by
+ using <methodname>operator!</methodname>() or directly accessing public read-only property p_predicate_value. The
+ error message is stored in public read-write property p_message.
+ </para>
+
+ <btl-example name="example31">
+ <title>Custom predicate support using class predicate_result</title>
+ </btl-example>
+ </section>
+
+ <section id="utf.user-guide.testing-tools.fpv-comparison">
+ <title>Floating-point comparison algorithms</title>
+
+ <para role="first-line-indented">
+ In most cases it is unreasonable to use an <code>operator==(...)</code> for a floating-point values equality check.
+ The simple, absolute value comparison based, solution for a floating-point values <varname>u</varname>,
+ <varname>v</varname> and a tolerance &egr;:
+ </para>
+
+ <btl-equation index="1">
+ |<varname>u</varname> − <varname>v</varname>| ≤ &egr;
+ </btl-equation>
+
+ <simpara>
+ does not produce expected results in many circumstances - specifically for very small or very big values (See
+ <xref linkend="bbl.Squassabia"/> for examples). The &utf; implements floating-point comparison algorithm that is
+ based on the more confident solution first presented in <xref linkend="bbl.KnuthII"/>:
+ </simpara>
+
+ <btl-equation index="2">
+ |<varname>u</varname> − <varname>v</varname>| ≤ &egr; × |<varname>u</varname>| ∧ |<varname>u</varname> − <varname>v</varname>| ≤ &egr; × |<varname>v</varname>|
+ </btl-equation>
+
+ <simpara>
+ defines a <firstterm>very close with tolerance &egr;</firstterm> relationship between <varname>u</varname> and <varname>v</varname>
+ </simpara>
+
+ <btl-equation index="3">
+ |<varname>u</varname> − <varname>v</varname>| ≤ &egr; × |<varname>u</varname>| ∨ |<varname>u</varname> − <varname>v</varname>| ≤ &egr; × |<varname>v</varname>|
+ </btl-equation>
+
+ <simpara>
+ defines a <firstterm>close enough with tolerance &egr;</firstterm> relationship between <varname>u</varname> and <varname>v</varname>
+ </simpara>
+
+ <para role="first-line-indented">
+ Both relationships are commutative but are not transitive. The relationship defined by inequations
+ (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.2">2</ulink>) is stronger
+ that the relationship defined by inequations (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.3">3</ulink>)
+ (i.e. (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.2">2</ulink>) ⇒
+ (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.3">3</ulink>)). Because of the multiplication in the right side
+ of inequations, that can cause an unwanted underflow condition, the implementation is using modified version of the
+ inequations (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.2">2</ulink>) and
+ (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.3">3</ulink>) where all underflow, overflow conditions can be
+ guarded safely:
+ </para>
+
+ <btl-equation index="4">
+ |<varname>u</varname> − <varname>v</varname>| / |<varname>u</varname>| ≤ &egr; ∧ |<varname>u</varname> − <varname>v</varname>| / |<varname>v</varname>| ≤ &egr;
+ </btl-equation>
+
+ <btl-equation index="5">
+ |<varname>u</varname> − <varname>v</varname>| / |<varname>u</varname>| ≤ &egr; ∨ |<varname>u</varname> − <varname>v</varname>| / |<varname>v</varname>| ≤ &egr;
+ </btl-equation>
+
+ <para role="first-line-indented">
+ Checks based on equations (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.4">4</ulink>) and
+ (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.5">5</ulink>) are implemented by two predicates with
+ alternative interfaces: binary predicate <classname>close_at_tolerance</classname><footnote><simpara>check type
+ and tolerance value are fixed at predicate construction time</simpara></footnote> and predicate with four arguments
+ <classname>check_is_close</classname><footnote><simpara>check type and tolerance value are the arguments of the
+ predicate</simpara></footnote>.
+ </para>
+
+ <para role="first-line-indented">
+ While equations (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.4">4</ulink>) and
+ (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.5">5</ulink>) in general are preferred for the general floating
+ point comparison check over equation (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.1">1</ulink>), they are
+ unusable for the test on closeness to zero. The later check is still might be useful in some cases and the &utf;
+ implements an algorithm based on equation (<ulink linkend="utf.user-guide.testing-tools.fpv-comparison.eq.1">1</ulink>) in
+ binary predicate <classname>check_is_small</classname><footnote><simpara><varname>v</varname> is zero</simpara></footnote>.
+ </para>
+
+ <para role="first-line-indented">
+ On top of the generic, flexible predicates the &utf; implements macro based family of tools
+ <macroname>BOOST_CHECK_CLOSE</macroname> and <macroname>BOOST_CHECK_SMALL</macroname>. These tools limit the check
+ flexibility to strong-only checks, but automate failed check arguments reporting.
+ </para>
+
+ <section id="utf.user-guide.testing-tools.fpv-comparison.tolerance-selection">
+ <title>Tolerance selection considerations</title>
+
+ <para role="first-line-indented">
+ In case of absence of domain specific requirements the value of tolerance can be chosen as a sum of the predicted
+ upper limits for "relative rounding errors" of compared values. The "rounding" is the operation by which a real
+ value 'x' is represented in a floating-point format with 'p' binary digits (bits) as the floating-point value 'X'.
+ The "relative rounding error" is the difference between the real and the floating point values in relation to real
+ value: |x-X|/|x|. The discrepancy between real and floating point value may be caused by several reasons:
+ </para>
+
+ <itemizedlist>
+ <listitem><simpara>Type promotion</simpara></listitem>
+ <listitem><simpara>Arithmetic operations</simpara></listitem>
+ <listitem><simpara>Conversion from a decimal presentation to a binary presentation</simpara></listitem>
+ <listitem><simpara>Non-arithmetic operation</simpara></listitem>
+ </itemizedlist>
+
+ <para role="first-line-indented">
+ The first two operations proved to have a relative rounding error that does not exceed ½ ×
+ "machine epsilon value" for the appropriate floating point type (represented by
+ <classname>std::numeric_limits</classname><FPT>::epsilon()). Conversion to binary presentation, sadly, does
+ not have such requirement. So we can't assume that float 1.1 is close to real 1.1 with tolerance ½
+ × "machine epsilon value" for float (though for 11./10 we can). Non arithmetic operations either do not have a
+ predicted upper limit relative rounding errors. Note that both arithmetic and non-arithmetic operations might also
+ produce others "non-rounding" errors, such as underflow/overflow, division-by-zero or 'operation errors'.
+ </para>
+
+ <para role="first-line-indented">
+ All theorems about the upper limit of a rounding error, including that of ½ × epsilon, refer only to
+ the 'rounding' operation, nothing more. This means that the 'operation error', that is, the error incurred by the
+ operation itself, besides rounding, isn't considered. In order for numerical software to be able to actually
+ predict error bounds, the IEEE754 standard requires arithmetic operations to be 'correctly or exactly rounded'.
+ That is, it is required that the internal computation of a given operation be such that the floating point result
+ is the exact result rounded to the number of working bits. In other words, it is required that the computation used
+ by the operation itself doesn't introduce any additional errors. The IEEE754 standard does not require same behavior
+ from most non-arithmetic operation. The underflow/overflow and division-by-zero errors may cause rounding errors
+ with unpredictable upper limits.
+ </para>
+
+ <para role="first-line-indented">
+ At last be aware that ½ × epsilon rules are not transitive. In other words combination of two
+ arithmetic operations may produce rounding error that significantly exceeds 2 × ½ × epsilon. All
+ in all there are no generic rules on how to select the tolerance and users need to apply common sense and domain/
+ problem specific knowledge to decide on tolerance value.
+ </para>
+
+ <para role="first-line-indented">
+ To simplify things in most usage cases latest version of algorithm below opted to use percentage values for
+ tolerance specification (instead of fractions of related values). In other words now you use it to check that
+ difference between two values does not exceed x percent.
+ </para>
+
+ <para role="first-line-indented">
+ For more reading about floating-point comparison see references below.
+ </para>
+ </section>
+
+ <bibliography id="bbl.fpv-comparison">
+ <title>A floating-point comparison related references</title>
+
+ <bibliodiv id="bbl.fpv-comparison.books"><title>Books</title>
+
+ <biblioentry id="bbl.KnuthII">
+ <abbrev>KnuthII</abbrev>
+
+ <title>The art of computer programming (vol II)</title>
+ <author><firstname>Donald. E.</firstname><surname>Knuth</surname></author>
+ <copyright><year>1998</year><holder>Addison-Wesley Longman, Inc.</holder></copyright>
+ <isbn>0-201-89684-2</isbn>
+ <publisher><publishername>Addison-Wesley Professional; 3 edition</publishername></publisher>
+ </biblioentry>
+
+ <biblioentry id="bbl.Kulisch">
+ <abbrev>Kulisch</abbrev>
+
+ <biblioset relation="section">
+ <title>Rounding near zero</title>
+ </biblioset>
+ <biblioset relation="book">
+ <title><ulink url="http://www.amazon.com/Advanced-Arithmetic-Digital-Computer-Kulisch/dp/3211838708">Advanced Arithmetic for the Digital Computer</ulink></title>
+
+ <author><firstname>Ulrich W</firstname><surname>Kulisch</surname></author>
+ <copyright><year>2002</year><holder>Springer, Inc.</holder></copyright>
+ <isbn>0-201-89684-2</isbn>
+ <publisher><publishername>Springer; 1 edition</publishername></publisher>
+ </biblioset>
+ </biblioentry>
+
+ </bibliodiv>
+
+ <bibliodiv id="bbl.fpv-comparison.periodicals"><title>Periodicals</title>
+
+ <biblioentry id="bbl.Squassabia">
+ <abbrev>Squassabia</abbrev>
+
+ <title><ulink url="http://www.adtmag.com/joop/carticle.aspx?ID=396">Comparing Floats: How To Determine if Floating Quantities Are Close Enough Once a Tolerance Has Been Reached</ulink></title>
+ <author><firstname>Alberto</firstname><surname>Squassabia</surname></author>
+
+ <biblioset relation="journal">
+ <title>C++ Report</title>
+ <issuenum>March 2000</issuenum>.
+ </biblioset>
+ </biblioentry>
+
+ <biblioentry id="bbl.Becker">
+ <abbrev>Becker</abbrev>
+
+ <biblioset relation="article">
+ <title>The Journeyman's Shop: Trap Handlers, Sticky Bits, and Floating-Point Comparisons</title>
+ <author><firstname>Pete</firstname><surname>Becker</surname></author>
+ </biblioset>
+ <biblioset relation="journal">
+ <title>C/C++ Users Journal</title>
+ <issuenum>December 2000</issuenum>.
+ </biblioset>
+ </biblioentry>
+
+ </bibliodiv>
+
+ <bibliodiv id="bbl.fpv-comparison.publications"><title>Publications</title>
+
+ <biblioentry id="bbl.Goldberg">
+ <abbrev>Goldberg</abbrev>
+
+ <biblioset relation="article">
+ <title><ulink url="http://citeseer.ist.psu.edu/goldberg91what.html">What Every Computer Scientist Should Know About Floating-Point Arithmetic</ulink></title>
+ <author><firstname>David</firstname><surname>Goldberg</surname></author>
+ <copyright><year>1991</year><holder>Association for Computing Machinery, Inc.</holder></copyright>
+ <pagenums>150-230</pagenums>
+ </biblioset>
+ <biblioset relation="journal">
+ <title>Computing Surveys</title>
+ <issuenum>March</issuenum>.
+ </biblioset>
+ </biblioentry>
+
+ <biblioentry id="bbl.Langlois">
+ <abbrev>Langlois</abbrev>
+
+ <title><ulink url="http://www.inria.fr/rrrt/rr-3967.html">From Rounding Error Estimation to Automatic Correction with Automatic Differentiation</ulink></title>
+ <author><firstname>Philippe</firstname><surname>Langlois</surname></author>
+ <copyright><year>2000</year></copyright>
+ <issn>0249-6399</issn>
+ </biblioentry>
+
+ <biblioentry id="bbl.Kahan">
+ <abbrev>Kahan</abbrev>
+
+ <title><ulink url="http://www.cs.berkeley.edu/~wkahan/">Lots of information on William Kahan home page</ulink></title>
+ <author><firstname>William</firstname><surname>Kahan</surname></author>
+ </biblioentry>
+
+ </bibliodiv>
+ </bibliography>
+ </section>
+
+ <section id="utf.user-guide.testing-tools.reference">
+ <title>The &utf; testing tools reference</title>
+ <titleabbrev>Reference</titleabbrev>
+
+ <inline-reference id="utf.user-guide.testing-tools.reference.body">
+ <refentry name="BOOST_<level>">
+ <inline-synopsis>
+ <macro name="BOOST_WARN" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ </macro>
+ <macro name="BOOST_CHECK" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ </macro>
+ <macro name="BOOST_REQUIRE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to validate the predicate value. The only parameter for these tools is a boolean predicate
+ value that gets validated. It could be any expression that could be evaluated and converted to boolean value. The
+ expression gets evaluated only once, so it's safe to pass complex expression for validation.
+ </para>
+
+ <btl-example name="example34">
+ <title>BOOST_<level> usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_MESSAGE</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_BITWISE_EQUAL">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_BITWISE_EQUAL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_BITWISE_EQUAL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_BITWISE_EQUAL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to perform bitwise comparison of two values. The check shows all positions where left and
+ right value's bits mismatch.
+ </para>
+
+ <para role="first-line-indented">
+ The first parameter is the left compared value. The second parameter is the right compared value. Parameters are
+ not required to be of the same type, but warning is issued if their type's size does not coincide.
+ </para>
+
+ <btl-example name="example33">
+ <title>BOOST_<level>_BITWISE_EQUAL usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_EQUAL</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_CLOSE">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_CLOSE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ <macro name="BOOST_CHECK_CLOSE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_CLOSE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to check on closeness using strong relationship defined by the predicate
+ <functionname>check_is_close</functionname>( left, right, tolerance ). To check for the weak relationship use
+ <ref>BOOST_<level>_PREDICATE</ref> family of tools with explicit <functionname>check_is_close</functionname>
+ invocation.
+ </para>
+
+ <para>
+ The first parameter is the <emphasis>left</emphasis> compared value. The second parameter is the
+ <emphasis>right</emphasis> compared value. Last third parameter defines the tolerance for the comparison in
+ <link linkend="utf.user-guide.testing-tools.fpv-comparison.tolerance-selection"><emphasis role="bold">percentage units</emphasis></link>.
+ </para>
+
+ <note>
+ <simpara>
+ It is required for left and right parameters to be of the same floating point type. You will need to explicitly
+ resolve any type mismatch to select which type to use for comparison.
+ </simpara>
+ </note>
+
+ <note>
+ <simpara>
+ Note that to use these tools you need to include additional header floating_point_comparison.hpp.
+ </simpara>
+ </note>
+
+ <btl-example name="example42">
+ <title>BOOST_<level>_CLOSE usage with very small values</title>
+ </btl-example>
+
+ <btl-example name="example43">
+ <title>BOOST_<level>_CLOSE usage with very big values</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_CLOSE_FRACTION</ref>, <ref>BOOST_<level>_SMALL</ref>, <ref>BOOST_<level>_EQUAL</ref>,
+ <link linkend="utf.user-guide.testing-tools.fpv-comparison">Floating point comparison algorithms</link>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_CLOSE_FRACTION">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_CLOSE_FRACTION" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ <macro name="BOOST_CHECK_CLOSE_FRACTION" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_CLOSE_FRACTION" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to check on closeness using strong relationship defined by the predicate
+ <functionname>check_is_close</functionname>( left, right, tolerance ). To check for the weak relationship use
+ <ref>BOOST_<level>_PREDICATE</ref> family of tools with explicit <functionname>check_is_close</functionname>
+ invocation.
+ </para>
+
+ <para>
+ The first parameter is the <emphasis>left</emphasis> compared value. The second parameter is the
+ <emphasis>right</emphasis> compared value. Last third parameter defines the tolerance for the comparison as
+ <link linkend="utf.user-guide.testing-tools.fpv-comparison.tolerance-selection"><emphasis role="bold">fraction of absolute
+ values being compared</emphasis></link>.
+ </para>
+
+ <note>
+ <simpara>
+ It is required for left and right parameters to be of the same floating point type. You will need to explicitly
+ resolve any type mismatch to select which type to use for comparison.
+ </simpara>
+ </note>
+
+ <note>
+ <simpara>
+ Note that to use these tools you need to include additional header floating_point_comparison.hpp.
+ </simpara>
+ </note>
+
+ <btl-example name="example44">
+ <title>BOOST_<level>_CLOSE_FRACTION usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_CLOSE</ref>, <ref>BOOST_<level>_SMALL</ref>, <ref>BOOST_<level>_EQUAL</ref>,
+ <link linkend="utf.user-guide.testing-tools.fpv-comparison">Floating point comparison algorithms</link>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_EQUAL">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_EQUAL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_EQUAL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_EQUAL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Check performed by these tools is the same as the one performed by <ref>BOOST_<level></ref>( left == right ).
+ The difference is that the mismatched values are reported as well.
+ </para>
+
+ <note>
+ <simpara>
+ It is bad idea to use these tools to compare floating point values. Use <ref>BOOST_<level>_CLOSE</ref> or
+ <ref>BOOST_<level>_CLOSE_FRACTION</ref> tools instead.
+ </simpara>
+ </note>
+
+ <btl-example name="example35">
+ <title>BOOST_<level>_EQUAL usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level></ref>, <ref>BOOST_<level>_CLOSE</ref>, <ref>BOOST_<level>_NE</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_EQUAL_COLLECTIONS">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_EQUAL_COLLECTIONS" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left_begin"/>
+ <macro-parameter name="left_end"/>
+ <macro-parameter name="right_begin"/>
+ <macro-parameter name="right_end"/>
+ </macro>
+ <macro name="BOOST_CHECK_EQUAL_COLLECTIONS" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left_begin"/>
+ <macro-parameter name="left_end"/>
+ <macro-parameter name="right_begin"/>
+ <macro-parameter name="right_end"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_EQUAL_COLLECTIONS" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left_begin"/>
+ <macro-parameter name="left_end"/>
+ <macro-parameter name="right_begin"/>
+ <macro-parameter name="right_end"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to perform an element by element comparison of two collections. They print all mismatched
+ positions, collection elements at these positions and check that the collections have the same size. The first two
+ parameters designate begin and end of the first collection. The two parameters designate begin and end of the
+ second collection.
+ </para>
+
+ <btl-example name="example36">
+ <title>BOOST_<level>_EQUAL_COLLECTIONS usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_EQUAL</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_EXCEPTION">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_EXCEPTION" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ <macro-parameter name="exception"/>
+ <macro-parameter name="predicate"/>
+ </macro>
+ <macro name="BOOST_CHECK_EXCEPTION" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ <macro-parameter name="exception"/>
+ <macro-parameter name="predicate"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_EXCEPTION" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ <macro-parameter name="exception"/>
+ <macro-parameter name="predicate"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to perform an exception detection and validation check. Tools execute the supplied expression
+ and validate that it throws an exception of supplied class (or the one derived from it) that complies with the
+ supplied predicate. If the expression throws any other unrelated exception, doesn't throw at all or
+ predicate evaluates to false, check fails. In comparison with <ref>BOOST_<level>_THROW</ref> tools these
+ allow performing more fine-grained checks. For example: make sure that an expected exception has specific
+ error message.
+ </para>
+
+ <btl-example name="example37">
+ <title>BOOST_<level>_EXCEPTION usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_THROW</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_GE">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_GE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_GE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_GE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Check performed by these tools is the same as the one performed by <ref>BOOST_<level></ref>( left >= right ).
+ The difference is that the argument values are reported as well.
+ </para>
+
+ <btl-example name="example57">
+ <title>BOOST_<level>_GE usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_LE</ref>, <ref>BOOST_<level>_LT</ref>, <ref>BOOST_<level>_GT</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_GT">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_GT" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_GT" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_GT" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Check performed by these tools is the same as the one performed by <ref>BOOST_<level></ref>( left > right ).
+ The difference is that the argument values are reported as well.
+ </para>
+
+ <btl-example name="example58">
+ <title>BOOST_<level>_GT usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_LE</ref>, <ref>BOOST_<level>_LT</ref>, <ref>BOOST_<level>_GE</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_LE">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_LE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_LE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_LE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Check performed by these tools is the same as the one performed by <ref>BOOST_<level></ref>( left <= right ).
+ The difference is that the argument values are reported as well.
+ </para>
+
+ <btl-example name="example55">
+ <title>BOOST_<level>_LE usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_LT</ref>, <ref>BOOST_<level>_GE</ref>, <ref>BOOST_<level>_GT</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_LT">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_LT" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_LT" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_LT" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Check performed by these tools is the same as the one performed by <ref>BOOST_<level></ref>( left < right ).
+ The difference is that the argument values are reported as well.
+ </para>
+
+ <btl-example name="example56">
+ <title>BOOST_<level>_LT usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_LE</ref>, <ref>BOOST_<level>_GE</ref>, <ref>BOOST_<level>_GT</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_MESSAGE">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_MESSAGE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ <macro-parameter name="message"/>
+ </macro>
+ <macro name="BOOST_CHECK_MESSAGE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ <macro-parameter name="message"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_MESSAGE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ <macro-parameter name="message"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools perform exactly the same check as <ref>BOOST_<level></ref> tools. The only difference is that
+ instead of generating an error/confirm message these use the supplied one.
+ </para>
+
+ <para>
+ The first parameter is the boolean expression. The second parameter is the message reported in case of check
+ failure. The message argument can be constructed of components of any type supporting the
+ <code>std::ostream& operator<<(std::ostream&)</code>.
+ </para>
+
+ <btl-example name="example38">
+ <title>BOOST_<level>_MESSAGE usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level></ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_NE">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_NE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_CHECK_NE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_NE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="left"/>
+ <macro-parameter name="right"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Check performed by these tools is the same as the one performed by <ref>BOOST_<level></ref>( left != right ).
+ The difference is that the matched values are reported as well.
+ </para>
+
+ <btl-example name="example54">
+ <title>BOOST_<level>_NE usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_EQUAL</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_NO_THROW">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_NO_THROW" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ </macro>
+ <macro name="BOOST_CHECK_NO_THROW" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_NO_THROW" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to perform a "no throw" check. Tools execute the supplied expression and validate that it does
+ not throw any exceptions. Error would be reported by the framework even if the statement appear directly in test
+ case body and throw any exception. But these tools allow proceeding further with test case in case of failure.
+ </para>
+
+ <para>
+ If check is successful, tools may produce a confirmation message, in other case they produce an error message in
+ a form "error in <test case name>exception was thrown by <expression>.
+ </para>
+
+ <para>
+ The only parameter is an expression to execute. You can use do-while(0) block if you want to execute more than one
+ statement.
+ </para>
+
+ <btl-example name="example39">
+ <title>BOOST_<level>_NO_THROW usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_THROW</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_PREDICATE">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_PREDICATE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ <macro-parameter name="arguments_list"/>
+ </macro>
+ <macro name="BOOST_CHECK_PREDICATE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ <macro-parameter name="arguments_list"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_PREDICATE" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="predicate"/>
+ <macro-parameter name="arguments_list"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These are generic tools used to validate an arbitrary supplied predicate functor (there is a compile time limit on
+ predicate arity defined by the configurable macro <macroname>BOOST_TEST_MAX_PREDICATE_ARITY</macroname>). To
+ validate zero arity predicate use <ref>BOOST_<level></ref> tools. In other cases prefer theses tools. The
+ advantage of these tools is that they show arguments values in case of predicate failure.
+ </para>
+
+ <para>
+ The first parameter is the predicate itself. The second parameter is the list of predicate arguments each wrapped
+ in round brackets (BOOST_PP sequence format).
+ </para>
+
+ <btl-example name="example40">
+ <simpara>
+ Note difference in error log from
+ </simpara>
+ <title>BOOST_<level>_PREDICATE usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level></ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_SMALL">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_SMALL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="value"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ <macro name="BOOST_CHECK_SMALL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="value"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_SMALL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="value"/>
+ <macro-parameter name="tolerance"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to check that supplied value is small enough. The "smallness" is defined by absolute value
+ of the tolerance supplied as a second argument. Use these tools with caution. To compare to values on closeness
+ it's preferable to use <ref>BOOST_<level>_CLOSE</ref> tools instead.
+ </para>
+
+ <para role="first-line-indented">
+ The first parameter is the value to check. The second parameter is the tolerance.
+ </para>
+
+ <note>
+ <simpara>
+ Note that to use these tools you need to include additional header floating_point_comparison.hpp.
+ </simpara>
+ </note>
+
+ <btl-example name="example41">
+ <title>BOOST_<level>_SMALL usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>_CLOSE</ref>, <ref>BOOST_<level>_CLOSE_FRACTION</ref>,
+ <link linkend="utf.user-guide.testing-tools.fpv-comparison">Floating point comparison algorithms</link>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_<level>_THROW">
+ <inline-synopsis>
+ <macro name="BOOST_WARN_THROW" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ <macro-parameter name="exception"/>
+ </macro>
+ <macro name="BOOST_CHECK_THROW" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ <macro-parameter name="exception"/>
+ </macro>
+ <macro name="BOOST_REQUIRE_THROW" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="expression"/>
+ <macro-parameter name="exception"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ These tools are used to perform an exception detection check. Tools execute the supplied expression and validate
+ that it throws an exception of supplied class (or the one derived from it) or it's child. If the statement
+ throws any other unrelated exception or doesn't throw at all, check fails.
+ </para>
+
+ <para>
+ If check is successful, the tool produces a confirmation message, in other case it produces an error message in a
+ form "error in <replaceable>test case name</replaceable>: exception <replaceable>exception</replaceable> expected.
+ </para>
+
+ <para role="first-line-indented">
+ The first parameter is the expression to execute. Use do-while(0) block if you want to execute more than one
+ statement. The second parameter is an expected exception.
+ </para>
+
+ <btl-example name="example45">
+ <title>BOOST_<level>_THROW usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level>NO_THROW</ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_ERROR">
+ <inline-synopsis>
+ <macro name="BOOST_ERROR" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="message"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ BOOST_ERROR tool behave the same way as <code>BOOST_CHECK_MESSAGE( false, message )</code>. This tool is used for
+ an unconditional error counter increasing and message logging.
+ </para>
+
+ <para>
+ The only tool's parameter is an error message to log.
+ </para>
+
+ <btl-example name="example46">
+ <title>BOOST_ERROR usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level></ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_FAIL">
+ <inline-synopsis>
+ <macro name="BOOST_FAIL" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="message"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ BOOST_FAIL behave the same way as <code>BOOST_REQUIRE_MESSAGE( false, message )</code>. This tool is used for an
+ unconditional error counter increasing, message logging and the current test case aborting.
+ </para>
+
+ <para>
+ The only tool's parameter is an error message to log.
+ </para>
+
+ <btl-example name="example47">
+ <title>BOOST_FAIL usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level></ref>
+ </seealso>
+ </refentry>
+
+ <refentry name="BOOST_IS_DEFINED">
+ <inline-synopsis>
+ <macro name="BOOST_IS_DEFINED" kind="functionlike" ref-id="utf.user-guide.testing-tools.reference">
+ <macro-parameter name="symbol"/>
+ </macro>
+ </inline-synopsis>
+
+ <para role="first-line-indented">
+ Unlike the rest of the tools in the toolbox this tool does not perform the logging itself. Its only purpose
+ is to check at runtime whether or not the supplied preprocessor symbol is defined. Use it in combination with
+ <ref>BOOST_<level></ref> to perform and log validation. Macros of any arity could be checked. To check the
+ macro definition with non-zero arity specify dummy arguments for it. See below for example.
+ </para>
+
+ <para>
+ The only tool's parameter is a preprocessor symbol that gets validated.
+ </para>
+
+ <btl-example name="example48">
+ <title>BOOST_IS_DEFINED usage</title>
+ </btl-example>
+
+ <seealso>
+ <ref>BOOST_<level></ref>
+ </seealso>
+ </refentry>
+
+ </inline-reference>
+
+ </section>
+</section>
Added: trunk/libs/test/doc/src/utf.user-guide.usage-variants.xml
==============================================================================
--- (empty file)
+++ trunk/libs/test/doc/src/utf.user-guide.usage-variants.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
+ <!ENTITY utf "<acronym>UTF</acronym>">
+]>
+ <section id="utf.user-guide.usage-variants">
+ <title>The &utf; usage variants … or the <ulink url="http://en.wikipedia.org/wiki/Buridan's_ass">Buridan's donkey</ulink> parable</title>
+ <titleabbrev>Usage variants</titleabbrev>
+
+ <para role="first-line-indented">
+ The &utf; presents you with 4 different variants how it can be used.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <simpara><link linkend="utf.user-guide.static-lib-variant">The static library variant</link></simpara>
+ </listitem>
+ <listitem>
+ <simpara><link linkend="utf.user-guide.dynamic-lib-variant">The dynamic library variant</link></simpara>
+ </listitem>
+ <listitem>
+ <simpara><link linkend="utf.user-guide.single-header-variant">The single-header variant</link></simpara>
+ </listitem>
+ <listitem>
+ <simpara><link linkend="utf.user-guide.extern-test-runner-variant">The external test runner variant</link></simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para role="first-line-indented">
+ Unlike the Buridan's donkey though, you shouldn't have problems deciding which one to use, since there are
+ clear reasons why would you prefer each one.
+ </para>
+
+ <para role="first-line-indented">
+ In most cases to compile a test module based on the &utf; all you need to include is just the single header
+ <filename class="headerfile">boost/test/unit_test.hpp</filename>. This header includes internally most of the other
+ headers that contains the &utf; definitions. Some advanced features, like the floating point comparison or the
+ logged expectations testing, are defined in independent headers and need to be included explicitly.
+ </para>
+
+ <section id="utf.user-guide.static-lib-variant">
+ <title>The static library variant of the &utf;</title><titleabbrev>Static library</titleabbrev>
+ <para role="first-line-indented">
+ The &utf; can be built into a static library. If you opt to link a test module with the
+ <link linkend="utf.compilation.standalone">standalone static library</link>, this usage is called the static library
+ variant of the &utf;.
+ </para>
+
+ <para role="first-line-indented">
+ The test runner supplied with this variant required you to implement the <link linkend="test-module.def">test
+ module</link> initialization function that matches one of the two specifications depending on the compilation flag
+ <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required
+ to match the original specification. If you define the flag <xref linkend="utf.flag.alt-init-api"
+ endterm="utf.flag.alt-init-api"/> during a test module compilation you are required to use the alternative
+ initialization function specification. The &utf; provides an ability to
+ <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
+ initialization function with correct specification if no custom initialization is required by a test module.
+ </para>
+
+ <important>
+ <simpara>
+ If you opted to use an alternative initialization API, for a test module to be able to link with prebuilt library,
+ the flag <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> has to be defined both during
+ library and a test module compilation.
+ </simpara>
+ </important>
+ </section>
+
+ <section id="utf.user-guide.dynamic-lib-variant">
+ <title>The dynamic library variant of the &utf;</title>
+ <titleabbrev>Dynamic library</titleabbrev>
+
+ <para role="first-line-indented">
+ In the project with large number of test modules <link linkend="utf.user-guide.dynamic-lib-variant">the static
+ library</link> variant of the &utf; may cause you to waste a lot of disk space, since the &utf; is linked
+ statically with every test module. The solution is to link with the &utf; built into a dynamic library. If you opt
+ to link a test module with the prebuilt dynamic library, this usage is called the dynamic library variant of the
+ &utf;. This variant requires you to define the flag <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/>
+ either in a makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
+ inclusion.
+ </para>
+
+ <para role="first-line-indented">
+ The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
+ module</link> initialization function that matches the alternative initialization function signature. The &utf;
+ provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link>
+ an empty test module initialization function with correct signature if no custom initialization is required by a
+ test module.
+ </para>
+
+ <note>
+ <simpara>
+ The name of the test module initialization function is not enforced, since the function is passed as an argument
+ to the test runner.
+ </simpara>
+ </note>
+ </section>
+
+ <section id="utf.user-guide.single-header-variant">
+ <title>The single-header variant of the &utf;</title>
+ <titleabbrev>Single header</titleabbrev>
+
+ <para role="first-line-indented">
+ If you prefer to avoid the <link linkend="utf.compilation.standalone">standalone library compilation</link>, you
+ should use the single-header variant of the &utf;. This variant is implemented, as it follows from its name, in
+ the single header <filename class="headerfile">boost/test/included/unit_test.hpp</filename>. An inclusion of
+ the header causes the complete implementation of the &utf; to be included as a part of a test module's
+ source file. The header <filename class="headerfile">boost/test/unit_test.hpp</filename> doesn't have to be
+ included anymore. You don't have to worry about disabling <link linkend="utf.compilation.auto-linking">
+ auto-linking</link> feature either. It's done in the implementation header already. This variant
+ can't be used with the <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/>.
+ Otherwise it's almost identical from the usage prospective to the static library variant of the &utf;.
+ In fact the only difference is the name of the include file:
+ <filename class="headerfile">boost/test/included/unit_test.hpp</filename> instead of
+ <filename class="headerfile">boost/test/unit_test.hpp</filename>.
+ </para>
+
+ <para role="first-line-indented">
+ The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
+ module</link> initialization function that matches one of the two specifications depending on the compilation flag
+ <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required to
+ match the original specification. If you define the flag
+ <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> during a test module compilation you are
+ required to use the alternative initialization function specification. The &utf; provides an ability to
+ <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
+ initialization function with correct specification if no custom initialization is required by a test module.
+ </para>
+ </section>
+
+ <section id="utf.user-guide.extern-test-runner-variant">
+ <title>The external test runner variant of the &utf;</title>
+ <titleabbrev>External test runner</titleabbrev>
+
+ <para role="first-line-indented">
+ All other usage variants employ the build-in test runners. If you plan to use an external test runner with your
+ test module you need to build it as a dynamic library. This usage of the &utf; is called the external test runner
+ variant of the &utf;. The variant requires you to define the flag
+ <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/> either in a makefile or before the header
+ <filename class="headerfile">boost/test/unit_test.hpp</filename> inclusion. An external test runner utility is
+ required to link with dynamic library.
+ </para>
+
+ <para role="first-line-indented">
+ If an external test runner is based on the test runner built in to the dynamic library (like the standalone
+ boost_test_runner utility supplied by the &utf;), it requires you to implement the <link linkend="test-module.def">
+ test module</link> initialization function that matches the alternative initialization function signature. The
+ &utf; provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate
+ </link> an empty test module initialization function with correct signature if no custom initialization is required
+ by a test module.
+ </para>
+
+ <note>
+ <simpara>
+ An advanced test runner doesn't have to be based on the build-in one and may require a different
+ test module initialization function signature and/or name.
+ </simpara>
+ </note>
+ </section>
+ </section>
Copied: trunk/libs/test/doc/src/utf.user-guide.xml (from r73722, /trunk/libs/test/doc/src/utf.users-guide.xml)
==============================================================================
--- /trunk/libs/test/doc/src/utf.users-guide.xml (original)
+++ trunk/libs/test/doc/src/utf.user-guide.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -6,693 +6,63 @@
<title>Unit Test Framework: User's guide</title><titleabbrev>User's guide</titleabbrev>
<section id="utf.user-guide.intro">
- <title>Introduction … or what's your name?</title><titleabbrev>Introduction</titleabbrev>
+ <title>Introduction … or where to start?</title><titleabbrev>Introduction</titleabbrev>
<para role="first-line-indented">
- Without further ado, let's define terms regularly used by the &utf;.
+ Without further ado, I'd like to start … but where? It's not obvious what is the best order to describe the framework.
+ One can use bottom up approach, starting with with basics and going up to cover real interfaces based on them. The downside is
+ that you'll have to dig through the multiple pages of information you may not never need in real life. One can follow the order
+ of test program execution. From test initialization to test tree construction to the report and log generation. This also
+ unfortunately may not be most clear way. The Boost.Test &utf; is very flexible and a lot of details of various test initialization
+ options may not necessarily important for average user, while understanding test output is.
</para>
- <variablelist>
- <?dbhtml term-width="16%" list-width="100%"?>
- <?dbhtml term-separator=":"?>
- <?dbhtml table-summary="utf terms definition"?>
-
- <varlistentry id="test-module.def">
- <term><firstterm>The test module</firstterm></term>
- <listitem>
- <simpara>
- This is a single binary that performs the test. Physically a test module consists of one or more test source files,
- which can be built into an executable or a dynamic library. A test module that consists of a single test source
- file is called <firstterm id="single-file-test-module.def">single-file test module</firstterm>. Otherwise
- it's called <firstterm id="multi-file-test-module.def">multi-file test module</firstterm>. Logically a test
- module consists of four parts: <link linkend="test-setup.def">test setup</link> (or test initialization),
- <link linkend="test-body.def">test body</link>, <link linkend="test-cleanup.def">test cleanup</link> and
- <link linkend="test-runner.def">test runner</link>. The test runner part is optional. If a test module is built as
- an executable the test runner is built-in. If a test module is built as a dynamic library, it is run by an
- external test runner.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-body.def">
- <term><firstterm>The test body</firstterm></term>
- <listitem>
- <simpara>
- This is the part of a test module that actually performs the test.
- Logically test body is a collection of <link linkend="test-assertion.def">test assertions</link> wrapped in
- <link linkend="test-case.def">test cases</link>, which are organized in a <link linkend="test-tree.def">test tree
- </link>.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-tree.def">
- <term><firstterm>The test tree</firstterm></term>
- <listitem>
- <simpara>
- This is a hierarchical structure of <link linkend="test-suite.def">test suites</link> (non-leaf nodes) and
- <link linkend="test-case.def">test cases</link> (leaf nodes).
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-unit.def">
- <term><firstterm>The test unit</firstterm></term>
- <listitem>
- <simpara>
- This is a collective name when referred to either <link linkend="test-suite.def">test suite</link> or
- <link linkend="test-case.def">test case</link>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-assertion.def">
- <term><firstterm>Test assertion</firstterm></term>
- <listitem>
- <simpara>
- This is a single binary condition (binary in a sense that is has two outcomes: pass and fail) checked
- by a test module.
- </simpara>
- <simpara>
- There are different schools of thought on how many test assertions a test case should consist of. Two polar
- positions are the one advocated by TDD followers - one assertion per test case; and opposite of this - all test
- assertions within single test case - advocated by those only interested in the first error in a
- test module. The &utf; supports both approaches.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-case.def">
- <term><firstterm>The test case</firstterm></term>
- <listitem>
- <simpara>
- This is an independently monitored function within a test module that
- consists of one or more test assertions. The term "independently monitored" in the definition above is
- used to emphasize the fact, that all test cases are monitored independently. An uncaught exception or other normal
- test case execution termination doesn't cause the testing to cease. Instead the error is caught by the test
- case execution monitor, reported by the &utf; and testing proceeds to the next test case. Later on you are going
- to see that this is on of the primary reasons to prefer multiple small test cases to a single big test function.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-suite.def">
- <term><firstterm>The test suite</firstterm></term>
- <listitem>
- <simpara>
- This is a container for one or more test cases. The test suite gives you an ability to group
- test cases into a single referable entity. There are various reasons why you may opt to do so, including:
- </simpara>
- <itemizedlist>
- <listitem>
- <simpara>To group test cases per subsystems of the unit being tested.</simpara>
- </listitem>
- <listitem>
- <simpara>To share test case setup/cleanup code.</simpara>
- </listitem>
- <listitem>
- <simpara>To run selected group of test cases only.</simpara>
- </listitem>
- <listitem>
- <simpara>To see test report split by groups of test cases</simpara>
- </listitem>
- <listitem>
- <simpara>To skip groups of test cases based on the result of another test unit in a test tree.</simpara>
- </listitem>
- </itemizedlist>
- <simpara>
- A test suite can also contain other test suites, thus allowing a hierarchical test tree structure to be formed.
- The &utf; requires the test tree to contain at least one test suite with at least one test case. The top level
- test suite - root node of the test tree - is called the master test suite.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-setup.def">
- <term><firstterm>The test setup</firstterm></term>
- <listitem>
- <simpara>
- This is the part of a test module that is responsible for the test
- preparation. It includes the following operations that take place prior to a start of the test:
- </simpara>
- <itemizedlist>
- <listitem>
- <simpara>
- The &utf; initialization
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Test tree construction
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Global test module setup code
- </simpara>
- </listitem>
- </itemizedlist>
- <simpara>
- Per test case" setup code, invoked for every test case it's assigned to, is also attributed to the
- test initialization, even though it's executed as a part of the test case.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-cleanup.def">
- <term><firstterm>The test cleanup</firstterm></term>
- <listitem>
- <simpara>
- This is the part of test module that is responsible for cleanup operations.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-fixture.def">
- <term><firstterm>The test fixture</firstterm></term>
- <listitem>
- <simpara>
- Matching setup and cleanup operations are frequently united into a single entity called test fixture.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-runner.def">
- <term><firstterm>The test runner</firstterm></term>
- <listitem>
- <simpara>
- This is an "executive manager" that runs the show. The test runner's functionality should include
- the following interfaces and operations:
- </simpara>
- <itemizedlist>
- <listitem>
- <simpara>
- Entry point to a test module. This is usually either the function main() itself or single function that can be
- invoked from it to start testing.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Initialize the &utf; based on runtime parameters
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Select an output media for the test log and the test results report
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Select test cases to execute based on runtime parameters
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Execute all or selected test cases
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Produce the test results report
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Generate a test module result code.
- </simpara>
- </listitem>
- </itemizedlist>
- <para role="first-line-indented">
- An advanced test runner may provide additional features, including interactive <acronym>GUI</acronym> interfaces,
- test coverage and profiling support.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="test-log.def">
- <term><firstterm>The test log</firstterm></term>
- <listitem>
- <simpara>
- This is the record of all events that occur during the testing.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-results-report.def">
- <term><firstterm>The test results report</firstterm></term>
- <listitem>
- <simpara>
- This is the report produced by the &utf; after the testing is completed, that indicates which test cases/test
- suites passed and which failed.
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist >
- </section>
-
- <section id="utf.user-guide.usage-variants">
- <title>The &utf; usage variants … or the <ulink url="http://en.wikipedia.org/wiki/Buridan's_ass">Buridan's donkey</ulink> parable</title>
- <titleabbrev>Usage variants</titleabbrev>
-
<para role="first-line-indented">
- The &utf; presents you with 4 different variants how it can be used.
+ Well … This is a User's Guide after all. Let's go by what <emphasis role="bold">you</emphasis> need to know to successfully use the &utf;. Thus I follow
+ the order of decisions you as a user have to make and order of complexity of the problems you have to solve. If you find yourself
+ faces with some unclear term feel free to jump directly to the <link linkend="utf.user-guide.glossary">Glossary</link> section,
+ where I collection short definition for all used terms. And again if you want to jump right into coding the
+ <link linkend="utf.tutorials">Tutorials</link> section would be a better place to start.
</para>
-
- <itemizedlist>
- <listitem>
- <simpara><link linkend="utf.user-guide.static-lib-variant">The static library variant</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.dynamic-lib-variant">The dynamic library variant</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.single-header-variant">The single-header variant</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.extern-test-runner-variant">The external test runner variant</link></simpara>
- </listitem>
- </itemizedlist>
-
<para role="first-line-indented">
- Unlike the Buridan's donkey though, you shouldn't have problems deciding which one to use, since there are
- clear reasons why would you prefer each one.
+ The &utf; has several usage variants. And the first decision you have to make is which one to use. These variants are covered in
+ section dedicated to <link linkend="utf.user-guide.usage-variants">Usage variants</link>. The next step, probably the most important
+ for you, is to start writing test cases, bind them in test suites and implement your checks. First two topics are coverred in
+ <link linkend="utf.user-guide.test-organization">Test organization</link> section, while
+ <link linkend="utf.user-guide.testing-tools">Testing tools</link> section arms you with rich set of tools enough to implement
+ almost arbitrary check you need.
</para>
-
<para role="first-line-indented">
- In most cases to compile a test module based on the &utf; all you need to include is just the single header
- <filename class="headerfile">boost/test/unit_test.hpp</filename>. This header includes internally most of the other
- headers that contains the &utf; definitions. Some advanced features, like the floating point comparison or the
- logged expectations testing, are defined in independent headers and need to be included explicitly.
+ Next you'll learn how to understand and manipulate the &utf; output in a <link linkend="utf.user-guide.test-output">Test output</link>
+ section. At that point you should be able to build and run most simple test modules and almost inevitable find a need to configure
+ how the test module is executed. Whether you want to change output format, select which test case to run or run test cases in random order
+ these and may other runtime configuration parameters are discribed in <link linkend="utf.user-guide.runtime-config">Runtime configuration</link>
+ section.
</para>
-
- <section id="utf.user-guide.static-lib-variant">
- <title>The static library variant of the &utf;</title><titleabbrev>Static library</titleabbrev>
- <para role="first-line-indented">
- The &utf; can be built into a static library. If you opt to link a test module with the
- <link linkend="utf.compilation.standalone">standalone static library</link>, this usage is called the static library
- variant of the &utf;.
- </para>
-
- <para role="first-line-indented">
- The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
- module</link> initialization function that matches one of the two specifications depending on the compilation flag
- <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required
- to match the original specification. If you define the flag <xref linkend="utf.flag.alt-init-api"
- endterm="utf.flag.alt-init-api"/> during a test module compilation you are required to use the alternative
- initialization function specification. The &utf; provides an ability to
- <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
- initialization function with correct specification if no custom initialization is required by a test module.
- </para>
-
- <important>
- <simpara>
- If you opted to use an alternative initialization API, for a test module to be able to link with prebuilt library,
- the flag <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> has to be defined both during
- library and a test module compilation.
- </simpara>
- </important>
- </section>
-
- <section id="utf.user-guide.dynamic-lib-variant">
- <title>The dynamic library variant of the &utf;</title>
- <titleabbrev>Dynamic library</titleabbrev>
-
- <para role="first-line-indented">
- In the project with large number of test modules <link linkend="utf.user-guide.dynamic-lib-variant">the static
- library</link> variant of the &utf; may cause you to waste a lot of disk space, since the &utf; is linked
- statically with every test module. The solution is to link with the &utf; built into a dynamic library. If you opt
- to link a test module with the prebuilt dynamic library, this usage is called the dynamic library variant of the
- &utf;. This variant requires you to define the flag <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/>
- either in a makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
- inclusion.
- </para>
-
- <para role="first-line-indented">
- The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
- module</link> initialization function that matches the alternative initialization function signature. The &utf;
- provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link>
- an empty test module initialization function with correct signature if no custom initialization is required by a
- test module.
- </para>
-
- <note>
- <simpara>
- The name of the test module initialization function is not enforced, since the function is passed as an argument
- to the test runner.
- </simpara>
- </note>
- </section>
-
- <section id="utf.user-guide.single-header-variant">
- <title>The single-header variant of the &utf;</title>
- <titleabbrev>Single header</titleabbrev>
-
- <para role="first-line-indented">
- If you prefer to avoid the <link linkend="utf.compilation.standalone">standalone library compilation</link>, you
- should use the single-header variant of the &utf;. This variant is implemented, as it follows from its name, in
- the single header <filename class="headerfile">boost/test/included/unit_test.hpp</filename>. An inclusion of
- the header causes the complete implementation of the &utf; to be included as a part of a test module's
- source file. The header <filename class="headerfile">boost/test/unit_test.hpp</filename> doesn't have to be
- included anymore. You don't have to worry about disabling <link linkend="utf.compilation.auto-linking">
- auto-linking</link> feature either. It's done in the implementation header already. This variant
- can't be used with the <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/>.
- Otherwise it's almost identical from the usage prospective to the static library variant of the &utf;.
- In fact the only difference is the name of the include file:
- <filename class="headerfile">boost/test/included/unit_test.hpp</filename> instead of
- <filename class="headerfile">boost/test/unit_test.hpp</filename>.
- </para>
-
- <para role="first-line-indented">
- The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
- module</link> initialization function that matches one of the two specifications depending on the compilation flag
- <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required to
- match the original specification. If you define the flag
- <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> during a test module compilation you are
- required to use the alternative initialization function specification. The &utf; provides an ability to
- <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
- initialization function with correct specification if no custom initialization is required by a test module.
- </para>
- </section>
-
- <section id="utf.user-guide.extern-test-runner-variant">
- <title>The external test runner variant of the &utf;</title>
- <titleabbrev>External test runner</titleabbrev>
-
- <para role="first-line-indented">
- All other usage variants employ the build-in test runners. If you plan to use an external test runner with your
- test module you need to build it as a dynamic library. This usage of the &utf; is called the external test runner
- variant of the &utf;. The variant requires you to define the flag
- <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/> either in a makefile or before the header
- <filename class="headerfile">boost/test/unit_test.hpp</filename> inclusion. An external test runner utility is
- required to link with dynamic library.
- </para>
-
- <para role="first-line-indented">
- If an external test runner is based on the test runner built in to the dynamic library (like the standalone
- boost_test_runner utility supplied by the &utf;), it requires you to implement the <link linkend="test-module.def">
- test module</link> initialization function that matches the alternative initialization function signature. The
- &utf; provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate
- </link> an empty test module initialization function with correct signature if no custom initialization is required
- by a test module.
- </para>
-
- <note>
- <simpara>
- An advanced test runner doesn't have to be based on the build-in one and may require a different
- test module initialization function signature and/or name.
- </simpara>
- </note>
- </section>
- </section>
-
- <section id="utf.user-guide.test-runners">
- <title>The supplied test runners … or where is the entrance?</title>
- <titleabbrev>Supplied test runners</titleabbrev>
-
<para role="first-line-indented">
- All usage variants of the &utf;, excluding the
- <link linkend="utf.user-guide.external-test-runner">external test runner</link>, supply the test runner in a form of
- free function named unit_test_main with the following signature:
+ One of the first non trivial things you might want toadd to your test module is test fixture. Fixture support is coverred in
+ <link linkend="utf.user-guide.fixture">Test fixture</link> section. Usually th default test module initialization will work just fine,
+ but if you want to implement some custom initialization or change how default initialization behaves you need to first look in
+ <link linkend="utf.user-guide.initialization">Test module initialization</link> section. Here you'll learn about various options the &utf;
+ provides for you to customize this behavior.
</para>
-
- <programlisting>int unit_test_main( init_unit_test_func init_func, int argc, char* argv[] );</programlisting>
-
<para role="first-line-indented">
- To invoke the test runner you are required to supply the pointer to the <link linkend="test-module.def">test module</link>
- initialization function as the first argument to the test runner function. In majority of the cases this function is
- invoked directly from test executable entry point - function main(). In most usage variants the &utf; can
- automatically generate default function main() implementation as either part of the library or test module itself.
- Since the function main needs to refer to the initialization function by name, it is predefined by the default
- implementation and you are required to match both specific signature and name, when implementing initialization
- function. If you for any reason prefer more flexibility you can opt to implement the function main() yourself, in
- which case it's going to be your responsibility to invoke the test runner, but the initialization function name is
- not enforces the &utf;. See below for flags that needs to be defined/undefined in each usage variant to enable this.
+ Finally you might want to learn about how the &utf; implements entry points into the test modules. This is especially important if you
+ intend to implement main function yourself (and not use the main function provided by the &utf;). The
+ <link linkend="utf.user-guide.test-runners">Test runners</link> section covers this subject. Different usage variants employ slightly
+ different approached to implementing test module entry points and presents slightly different interfaces. This section intended for advanced
+ user some of the details of the implementation are described there.
</para>
-
- <warning>
- <simpara>
- In spite syntactic similarity the signatures of the test runner function in fact are different for different usage
- variants. The cause is different signature of the test module initialization function referred by the
- <link linkend="utf.user-guide.initialization.signature-typedef">typedef init_unit_test_func</link>. This makes static
- and dynamic library usage variants incompatible and they can't be easily switched on a fly.
- </simpara>
- </warning>
-
- <section id="utf.user-guide.static-lib-runner">
- <title>Static library variant of the &utf;</title>
- <titleabbrev>Static library</titleabbrev>
-
- <para role="first-line-indented">
- By default this variant supplies the function main() as part of static library. If this is for any reason undesirable
- you need to define the flag <xref linkend="utf.flag.no-main" endterm="utf.flag.no-main"/> during the library
- compilation and the function main() implementation won't be generated.
- </para>
-
- <para role="first-line-indented">
- In addition to the <link linkend="utf.user-guide.static-lib-variant">initialization function signature requirement</link>
- default function main() implementation assumes the name of initialization function is init_unit_test_suite
- </para>
-
- </section>
-
- <section id="utf.user-guide.dynamic-lib-runner">
- <title>Dynamic library variant of the &utf;</title>
- <titleabbrev>Dynamic library</titleabbrev>
-
- <para role="first-line-indented">
- Unlike the static library variant function main() can't reside in the dynamic library body. Instead this variant
- supplies default function main() implementation as part of the header
- <filename class="headerfile">boost/test/unit_test.hpp</filename> to be generated as part of your test file body.
- The function main() is generated only if either the <xref linkend="utf.flag.main" endterm="utf.flag.main"/> or
- the <xref linkend="utf.flag.module" endterm="utf.flag.module"/> flags are defined during a test module compilation.
- For <link linkend="single-file-test-module.def">single-file test module</link> flags can be defined either in a
- test module's makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
- inclusion. For a <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/> flags can't
- be defined in makefile and have to be defined in only one of the test files to avoid duplicate copies of the
- function main().
- </para>
-
- <important>
- <simpara>
- The same flags also govern generation of an empty
- <link linkend="utf.user-guide.initialization">test module initialization function</link>. This means that if you
- need to implement either function main() or initialization function manually, you can't define the above flags
- and are required to manually implement both of them.
- </simpara>
- </important>
- </section>
-
- <section id="utf.user-guide.single-header-runner">
- <title>Single-header variant of the &utf;</title>
- <titleabbrev>Single header</titleabbrev>
-
- <para role="first-line-indented">
- By default this variant supplies function main() as part of the header
- <filename class="headerfile">boost/test/included/unit_test.hpp</filename> to be generated as part of your test file
- body. If this is for any reason undesirable you need to define the flag
- <xref linkend="utf.flag.no-main" endterm="utf.flag.no-main"/> during test module compilation and the function main()
- implementation won't be generated.
- </para>
- </section>
-
- <section id="utf.user-guide.external-test-runner">
- <title>External test runner variant of the &utf;</title>
- <titleabbrev>External test runner</titleabbrev>
-
- <para role="first-line-indented">
- The external test runner variant of the &utf; supplies the test runner in a form of standalone utility
- boost_test_runner. You are free to implement different, more advanced, test runners that can be used with this
- variant.
- </para>
-
- <simpara>
- <!-- TO FIX -->
- </simpara>
- </section>
-
- <section id="utf.user-guide.runners-exit-status">
- <title>Generated exit status values</title>
-
- <para role="first-line-indented">
- Once testing is finished, all supplied test runners report the results and returns an exit status value. Here are
- the summary of all possible generated values:
- </para>
- <table id="utf.user-guide.runners-exit-status-summary">
- <title>Generated exit status values</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <thead>
- <row>
- <entry>Value</entry>
- <entry>Meaning</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>boost::exit_success</entry>
- <entry>
- No errors occurred during the test or the success result code was explicitly requested with the no_result_code
- parameter.
- </entry>
- </row>
- <row>
- <entry>boost::exit_test_failure</entry>
- <entry>
- Non-fatal errors detected and no uncaught exceptions were thrown during testing or the &utf; fails during
- initialization.
- </entry>
- </row>
- <row>
- <entry>boost::exit_exception_failure</entry>
- <entry>
- Fatal errors were detected or uncaught exceptions thrown during testing.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
</section>
- <section id="utf.user-guide.initialization">
- <title>Test module initialization … or ready, set …</title>
- <titleabbrev>Test module initialization</titleabbrev>
-
- <para role="first-line-indented">
- There are two tasks that you may need to perform before actual testing can start:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- The test tree needs to be built (unless you are using automated test units registration).
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Custom test module initialization needs to be performed. This includes
- initialization of the code under test and custom tune-up of the &utf; parameters (for example the test log or the
- test results report output streams redirection).
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- The function dedicated for this purpose is called the test module initialization function. Alternatively you can
- employ global fixtures, covered in details, including differences in two approaches, in
- <xref linkend="utf.user-guide.fixture"/>.
- </para>
-
- <para role="first-line-indented">
- The &utf; requires you to implement the test module initialization function. The test runner supplied with the static
- library or single-header variants of the &utf; requires the specific function specification. The test runner supplied
- with the dynamic library variant of the &utf; requires the specific initialization function signature only. <!-- TO FIX: specific specification -->
- </para>
-
- <para role="first-line-indented">
- For many <link linkend="test-module.def">test modules</link> you don't need to do any custom initialization
- and test tree construction is automated. In this case you don't really need the initialization function and
- the &utf; provides a way to automatically generate an empty one for you.
- </para>
-
- <para role="first-line-indented">
- Original design of the &utf; supported the manual test tree construction only. Later versions introduced the
- automated registration of test units. In later versions of the &utf; the original initialization function
- specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification
- was introduced. This change is not backward compatible. The test runners supplied with the static library and
- single-header variants of the &utf; by default still require original initialization function specification, but
- support <link linkend="utf.compilation.flags">compilation flags</link> that switch to the alternative one. The test
- runner supplied with dynamic library variant of the &utf; requires new specification and doesn't support
- original one. The plan is to deprecate the original initialization function specification in one of the future
- releases and ultimately to stop supporting it.
- </para>
-
- <para role="first-line-indented">
- The initialization function invocation is monitored by the &utf; the same way as all the test cases. An unexpected
- exception or system error detected during initialization function invocation is treated as initialization error and
- is reported as such.
- </para>
-
- <section id="utf.user-guide.initialization.orig-signature">
- <title>Original initialization function signature and name</title>
- <titleabbrev>Original initialization function</titleabbrev>
-
- <para role="first-line-indented">
- The original design of the &utf; initialization requires you to implement the function with the following
- specification:
- </para>
-
- <programlisting><classname>boost::unit_test::test_suite</classname>* init_unit_test_suite( int argc, char* argv[] );</programlisting>
-
- <para role="first-line-indented">
- In original design of the &utf; this function was intended to initialize and return a master test suite. The null
- value was considered an initialization error. The current design of the &utf; maintains master test suite instance
- internally and does not treat the null result value as an initialization error. In fact it's recommended to
- return null value always and register test units in the master test suite using the regular test suite add
- interface. The only way to indicate an initialization error is to throw the
- <classname>boost::unit_test::framework::setup_error</classname> exception.
- </para>
-
- <para role="first-line-indented">
- The initialization function parameters argc, argv provide the command line arguments specified during test
- module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be
- consisted with the alternative initialization function specification it's recommended though to access the
- command line arguments using the master test suite interface.
- </para>
- </section>
-
- <section id="utf.user-guide.initialization.alt-signature">
- <title>Alternative initialization function signature and name</title>
- <titleabbrev>Alternative initialization function</titleabbrev>
-
- <para role="first-line-indented">
- The alternative design of the &utf; initialization requires you to implement a function with the following
- specification:
- </para>
-
- <programlisting>bool init_unit_test();</programlisting>
-
- <para role="first-line-indented">
- The result value of this function indicates whether or not initialization was successful. To register test
- units in a master test suite use the test suite add interface. To access command line arguments use the master
- test suite interface. It's guarantied that any framework-specific command line arguments are excluded.
- </para>
- </section>
-
- <section id="utf.user-guide.initialization.signature-typedef">
- <title>Initialization function signature access</title>
-
- <para role="first-line-indented">
- The test runner interface needs to refer to the initialization function signature. The &utf; provides the typedef
- that resolves to proper signature in all configurations:
- </para>
-
- <programlisting>namespace boost {
-namespace unit_test {
-#ifdef BOOST_TEST_ALTERNATIVE_INIT_API
-typedef bool (*init_unit_test_func)();
-#else
-typedef test_suite* (*init_unit_test_func)( int, char* [] );
-#endif
-}
-}</programlisting>
-
- </section>
-
- <section id="utf.user-guide.initialization.auto-generation">
- <title>Automated generation of the test module initialization function</title>
- <titleabbrev>Automated generation</titleabbrev>
-
- <para role="first-line-indented">
- To automatically generate an empty test module initialization function you need to define
- <xref linkend="utf.flag.main" endterm="utf.flag.main"/> before including the
- <filename class="headerfile">boost/test/unit_test.hpp</filename> header. The value of this define is ignored.
- Alternatively you can define the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/> to be equal to
- any string (not necessarily in quotes). This macro causes the same result as
- <xref linkend="utf.flag.main" endterm="utf.flag.main"/>, and in addition the macro value becomes the name of the
- master test suite.
- </para>
-
- <important>
- <simpara>
- For a test module consisting of multiple source files you have to define these flags in a single test file only.
- Otherwise you end up with multiple instances of the initialization function.
- </simpara>
- </important>
- </section>
- </section>
-
- <xi:include href="utf.users-guide.test-organization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.users-guide.fixture.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.users-guide.test-output.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.usage-variants.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.test-organization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.testing-tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.test-output.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="utf.user-guide.runtime-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.fixture.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.initialization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.test-runners.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.glossary.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
</section>
Deleted: trunk/libs/test/doc/src/utf.users-guide.fixture.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.users-guide.fixture.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,284 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
- <!ENTITY utf "<acronym>UTF</acronym>">
-]>
-<section id="utf.user-guide.fixture">
- <title>Fixtures … or let me repeat myself</title>
- <titleabbrev>Fixtures</titleabbrev>
-
- <para role="first-line-indented">
- In general terms a test fixture or test context is the collection of one or more of the following items, required
- to perform the test:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>preconditions</simpara>
- </listitem>
- <listitem>
- <simpara>particular states of tested unites</simpara>
- </listitem>
- <listitem>
- <simpara>necessary cleanup procedures</simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- Though these tasks are encountered in many if not all test cases, what makes a test fixture different is
- repetition. Where a normal test case implementation does all preparatory and cleanup work itself, a test fixture
- allows this to be implemented in a separate reusable unit.
- </para>
-
- <para role="first-line-indented">
- With introduction of extreme programming (XP), the testing style, that require test setup/cleanup repetition, is
- becoming more and more popular. Single XP adopted test modules may contain hundreds of single assertion test cases,
- many requiring very similar test setup/cleanup. This is the problem that the test fixture is designed to solve.
- </para>
-
- <para role="first-line-indented">
- In practice a test fixture usually is a combination of setup and teardown functions, associated with test case.
- The former serves the purposes of test setup; the later is dedicated to the cleanup tasks. Ideally it's
- preferable that a test module author is able to define variables used in fixtures on the stack and the same time
- is able to refer to them directly in test case.
- </para>
-
- <para role="first-line-indented">
- It's important to understand that C++ provides a way to implement a straightforward test fixture solution
- that almost satisfies our requirements without any extra support from the test framework. This may explain why
- test fixtures support was introduced in the &utf; somewhat late in its life cycle. Here is how simple test module
- with such a fixture may look like:
- </para>
-
- <btl-snippet name="snippet5"/>
-
- <para role="first-line-indented">
- This is a generic solution that can be used to implement any kind of shared setup or cleanup procedure. Still
- there are several more or less minor practical issues with this pure C++ based fixtures solution:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- We need to add a fixture declaration statement into each test case manually.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Objects defined in fixture are references with "<fixture-instance-name>." prefix.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- There is no place to execute a "global" fixture, which performs "global" setup/cleanup
- procedures before and after testing.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- While there is little the &utf; can do to address these issues for manually registered test units, it's
- possible to resolve them for test units that are automatically registered. To do this the &utf; defines a
- <link linkend="utf.user-guide.fixture.model">generic fixture model</link> - fixed interfaces that both setup and
- teardown fixture functions should comply to. Based on the generic fixture model, the &utf; presents solution for
- the following tasks:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara><link linkend="utf.user-guide.fixture.per-test-case">per test case fixture automation</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.fixture.test-suite-shared">shared test suite level fixture</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.fixture.global">"global" fixture support</link></simpara>
- </listitem>
- </itemizedlist>
-
- <section id="utf.user-guide.fixture.model">
- <title>Generic fixture model</title>
- <titleabbrev>Generic model</titleabbrev>
-
- <para role="first-line-indented">
- The &utf; defines the generic fixture model as follows:
- </para>
-
- <programlisting>struct <fixture-name>{
- <fixture-name>(); // setup function
- ~<fixture-name>(); // teardown function
-};</programlisting>
-
- <para role="first-line-indented">
- In other words a fixture is expected to be implemented as a class where the class constructor serves as a setup
- method and class destructor serves as teardown method. The &utf; opted to avoid explicit names in fixture
- interface for setup and teardown methods, since is considered most natural in C++ for tasks similar to RAII and
- coincides with the pure C++ solution discusses earlier.
- </para>
-
- <important>
- <simpara>
- The above interface prevents you to report errors in the teardown procedure using an exception. It does make
- sense though: if somehow more than one fixture is assigned to a test unit, you want all teardown procedures to
- run, even if some may experience problems.
- </simpara>
- </important>
- </section>
-
- <section id="utf.user-guide.fixture.per-test-case">
- <title>Per test case fixture</title>
- <titleabbrev>Per test case</titleabbrev>
-
- <para role="first-line-indented">
- To automate the task of assigning a fixture for the test case, for test case creation use the macro
- BOOST_FIXTURE_TEST_CASE in place of the macro <macroname>BOOST_AUTO_TEST_CASE</macroname>:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_FIXTURE_TEST_CASE" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- <macro-parameter name="fixture_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The only difference from the macro <macroname>BOOST_AUTO_TEST_CASE</macroname> is the presence of an extra argument
- - fixture name. Unlike the pure C++ solution you have direct access to the public and protected members of the
- fixture, though you still need to refer to the fixture name in every test case.
- </para>
-
- <note>
- <simpara>
- You can't access private members of fixture, but then why would you make anything private?
- </simpara>
- </note>
-
- <btl-example name="example18">
- <title>Per test case fixture</title>
-
- <para role="first-line-indented">
- In this example only test_case1 and test_case2 have fixture F assigned. In the next section you going to see
- what can be done if all test cases in a test suite require the same fixture.
- </para>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.fixture.test-suite-shared">
- <title>Test suite level fixture</title>
- <titleabbrev>Test suite shared</titleabbrev>
-
- <para role="first-line-indented">
- If all test cases in a test require the same fixture (you can group test cases in the test suite based on a
- fixture required) you can make another step toward an automation of a test fixture assignment. To assign the
- same shared fixture for all test cases in a test suite use the macro BOOST_FIXTURE_TEST_SUITE in place of the
- macro <macroname>BOOST_AUTO_TEST_SUITE</macroname> for automated test suite creation and registration.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_FIXTURE_TEST_SUITE" kind="functionlike">
- <macro-parameter name="suite_name"/>
- <macro-parameter name="fixure_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- Once again the only difference from the macro <macroname>BOOST_AUTO_TEST_SUITE</macroname> usage is the presence of
- an extra argument - the fixture name. And now, you not only have direct access to the public and protected members
- of the fixture, but also do not need to refer to the fixture name in test case definition. All test cases assigned
- the same fixture automatically.
- </para>
-
- <tip>
- <simpara>
- If necessary you can reset the fixture for a particular test case with the use of the macro
- <macroname>BOOST_FIXTURE_TEST_CASE</macroname>.
- </simpara>
- </tip>
-
- <note>
- <simpara>
- The fixture assignment is "deep". In other words unless reset by another
- <macroname>BOOST_FIXTURE_TEST_SUITE</macroname> or <macroname>BOOST_FIXTURE_TEST_CASE</macroname> definition the
- same fixture is assigned to all test cases, including ones that belong to the sub test suites.
- </simpara>
- </note>
-
- <btl-example name="example19">
- <title>Test suite level fixture</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.fixture.global">
- <title>Global fixture</title>
-
- <para role="first-line-indented">
- Any global initialization that needs to be performed every time testing begins or a global cleanup that is to be
- performed once testing is finished is called a global fixture. The &utf; global fixture design is based on a
- generic test fixture model and is supported by the utility class boost::unit_test::global_fixture. The global
- fixture design allows any number of global fixtures to be defined in any test file that constitutes a test module.
- Though some initialization can be implemented in the test module initialization function, there are several
- reasons to prefer the global fixture approach:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>There is no place for cleanup/teardown operations in the initialization function.</simpara>
- </listitem>
- <listitem>
- <simpara>
- Unlike the initialization function, the global fixture setup method invocation is guarded by the execution
- monitor. That means that all uncaught errors that occur during initialization are properly reported.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Any number of different global fixtures can be defined, which allows you to split initialization code by
- category.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- The fixture allows you to place matching setup/teardown code in close vicinity in your test module code.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- If the whole test tree is constructed automatically the initialization function is empty and auto-generated by
- the &utf;. To introduce the initialization function can be more work than the use of a global fixture facility,
- while global fixture is more to the point.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Since all fixtures follow the same generic model you can easily switch from local per test case fixtures to
- the global one.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- If you are using the interactive test runner (non-supplied yet) global test fixtures are applied to every run,
- while an initialization function is executed only once during a test module startup (just make sure that
- it's what you really want).
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- To define a global test module fixture you need to implement a class that matched generic fixture model and
- passed it as an argument to the macro BOOST_GLOBAL_FIXTURE.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_GLOBAL_FIXTURE" kind="functionlike">
- <macro-parameter name="fixure_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The statement, that performs global fixture definition, has to reside at a test file scope.
- </para>
-
- <btl-example name="example20">
- <title>Global fixture</title>
- </btl-example>
- </section>
-</section>
\ No newline at end of file
Deleted: trunk/libs/test/doc/src/utf.users-guide.test-organization.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.users-guide.test-organization.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,840 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
- <!ENTITY utf "<acronym>UTF</acronym>">
-]>
-<section id="utf.user-guide.test-organization">
- <title>Test organization … or the house that Jack built</title>
- <titleabbrev>Test organization</titleabbrev>
-
- <para role="first-line-indented">
- If you look at many legacy test modules, big chance is that it's implemented as one big test function that
- consists of a mixture of check and output statements. Is there anything wrong with it? Yes. There are various
- disadvantages in single test function approach:
- </para>
-
- <itemizedlist mark="square">
- <listitem>
- <simpara>
- One big function tends to become really difficult to manage if the number of checks exceeds a reasonable limit
- (true for any large function). What is tested and where - who knows?
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Many checks require similar preparations. This results in code repetitions within the test function.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- If a fatal error or an exception is caused by any checks within the test function the rest of tests are
- skipped and there is no way to prevent this.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- No way to perform only checks for a particular subsystem of the tested unit.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- No summary of how different subsystems of the tested unit performed under in the test.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- The above points should make it clear that it's preferable to split <link linkend="test-module.def">test module
- </link> into smaller units. These units are test cases. A test case has to be constructed based on some kind of
- function and registered in a test tree, so that the test runner knows how to invoke it. There are different
- possible designs for the test case construction problem: inheritance from the predefined base class, specifically
- named member function and so on. The &utf; opted to avoid classed altogether and to use the least intrusive "
- generic callback" approach. The facility, the &utf; provides, requires specific function signature and allows
- adopting any function or function object that matches the signature as a test case. The signatures the &utf;
- supports are:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.nullary-test-case">Nullary function</link>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.unary-test-case">Unary function</link>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.test-case-template">Nullary function template</link>
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- To solve test tree creation problem the &utf; provides facilities for
- <link linkend="utf.user-guide.test-organization.test-suite">test suite creation</link>.
- </para>
-
- <para role="first-line-indented">
- Generic test case construction design used by the &utf; causes the test case implementation (test function body)
- and test case creation/registration points to be remote. As a result you may forget to register the test case
- and it's never going to be executed, even though it's present in test file. To alleviate this issue
- the &utf; presents facilities for automated (in place) test case creation and registration in the test tree. These
- facilities sacrifice some generality and work for selected test function signatures only. But the result is that
- library users are relieved from the necessity to manually register test cases. These facilities are the most
- user-friendly and are recommended to be used whenever possible. In addition they support automated registration
- of test suites, thus allowing whole test tree to be created without any use of manual registration.
- </para>
-
- <para role="first-line-indented">
- The single test module may mix both automated and manual test case
- registration. In other words, within the same test module you can have both test cases implemented remotely and
- registered manually in the test module initialization function and test cases that are registered automatically at
- implementation point.
- </para>
-
- <para role="first-line-indented">
- In some cases it's desirable to allow some "expected" failures in test case without failing a
- test module. To support this request The &utf; allows specifying the number of
- <link linkend="utf.user-guide.test-organization.expected-failures">expected failures</link> in a test case.
- </para>
-
- <section id="utf.user-guide.test-organization.nullary-test-case">
- <title>Nullary function based test case</title>
-
- <para role="first-line-indented">
- The most widely used are test cases based on a nullary function. These include nullary free functions, nullary
- function objects created with <functionname>boost::bind</functionname> and nullary <classname>boost::function</classname>
- instances. The simplest is a free function and the &utf; provides facilities to create a free function based test
- case that is automatically registered. Here are the two construction interfaces:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.manual-nullary-test-case">Manually registered test case</link>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.auto-nullary-test-case">Test case with automated registration</link>
- </simpara>
- </listitem>
- </itemizedlist>
-
- <section id="utf.user-guide.test-organization.manual-nullary-test-case">
- <title>Manually registered nullary function based test case</title>
- <titleabbrev>Manual registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a test case manually, employ the macro BOOST_TEST_CASE:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_CASE" kind="functionlike">
- <macro-parameter name="test_function"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- BOOST_TEST_CASE creates an instance of the class boost::unit_test::test_case and returns a pointer to the
- constructed instance. The test case name is deduced from the macro argument test_function. If you prefer to
- assign a different test case name, you have to use the underlying make_test_case interface instead. To
- register a new test case, employ the method test_suite::add. Both test case creation and registration are
- performed in the test module initialization function.
- </para>
-
- <para role="first-line-indented">
- Here is the simplest possible manually registered test case. This example employs the original test module
- initialization function specification. A single test case is created and registered in the master test suite.
- Note that the free function name is passed by address to the macro BOOST_TEST_CASE.
- </para>
-
- <btl-example name="example01">
- <title>Nullary free function manually registered</title>
- </btl-example>
-
- <para role="first-line-indented">
- A test case can be implemented as a method of a class. In this case a pointer to the class instance has to be
- bound to the test method to create a test case. You can use the same instance of the class for multiple test
- cases. The &utf; doesn't take an ownership of the class instance and you are required to manage the class
- instance lifetime yourself.
- </para>
-
- <warning>
- <simpara>
- The class instance can't be defined in the initialization function scope, since it becomes invalid as
- soon as the test execution exits it. It needs to be either defined statically/globally or managed using a
- shared pointer.
- </simpara>
- </warning>
-
- <btl-example name="example02">
- <title>Nullary method of a class bound to global class instance and manually registered</title>
- </btl-example>
-
- <btl-example name="example03">
- <title>Nullary method of a class bound to shared class instance and manually registered</title>
- </btl-example>
-
- <para role="first-line-indented">
- If you do not need to reuse the test class instance and can't or do not wish to create test class
- instance globally it may be easier and safer to create an instance on the stack of free function:
- </para>
-
- <btl-example name="example04">
- <title>Nullary method of a class bound to local class instance inside free function</title>
- </btl-example>
-
- <para role="first-line-indented">
- If you have to perform the same set of tests with different sets of parameters you may want to base your test
- case on a function with arguments and bind particular parameters during test case creation.
- </para>
-
- <warning>
- <simpara>
- If you bind parameters by reference or pointer, the referenced value can't have local storage in the
- test module initialization function.
- </simpara>
- </warning>
-
- <btl-example name="example05">
- <title>Binary free function bound to set of different parameter pairs</title>
-
- <para role="first-line-indented">
- This example employs the alternative test module initialization function specification.
- </para>
- </btl-example>
-
- <para role="first-line-indented">
- The &utf; also presents an alternative method for parameterized test case creation, which is covered in
- <xref linkend="utf.user-guide.test-organization.unary-test-case"/>.
- </para>
- </section>
-
- <section id="utf.user-guide.test-organization.auto-nullary-test-case">
- <title>Nullary function based test case with automated registration</title>
- <titleabbrev>Automated registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a nullary free function cased test case, which is registered in place of implementation, employ the
- macro BOOST_AUTO_TEST_CASE.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_AUTO_TEST_CASE" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The macro is designed to closely mimic nullary free function syntax. Changes that are required to make an
- existing test case, implemented as a free function, registered in place are illustrated in the following
- example (compare with <xref linkend="utf.user-guide.test-organization.manual-nullary-test-case.example01"/>):
- </para>
-
- <btl-example name="example06">
- <title>Nullary function based test case with automated registration</title>
- </btl-example>
-
- <para role="first-line-indented">
- With this macro you don't need to implement the initialization function at all. The macro creates and
- registers the test case with the name free_test_function automatically.
- </para>
- </section>
- </section>
- <section id="utf.user-guide.test-organization.unary-test-case">
- <title>Unary function based test case</title>
-
- <para role="first-line-indented">
- Some tests are required to be repeated for a series of different input parameters. One way to achieve this is
- manually register a test case for each parameter as in example above. You can also invoke a test function with
- all parameters manually from within your test case, like this:
- </para>
-
- <btl-snippet name="snippet1"/>
-
- <para role="first-line-indented">
- The &utf; presents a better solution for this problem: the unary function based test case, also referred as
- parameterized test case. The unary test function can be a free function, unary functor (for example created
- with boost::bind) or unary method of a class with bound test class instance). The test function is converted
- into test case using the macro BOOST_PARAM_TEST_CASE. The macro expects a collection of parameters (passed as
- two input iterators) and an unary test function:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_PARAM_TEST_CASE" kind="functionlike">
- <macro-parameter name="test_function"/>
- <macro-parameter name="params_begin"/>
- <macro-parameter name="params_end"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- BOOST_PARAM_TEST_CASE creates an instance of the test case generator. When passed to the method test_suite::add,
- the generator produces a separate sub test case for each parameter in the parameters collection and registers
- it immediately in a test suite. Each test case is based on a test function with the parameter bound by value,
- even if the test function expects a parameter by reference. The fact that parameter value is stored along with
- bound test function releases you from necessity to manage parameters lifetime. For example, they can be defined
- in the test module initialization function scope.
- </para>
-
- <para role="first-line-indented">
- All sub test case names are deduced from the macro argument test_function. If you prefer to assign different
- names, you have to use the underlying make_test_case interface instead. Both test cases creation and
- registration are performed in the test module initialization function.
- </para>
-
- <para role="first-line-indented">
- The parameterized test case facility is preferable to the approach in the example above, since execution of
- each sub test case is guarded and counted independently. It produces a better test log/results report (in
- example above in case of failure you can't say which parameter is at fault) and allows you to test against
- all parameters even if one of them causes termination a particular sub test case.
- </para>
-
- <para role="first-line-indented">
- In comparison with a manual test case registration for each parameter approach the parameterized test case
- facility is more concise and easily extendible.
- </para>
-
- <para role="first-line-indented">
- In following simple example the same test, implemented in <code>free_test_function</code>, is
- performed for 5 different parameters. The parameters are defined in the test module initialization function
- scope. The master test suite contains 5 independent test cases.
- </para>
-
- <btl-example name="example07">
- <title>Unary free function based test case</title>
- </btl-example>
-
- <para role="first-line-indented">
- Next example is similar, but instead of a free function it uses a method of a class. Even though parameters are
- passed into test method by reference you can still define them in the test module initialization function scope.
- This example employs the alternative test module initialization function specification.
- </para>
-
- <btl-example name="example08">
- <title>Unary class method based test case</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-organization.test-case-template">
- <title>Test case template</title>
- <para role="first-line-indented">
- To test a template based component it's frequently necessary to perform the same set of checks for a
- component instantiated with different template parameters. The &utf; provides the ability to create a series of
- test cases based on a list of desired types and function similar to nullary function template. This facility is
- called test case template. Here are the two construction interfaces:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.manual-test-case-template">Manually registered test case
- template</link>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.auto-test-case-template">Test case template with automated
- registration</link>
- </simpara>
- </listitem>
- </itemizedlist>
-
- <section id="utf.user-guide.test-organization.manual-test-case-template">
- <title>Manually registered test case template</title>
- <titleabbrev>Manual registration</titleabbrev>
-
- <para role="first-line-indented">
- One way to perform the same set of checks for a component instantiated with different template parameters is
- illustrated in the following example:
- </para>
-
- <btl-snippet name="snippet2"/>
-
- <para role="first-line-indented">
- There several problems/inconveniencies with above approach, including:
- <itemizedlist>
- <listitem>
- <simpara>
- Fatal error in one of the invocation will stop whole test case and will skip invocations with different types
- </simpara>
- <simpara>
- You need to repeat function invocation manually for all the parameters you are interested in
- </simpara>
- <simpara>
- You need two functions to implement the test
- </simpara>
- </listitem>
- </itemizedlist>
- Ideally the test case template would be based on nullary function template (like single_test above).
- Unfortunately function templates are neither addressable nor can be used as template parameters. To alleviate
- the issue the manually registered test case template facility consists of two co-working macros:
- BOOST_TEST_CASE_TEMPLATE_FUNCTION and BOOST_TEST_CASE_TEMPLATE. Former is used to define the test case
- template body, later - to create and register test cases based on it.
- </para>
-
- <para role="first-line-indented">
- The macro BOOST_TEST_CASE_TEMPLATE_FUNCTION requires two arguments: the name of the test case template and the
- name of the format type parameter:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_CASE_TEMPLATE_FUNCTION" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- <macro-parameter name="type_name"/>
- </macro>
- </inline-synopsis>
-
- <btl-snippet name="snippet3"/>
-
- <para role="first-line-indented">
- The macro BOOST_TEST_CASE_TEMPLATE_FUNCTION is intended to be used in place of nullary function template
- signature:
- </para>
-
- <btl-snippet name="snippet4"/>
-
- <para role="first-line-indented">
- The only difference is that the BOOST_TEST_CASE_TEMPLATE_FUNCTION makes the test case template name usable in
- the template argument list.
- </para>
-
- <para role="first-line-indented">
- BOOST_TEST_CASE_TEMPLATE requires two arguments: the name of the test case template and Boost.MPL compatible
- collection of types to instantiate it with. The names passed to both macros should be the same.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_CASE_TEMPLATE" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- <macro-parameter name="collection_of_types"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- BOOST_TEST_CASE_TEMPLATE creates an instance of the test case generator. When passed to the method
- test_suite::add, the generator produces a separate sub test case for each type in the supplied collection of
- types and registers it immediately in the test suite. Each test case is based on the test case template body
- instantiated with a particular test type.
- </para>
-
- <para role="first-line-indented">
- Sub test case names are deduced from the macro argument test_case_name. If you prefer to assign different test
- case names, you need to use the underlying make_test_case interface instead. Both test cases creation and
- registration is performed in the test module initialization function.
- </para>
-
- <para role="first-line-indented">
- The test case template facility is preferable to the approach in example above, since execution of each sub
- test case is guarded and counted separately. It produces a better test log/results report (in example above in
- case of failure you can't say which type is at fault) and allows you to test all types even if one of
- them causes termination of the sub test case.
- </para>
-
- <btl-example name="example09">
- <title>Manually registered test case template</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-organization.auto-test-case-template">
- <title>Test case template with automated registration</title>
- <titleabbrev>Automated registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a test case template registered in place of implementation, employ the macro
- BOOST_AUTO_TEST_CASE_TEMPLATE. This facility is also called <firstterm>auto test case template</firstterm>.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_AUTO_TEST_CASE_TEMPLATE" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- <macro-parameter name="formal_type_parameter_name"/>
- <macro-parameter name="collection_of_types"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The macro BOOST_AUTO_TEST_CASE_TEMPLATE requires three arguments:
- </para>
- <variablelist>
- <?dbhtml list-presentation="list"?>
- <?dbhtml term-width="60%" list-width="100%"?>
- <?dbhtml term-separator=" - "?> <!-- TO FIX: where separator? -->
-
- <varlistentry>
- <term>The test case template name</term>
- <listitem>
- <simpara>
- unique test cases template identifier
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>The name of a formal template parameter</term>
- <listitem>
- <simpara>
- name of the type the test case template is instantiated with
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>The collection of types to instantiate test case template with</term>
- <listitem>
- <simpara>
- arbitrary MPL sequence
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <btl-example name="example10">
- <title>Test case template with automated registration</title>
- </btl-example>
- </section>
- </section>
-
- <section id="utf.user-guide.test-organization.test-suite">
- <title>Test suite</title>
-
- <para role="first-line-indented">
- If you consider test cases as leaves on the test tree, the test suite can be considered as branch and the master
- test suite as a trunk. Unlike real trees though, our tree in many cases consists only of leaves attached
- directly to the trunk. This is common for all test cases to reside directly in the master test suite. If you do
- want to construct a hierarchical test suite structure the &utf; provides both manual and automated
- test suite creation and registration facilities:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.manual-test-suite">Manually registered test suite</link>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <link linkend="utf.user-guide.test-organization.auto-test-suite">Test suite with automated registration</link>
- </simpara>
- </listitem>
- </itemizedlist>
-
- <section id="utf.user-guide.test-organization.test-suite-registration-interface">
- <title>Test unit registration interface</title>
-
- <para role="first-line-indented">
- The &utf; models the notion of test case container - test suite - using class boost::unit_test::test_suite. For
- complete class interface reference check advanced section of this documentation. Here you should only be
- interested in a single test unit registration interface:
- </para>
-
- <programlisting>void test_suite::add( test_unit* tc, counter_t expected_failures = 0, int timeout = 0 );</programlisting>
-
- <para role="first-line-indented">
- The first parameter is a pointer to a newly created test unit. The second optional parameter -
- expected_failures - defines the number of test assertions that are expected to fail within the test unit. By
- default no errors are expected.
- </para>
-
- <caution>
- <simpara>
- Be careful when supplying a number of expected failures for test suites. By default the &utf; calculates the
- number of expected failures in test suite as the sum of appropriate values in all test units that constitute
- it. And it rarely makes sense to change this.
- </simpara>
- </caution>
-
- <para role="first-line-indented">
- The third optional parameter - timeout - defines the timeout value for the test unit. As of now the &utf;
- isn't able to set a timeout for the test suite execution, so this parameter makes sense only for test case
- registration. By default no timeout is set. See the method
- <methodname>boost::execution_monitor::execute</methodname> for more details about the timeout value.
- </para>
-
- <para role="first-line-indented">
- To register group of test units in one function call the boost::unit_test::test_suite provides another add
- interface covered in the advanced section of this documentation.
- </para>
- </section>
-
- <section id="utf.user-guide.test-organization.manual-test-suite">
- <title>Manually registered test suites</title>
- <titleabbrev>Manual registration</titleabbrev>
-
- <para role="first-line-indented">
- To create a test suite manually, employ the macro BOOST_TEST_SUITE:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_SUITE" kind="functionlike">
- <macro-parameter name="test_suite_name"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- BOOST_TEST_SUITE creates an instance of the class boost::unit_test::test_suite and returns a pointer to the
- constructed instance. Alternatively you can create an instance of class boost::unit_test::test_suite yourself.
- </para>
-
- <note>
- <simpara>
- boost::unit_test::test_suite instances have to be allocated on the heap and the compiler won't allow you
- to create one on the stack.
- </simpara>
- </note>
-
- <para role="first-line-indented">
- Newly created test suite has to be registered in a parent one using add interface. Both test suite creation and
- registration is performed in the test module initialization function.
- </para>
-
- <btl-example name="example11">
- <title>Manually registered test suites</title>
- </btl-example>
-
- <para role="first-line-indented">
- This example creates a test tree, which can be represented by the following hierarchy:
- </para>
-
- <mediaobject>
- <imageobject>
- <imagedata format="jpg" fileref="../img/class-hier.jpg"/>
- </imageobject>
- </mediaobject>
- </section>
-
- <section id="utf.user-guide.test-organization.auto-test-suite">
- <title>Test suites with automated registration</title>
- <titleabbrev>Automated registration</titleabbrev>
-
- <para role="first-line-indented">
- The solution the &utf; presents for automated test suite creation and registration is designed to facilitate
- multiple points of definition, arbitrary test suites depth and smooth integration with automated test case creation
- and registration. This facility should significantly simplify a test tree construction process in comparison with
- manual explicit registration case.
- </para>
-
- <para role="first-line-indented">
- The implementation is based on the order of file scope variables definitions within a single compilation unit.
- The semantic of this facility is very similar to the namespace feature of C++, including support for test suite
- extension. To start test suite use the macro BOOST_AUTO_TEST_SUITE. To end test suite use the macro
- BOOST_AUTO_TEST_SUITE_END. The same test suite can be restarted multiple times inside the same test file or in a
- different test files. In a result all test units will be part of the same test suite in a constructed test tree.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_AUTO_TEST_SUITE" kind="functionlike">
- <macro-parameter name="test_suite_name"/>
- </macro>
- <macro name="BOOST_AUTO_TEST_SUITE_END" kind="functionlike"/>
- </inline-synopsis>
-
- <para role="first-line-indented">
- Test units defined in between test suite start and end declarations become members of the test suite. A test
- unit always becomes the member of the closest test suite declared. Test units declared at a test file scope
- become members of the master test suite. There is no limit on depth of test suite inclusion.
- </para>
-
- <btl-example name="example12">
- <title>Test suites with automated registration</title>
-
- <para role="first-line-indented">
- This example creates a test tree that matches exactly the one created in the manual test suite registration
- example. As you can see test tree construction in this example is more straightforward and automated.
- </para>
- </btl-example>
-
- <btl-example name="example53">
- <title>Example of test suite extension using automated registration facility</title>
-
- <para role="first-line-indented">
- In this example test suite test_suite consists of two parts. Their definition is remote and is separated by another
- test case. In fact these parts may even reside in different test files. The resulting test tree remains the same. As
- you can see from the output both test_case1 and test_case2 reside in the same test suite test_suite.
- </para>
- </btl-example>
-
- </section>
- <section id="utf.user-guide.test-organization.master-test-suite">
- <title>Master Test Suite</title>
-
- <para role="first-line-indented">
- As defined in introduction section the master test suite is a root node of a test tree. Each test module built
- with the &utf; always has the master test suite defined. The &utf; maintain the master test suite instance
- internally. All other test units are registered as direct or indirect children of the master test suite.
- </para>
-
- <programlisting>namespace boost {
-namespace unit_test {
-class master_test_suite_t : public test_suite {
-public:
- int argc;
- char** argv;
-};
-
-} // namespace unit_test
-
-} // namespace boost</programlisting>
-
- <para role="first-line-indented">
- To access single instance of the master test suite use the following interface:
- </para>
-
- <programlisting>namespace boost {
-namespace unit_test {
-namespace framework {
-
-master_test_suite_t& master_test_suite();
-
-} // namespace framework
-} // namespace unit_test
-} // namespace boost</programlisting>
-
- <section id="utf.user-guide.test-organization.cla-access" >
- <title>Command line arguments access interface</title>
-
- <para role="first-line-indented">
- Master test suite implemented as an extension to the regular test suite, since it maintains references to the
- command line arguments passed to the test module. To access the command line arguments use
- </para>
-
- <programlisting>boost::unit_test::framework::master_test_suite().argc
-boost::unit_test::framework::master_test_suite().argv</programlisting>
-
- <para role="first-line-indented">
- In below example references to the command line arguments are accessible either as an initialization function
- parameters or as members of the master test suite. Both references point to the same values. A test module that
- uses the alternative initialization function specification can only access command line arguments through the
- master test suite.
- </para>
-
- <note>
- <simpara>
- This interface for runtime parameter access is temporary. It's planned to be updated once runtime
- parameters support is redesigned.
- </simpara>
- </note>
-
- <para role="first-line-indented">
- Returning to the free function example, let's modify initialization function to check for absence of any
- test module arguments.
- </para>
-
- <btl-example name="example13">
- <title>Command line access in initialization function</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-organization.master-test-suite-name">
- <title>Naming</title>
- <para role="first-line-indented">
- The master test suite is created with default name "Master Test Suite". There are two methods two
- reset the name to a different value: using the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/>
- and from within the test module initialization function. Former is used for test modules that don't have the
- manually implemented initialization function. Following examples illustrate these methods.
- </para>
-
- <btl-example name="example14">
- <title>Naming master test suite using the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/></title>
-
- <para role="first-line-indented">
- If the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/> is defined, the test module initialization
- function is <link linkend="utf.user-guide.initialization.auto-generation">automatically generated</link> and the
- macro value becomes the name of the master test suite. The name may include spaces.
- </para>
- </btl-example>
-
- <btl-example name="example15">
- <title>Naming master test suite explicitly in the test module initialization function</title>
-
- <para role="first-line-indented">
- Without the <xref linkend="utf.flag.main" endterm="utf.flag.main"/> and the <xref linkend="utf.flag.module"
- endterm="utf.flag.module"/> flags defined, the test module initialization function has to be manually implemented.
- The master test suite name can be reset at any point within this function.
- </para>
- </btl-example>
- </section>
- </section>
- </section>
-
- <section id="utf.user-guide.test-organization.expected-failures">
- <title>Expected failures specification</title>
-
- <para role="first-line-indented">
- While in a perfect world all test assertions should pass in order for a test module to pass, in some situations
- it is desirable to temporarily allow particular tests to fail. For example, where a particular feature is not
- implemented yet and one needs to prepare a library for the release or when particular test fails on some
- platforms. To avoid a nagging red box in regression tests table, you can use the expected failures feature.
- </para>
-
- <para role="first-line-indented">
- This feature allows specifying an expected number of failed assertions per test unit. The value is specified
- during test tree construction, and can't be updated during test execution.
- </para>
-
- <para role="first-line-indented">
- The feature is not intended to be used to check for expected functionality failures. To check that a particular
- input is causing an exception to be thrown use <macroname>BOOST_CHECK_THROW</macroname> family of testing
- tools.
- </para>
-
- <para role="first-line-indented">
- The usage of this feature should be limited and employed only after careful consideration. In general you should
- only use this feature when it is necessary to force a test module to pass without actually fixing the problem.
- Obviously, an excessive usage of expected failures defeats the purpose of the unit test. In most cases it only
- needs be applied temporarily.
- </para>
-
- <para role="first-line-indented">
- You also need to remember that the expected failure specification is per test case. This means that any failed
- assertion within that test case can satisfy the expected failures quota. Meaning it is possible for an
- unexpected failure to occur to satisfy this quota.
- </para>
-
- <note>
- <simpara>
- If an assertion at fault is fixed and passed, while an expected failures specification still present, the test
- case is going to fail, since the number of failures is smaller than expected.
- </simpara>
- </note>
-
- <section id="utf.user-guide.test-organization.manual-expected-failures">
- <title>Usage with manually registered test cases</title>
-
- <para role="first-line-indented">
- To set the value of expected failures for the manually registered test unit pass it as a second argument for the
- test_suite::add call during test unit registration.
- </para>
-
- <btl-example name="example16">
- <title>Expected failures specification for manually registered test case</title>
- </btl-example>
- </section>
- <section id="utf.user-guide.test-organization.auto-expected-failures">
- <title>Usage with automatically registered test cases</title>
-
- <para role="first-line-indented">
- To set the number of expected failures for the automatically registered test unit use the macro
- BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES before the test case definition.
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES" kind="functionlike">
- <macro-parameter name="test_case_name"/>
- <macro-parameter name="number_of_expected_failures"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- You can use this macro both on a file scope and inside a test suite. Moreover you can use it even if name of test
- units coincide in different test suites. Expected failures specification applies to the test unit belonging to the same
- test suite where BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES resides.
- </para>
-
- <btl-example name="example17">
- <title>Expected failures specification for automatically registered test case</title>
- </btl-example>
- </section>
- </section>
-</section>
\ No newline at end of file
Deleted: trunk/libs/test/doc/src/utf.users-guide.test-output.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.users-guide.test-output.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,638 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
- <!ENTITY utf "<acronym>UTF</acronym>">
-]>
-<section id="utf.user-guide.test-output">
- <title>Test Output … or let's see what you got for your money</title>
- <titleabbrev>Test Output </titleabbrev>
-
- <para role="first-line-indented">
- The output produced by a test module is one of the major assets the &utf; brings to users. In comparison with any
- kind of manual/assert based solution the &utf; provide following services:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>All test errors are reported uniformly</simpara>
- <simpara>
- The test execution monitor along with standardized output from all included
- <link linkend="utf.testing-tools">testing tools</link> provides uniform reporting for all errors including fatal
- errors, like memory assess violation and uncaught exceptions.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Detailed information on the source of an error</simpara>
- <simpara>
- The &utf; test tool's based assertion provides as much information as possible about cause of error,
- usually allowing you to deduce what is wrong without entering the debugger or core analysis.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Separation of the test errors description (test log) from the results report summary (test results report)
- </simpara>
- <simpara>
- The information produced during test execution, including all error, warning and info messages from the test
- tools, executed test units notification constitute the test log. By default all entries in the test log are
- directed to the standard output. Once testing is completed the &utf; may produce a summary test report with
- different levels of detail. The test report is by default directed to the standard error output.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Flexibility in what is shown in the output</simpara>
- <simpara>
- The &utf; provides the ability to configure what if shown in both the test log and the test report. The
- configuration is supported both at runtime, during test module invocation and at compile time from within a
- test module.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Flexibility in how output is formatted</simpara>
- <simpara>
- The &utf; provides the ability to configure the format of the test module output. At the moment only 2 formats
- are supported by the &utf; itself, the well defined public interface allows you to customize an output for
- your purposes almost any way you want.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <section id="utf.user-guide.test-output.log">
- <title>Test log output</title>
- <titleabbrev>Test log</titleabbrev>
-
- <para role="first-line-indented">
- The test log is produced during the test execution. All entries in the test log are assigned a particular log
- level. Only the entries with level that exceeds the <firstterm>active log level threshold</firstterm> actually
- appear in the test log output. Log levels are arranged by the "importance" of the log entries. Here is
- the list of all levels in order of increasing "importance":
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>Success information messages</simpara>
- <simpara>
- This category includes messages that provide information on successfully passed assertions
- </simpara>
- </listitem>
- <listitem>
- <simpara>Test tree traversal notifications</simpara>
- <simpara>
- This category includes messages that are produced by the &utf; core and indicate which test suites/cases are
- currently being executed or skipped
- </simpara>
- </listitem>
- <listitem>
- <simpara>General information messages</simpara>
- <simpara>
- This category includes general information massages produced in most cases by a test module author using the
- macro <macroname>BOOST_TEST_MESSAGE</macroname>.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Warning messages</simpara>
- <simpara>
- This category includes messages produced by failed warning level assertions.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Non fatal error messages</simpara>
- <simpara>
- This category includes messages produced by failed check level assertions
- </simpara>
- </listitem>
- <listitem>
- <simpara>Uncaught C++ exceptions notifications</simpara>
- <simpara>
- This category includes messages that are produced by the &utf; and provide detailed information on the C++
- exceptions uncaught by the test case body.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Non-fatal system error</simpara>
- <simpara>
- This category includes messages that are produced by the &utf; itself and provides information about caught
- non-fatal system error. For example it includes messages produced in the case of test case timeout or if
- floating point values calculation errors are caught.
- </simpara>
- </listitem>
- <listitem>
- <simpara>Fatal system error</simpara>
- <simpara>
- This category includes messages produced by failed require level assertions and by the &utf; itself in case of
- abnormal test case termination.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <note>
- <simpara>
- The active log level works namely as threshold, not as selector. For the given active log level threshold, all
- test log entries with "importance" higher than threshold are enabled and all test log entries with
- "importance" below threshold are disabled.
- </simpara>
- </note>
-
- <para role="first-line-indented">
- In addition to the levels described above the test log defines two special log levels. The current log level can
- be set to:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>All messages</simpara>
- <simpara>
- If active log level threshold is set to this value, all test log entries appear in the output. In practice
- this is equivalent to setting the active log level threshold to "success information messages"
- </simpara>
- </listitem>
- <listitem>
- <simpara>Nothing</simpara>
- <simpara>
- If the active log level threshold is set to this value, none of test log entries appear in the output. This log level
- is used to execute a "silent" test that doesn't produce any test log and only generates a result code indicating whether test failed or passed.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- By default the active log level threshold is set to "non fatal error messages" and the test log output
- is generated in the human readable format. The active log level threshold and the output format can be configured
- at runtime during a test module invocation and at compile time from within a test module using the test log
- public interfaces. For example, for automated test module output processing it might be more convenient to use
- the XML based format.
- </para>
-
- <para role="first-line-indented">
- In most cases The &utf; can't provide an exact location, where system error occurs or uncaught C++ exception
- is thrown from. To be able to pinpoint it as close as possible the &utf; keeps track of checkpoints - the
- location a test module passed through. A test case entrance and exit points, a test tool invocation point the
- &utf; tracks automatically. Any other checkpoints should be entered by you manually. The test log provides two
- macros for this purpose: <macroname>BOOST_TEST_CHECKPOINT</macroname> - to specify a "named" checkpoint
- and <macroname>BOOST_TEST_PASSPOINT</macroname> - to specify an "unnamed" checkpoint.
- </para>
-
- <section id="utf.user-guide.test-output.log.testing-tool-args">
- <title>Logging tool arguments</title>
-
- <para role="first-line-indented">
- Most of the <link linkend="utf.testing-tools">testing tools</link> print values of their arguments to the output
- stream in some form of log statement. If arguments type does not support <code>operator<<(std::ostream&,
- ArgumentType const&)</code> interface you will get a compilation error. You can either implement above
- interface or prohibit the <link linkend="utf.testing-tools">testing tools</link> from logging argument values for
- specified type. To do so use following statement on file level before first test case that includes statement
- failing to compile:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_DONT_PRINT_LOG_VALUE" kind="functionlike">
- <macro-parameter name="ArgumentType"/>
- </macro>
- </inline-synopsis>
-
- <btl-example name="example32">
- <title>BOOST_TEST_DONT_PRINT_LOG_VALUE usage</title>
-
- <simpara>
- Try to comment out BOOST_TEST_DONT_PRINT_LOG_VALUE statement and you end up with compile time error.
- </simpara>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.runtime-config">
- <title>Runtime configuration</title>
-
- <para role="first-line-indented">
- The active log level threshold can be configured at runtime using the parameter
- <link linkend="utf.user-guide.runtime-config.reference">log_level</link>. The test log output format can be
- selected using either parameter <link linkend="utf.user-guide.runtime-config.reference">log_format</link> or the
- parameter <link linkend="utf.user-guide.runtime-config.reference">output_format</link>.
- </para>
- </section>
-
- <section id="utf.user-guide.test-output.log.BOOST_TEST_MESSAGE">
- <title>BOOST_TEST_MESSAGE</title>
-
- <para role="first-line-indented">
- The macro BOOST_TEST_MESSAGE is intended to be used for the purpose of injecting an additional message into the
- &utf; test log. These messages are not intended to indicate any error or warning conditions, but rather as
- information/status notifications. The macro signature is as follows:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_MESSAGE" kind="functionlike">
- <macro-parameter name="test_message"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The test_message argument can be as simple as C string literal or any custom expression that you can produce
- with in a manner similar to standard iostream operation.
- </para>
-
- <important>
- <simpara>
- Messages generated by this tool do not appear in test log output with default value of the active log level
- threshold. For these messages to appear the active log level threshold has to be set to a value below or equal
- to "message".
- </simpara>
- </important>
-
- <btl-example name="example21">
- <title>BOOST_TEST_MESSAGE usage</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.BOOST_TEST_CHECKPOINT">
- <title>BOOST_TEST_CHECKPOINT</title>
-
- <para role="first-line-indented">
- The macro BOOST_TEST_CHECKPOINT is intended to be used to inject "named" checkpoint position. The
- macro signature is as follows:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_CHECKPOINT" kind="functionlike">
- <macro-parameter name="checkoint_message"/>
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- The message formatted at the checkpoint position is saved and reported by the exception logging functions (if any
- occurs). Similarly to the <macroname>BOOST_TEST_MESSAGE</macroname> the message can be formatted from any standard
- output stream compliant components.
- </para>
-
- <btl-example name="example22">
- <title>BOOST_TEST_CHECKPOINT usage</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.BOOST_TEST_PASSPOINT">
- <title>BOOST_TEST_PASSPOINT</title>
-
- <para role="first-line-indented">
- The macro BOOST_TEST_PASSPOINT is intended to be used to inject an "unnamed" checkpoint position. The
- macro signature is as follows:
- </para>
-
- <inline-synopsis>
- <macro name="BOOST_TEST_PASSPOINT" kind="functionlike">
- </macro>
- </inline-synopsis>
-
- <para role="first-line-indented">
- Unlike the macro <macroname>BOOST_TEST_CHECKPOINT</macroname> this macro doesn't require any message to be
- supplied with it. It's just a simple "been there" marker that records file name and line number
- code passes through.
- </para>
-
- <btl-example name="example23">
- <title>BOOST_TEST_PASSPOINT usage</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.FPT">
- <title>Logging floating point type numbers</title>
-
- <para role="first-line-indented">
- It may appear that floating-point numbers are displayed by the &utf; with an excessive number of decimal digits.
- However the number of digits shown is chosen to avoid apparently nonsensical displays like <code>[1.00000 != 1.00000]</code>
- when comparing exactly unity against a value which is increased by just one least significant binary digit using
- the default precision for float of just 6 decimal digits, given by
- <classname>std::numeric_limits</classname><float>::digits10. The function used for the number of decimal
- digits displayed is that proposed for a future C++ Standard,
- <ulink url="http://www2.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1822.pdf">A Proposal to add a max
- significant decimal digits value</ulink>, to be called <classname>std::numeric_limits</classname>::max_digits10();.
- For 32-bit floats, 9 decimal digits are needed to ensure a single bit change produces a different decimal digit
- string.
- </para>
-
- <para role="first-line-indented">
- So a much more helpful display using 9 decimal digits is thus:
- <computeroutput>[1.00000000 != 1.00000012]</computeroutput> showing that the two values are in fact different.
- </para>
-
- <para role="first-line-indented">
- For <acronym>IEEE754</acronym> 32-bit float values - 9 decimal digits are shown. For 64-bit <acronym>IEEE754</acronym> double - 17 decimal digits. For
- <acronym>IEEE754</acronym> extended long double using 80-bit - 21 decimal digits. For <acronym>IEEE754</acronym> quadruple long double 128-bit, and Sparc
- extended long double 128-bit - 36 decimal digits. For floating-point types, a convenient formula to calculate
- max_digits10 is: 2 + <classname>std::numeric_limits</classname><FPT>::digits * 3010/10000;
- </para>
-
- <note>
- <simpara>
- Note that a user defined floating point type UDFPT must define
- <classname>std::numeric_limits</classname><UDFPT>::is_specialized = true and provide an appropriate value
- for <classname>std::numeric_limits</classname><UDFPT>::digits, the number of bits used for the significand
- or mantissa. For example, for the Sparc extended long double 128, 113 bits are used for the significand (one of
- which is implicit).
- </simpara>
- </note>
- </section>
-
- <section id="utf.user-guide.test-output.log.human-readabe-format">
- <title>Human readable log output format</title>
- <titleabbrev>Human readable format</titleabbrev>
-
- <para role="first-line-indented">
- The human readable log format is designed to closely match an errors description produced by the Microsoft family
- of C++ compilers. This format allows jumping to the error location, if test module output is redirected into IDE
- output window. The rest of the log messages are designed to produce the most human friendly description of the
- events occurring in test module. This is a default format generated by test modules.
- </para>
-
- <para role="first-line-indented">
- Here the list of events along with corresponding message and the condition that has to be satisfied for it to appear
- in the output.
- </para>
-
- <segmentedlist>
- <?dbhtml list-presentation="list"?>
-
- <segtitle>Event</segtitle>
- <segtitle>Condition</segtitle>
- <segtitle>Output</segtitle>
-
- <seglistitem>
- <seg>On testing start</seg>
- <seg>threshold != log_nothing</seg>
- <seg>
- <computeroutput><literallayout>Running <userinput>total number of test cases</userinput> test case(s) …</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On testing start</seg>
- <seg>threshold != log_nothing and show_build_info is set</seg>
- <seg>
- <computeroutput><literallayout>Platform: $BOOST_PLATFORM
-Compiler: $BOOST_COMPILER
-STL : $BOOST_STDLIB
-Boost : $BOOST_VERSION</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On abnormal testing termination</seg>
- <seg>threshold <= log_messages</seg>
- <seg>
- <computeroutput><literallayout>Test is aborted</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On test unit start</seg>
- <seg>threshold <= log_test_units</seg>
- <seg>
- <computeroutput><literallayout>Entering test <userinput>test unit type</userinput> <userinput>test unit name</userinput></literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On test unit end</seg>
- <seg>threshold <= log_test_units; testing time is reported only if elapsed time is more than 1 mks.</seg>
- <seg>
- <computeroutput><literallayout>Leaving test <userinput>test unit type</userinput> <userinput>test unit name</userinput>; testing time <userinput>value</userinput></literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On skipped test unit</seg>
- <seg>threshold <= log_test_units</seg>
- <seg>
- <computeroutput><literallayout>Test <userinput>test unit type</userinput> <userinput>test unit name</userinput> is skipped</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On uncaught C++ exception</seg>
- <seg>threshold <= log_cpp_exception_errors. Checkpoint message is reported only if provided</seg>
- <seg>
- <computeroutput><literallayout>unknown location(0): fatal error in <userinput>test case name</userinput>: <userinput>explanation</userinput>
-<userinput>last checkpoint location</userinput>: last checkpoint: <userinput>checkpoint message</userinput></literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On resumable system error</seg>
- <seg>threshold <= log_system_errors. Checkpoint message is reported only if provided</seg>
- <seg>
- <computeroutput><literallayout>unknown location(0): fatal error in <userinput>test case name</userinput>: <userinput>explanation</userinput>
-<userinput>last checkpoint location</userinput>: last checkpoint: <userinput>checkpoint message</userinput></literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On fatal system error</seg>
- <seg>threshold <= log_fatal_errors. Checkpoint message is reported only if provided</seg>
- <seg>
- <computeroutput><literallayout>unknown location(0): fatal error in <userinput>test case name</userinput>: <userinput>explanation</userinput>
-<userinput>last checkpoint location</userinput>: last checkpoint: <userinput>checkpoint message</userinput></literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On passed test assertion</seg>
- <seg>threshold <= log_successful_tests</seg>
- <seg>
- <computeroutput><literallayout><userinput>assertion location</userinput>: info: check<userinput>assertion expression</userinput> passed</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On failed WARNING level test assertion</seg>
- <seg>threshold <= log_warnings</seg>
- <seg>
- <computeroutput><literallayout><userinput>assertion location</userinput>: warning in <userinput>test case name</userinput>: condition <userinput>assertion description</userinput> is not satisfied</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On failed CHECK level test assertion</seg>
- <seg>threshold <= log_all_errors</seg>
- <seg>
- <computeroutput><literallayout><userinput>assertion location</userinput>: error in <userinput>test case name</userinput>: check <userinput>assertion description</userinput> failed</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On failed REQUIRE level test assertion</seg>
- <seg>threshold <= log_fatal_errors</seg>
- <seg>
- <computeroutput><literallayout><userinput>assertion location</userinput>: fatal error in <userinput>test case name</userinput>: critical check <userinput>assertion description</userinput> failed</literallayout></computeroutput>
- </seg>
- </seglistitem>
-
- <seglistitem>
- <seg>On test log message</seg>
- <seg>threshold <= log_messages</seg>
- <seg>
- <computeroutput><literallayout><userinput>Message content</userinput></literallayout></computeroutput>
- </seg>
- </seglistitem>
- </segmentedlist>
-
- <para role="first-line-indented">
- Advanced <link linkend="utf.testing-tools">testing tools</link> may produce more complicated error messages.
- </para>
- </section>
-
- <section id="utf.user-guide.test-output.log.xml-format">
- <title>XML based log output format</title>
-
- <para role="first-line-indented">
- This log format is designed for automated test results processing. The test log output XML schema depends on the
- active log level threshold.
- </para>
-
- <!-- TO FIX -->
- </section>
-
- <section id="utf.user-guide.test-output.log.ct-config">
- <title>Compile time configuration</title>
- <para role="first-line-indented">
- While many test log configuration tasks can be performed at runtime using predefined framework parameters, the
- &utf; provides a compile time interface as well. The interface gives you full power over what, where and how to
- log. The interface is provided by singleton class <classname>boost::unit_test::unit_test_log_t</classname> and is
- accessible through local file scope reference to single instance of this class: boost::unit_test::unit_test_log.
- </para>
-
- <section id="utf.user-guide.test-output.log.ct-config.output-stream">
- <title>Log output stream redirection</title>
-
- <para role="first-line-indented">
- If you want to redirect the test log output stream into something different from std::cout use the following
- interface:
- </para>
-
- <programlisting>boost::unit_test::unit_test_log.set_stream( std::ostream& str );</programlisting>
-
- <para role="first-line-indented">
- You can reset the output stream at any time both during the test module initialization and from within test
- cases. There are no limitations on number of output stream resets either.
- </para>
-
- <btl-example name="example50">
- <title>Test log output redirection</title>
-
- <warning>
- <simpara>
- If you redirect test log output stream from global fixture setup, you are
- <emphasis role="bold">required</emphasis> to reset it back to std::cout during teardown to prevent dangling
- references access
- </simpara>
- </warning>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.ct-config.log-level">
- <title>Log level configuration</title>
-
- <para role="first-line-indented">
- If you need to enforce specific log level from within your test module use the following interface:
- </para>
-
- <programlisting>boost::unit_test::unit_test_log.set_threshold_level( boost::unit_test::log_level );</programlisting>
-
- <para role="first-line-indented">
- In regular circumstances you shouldn't use this interface, since you not only override default log level, but also
- the one supplied at test execution time. Prefer to use runtime parameters for log level selection.
- </para>
-
- <btl-example name="example51">
- <title>Compile time log level configuration</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.ct-config.log-format">
- <title>Predefined log format selection</title>
-
- <para role="first-line-indented">
- The select at compile time the log format from the list of the formats supplied by the &utf;
- </para>
-
- <programlisting>boost::unit_test::unit_test_log.set_format( boost::unit_test::output_format );</programlisting>
-
- <para role="first-line-indented">
- In regular circumstances you shouldn't use this interface. Prefer to use runtime parameters for predefined log
- format selection.
- </para>
-
- <btl-example name="example52">
- <title>Compile time log format selection</title>
- </btl-example>
- </section>
-
- <section id="utf.user-guide.test-output.log.ct-config.log-formatter">
- <title>Custom log format support</title>
-
- <!-- TO FIX -->
- </section>
- </section>
- </section>
-
- <section id="utf.user-guide.test-output.results-report">
- <title>Test report output</title>
- <section id="utf.user-guide.test-output.results-report.runtime-config">
- <title>Runtime configuration</title>
- <!-- TO FIX -->
- </section>
-
- <section id="utf.user-guide.test-output.results-report.ct-config">
- <title>Compile time configuration</title>
-
- <section id="utf.user-guide.test-output.results-report.ct-config.output-stream">
- <title>Report output stream redirection and access</title>
- <!-- TO FIX -->
- </section>
-
- <section id="utf.user-guide.test-output.results-report.ct-config.report-level">
- <title>Report level configuration</title>
- <!-- TO FIX -->
- </section>
-
- <section id="utf.user-guide.test-output.results-report.ct-config.report-format">
- <title>Predefined report format selection</title>
- <!-- TO FIX -->
- </section>
-
- <section id="utf.user-guide.test-output.results-report.ct-config.report-formatter">
- <title>Custom report format support</title>
- <!-- TO FIX -->
- </section>
-
- </section>
- </section>
-
- <section id="utf.user-guide.test-output.progress">
- <title>Test progress display</title>
- <titleabbrev>Progress display</titleabbrev>
- <para role="first-line-indented">
- In case if the test module involves lengthy computation split among multiple test cases you may be interested in
- progress monitor. The test runners supplied with the &utf; support simple text progress display, implemented based
- on <classname>boost::progress_display</classname><footnote>The &utf; interfaces allow implementing
- an advanced GUI based test runner with arbitrary progress display controls</footnote>. The progress display output
- is enabled using the &utf; parameter <link linkend="utf.user-guide.runtime-config.parameters">show_progress</link>.
- </para> <!-- TO FIX: what's wrong with footnode? -->
-
-
- <para role="first-line-indented">
- The &utf; has no ability to estimate how long the test case execution is going to take and the manual test
- progress update is not supported at this point. The &utf; tracks the progress on test case level. If you want to
- see more frequent progress update, you need to split the test into multiple test cases.
- </para>
-
- <para role="first-line-indented">
- In default configuration both test log and test progress outputs are directed into standard output stream. Any test
- log messages are going to interfere with test progress display. To prevent this you can either set log level to
- lower level or redirect either test log or test progress output into different stream during test module
- initialization. Use following interface to redirect test progress output:
- </para>
-
- <programlisting>boost::unit_test::progress_monitor.set_stream( std::ostream& )</programlisting>
-
- <btl-example name="example49">
- <title>Progress report for the test module with large amount of test cases</title>
- </btl-example>
- </section>
-</section>
\ No newline at end of file
Deleted: trunk/libs/test/doc/src/utf.users-guide.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.users-guide.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
+++ (empty file)
@@ -1,698 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
- <!ENTITY utf "<acronym>UTF</acronym>">
-]>
-<section id="utf.user-guide" last-revision="$Date$">
- <title>Unit Test Framework: User's guide</title><titleabbrev>User's guide</titleabbrev>
-
- <section id="utf.user-guide.intro">
- <title>Introduction … or what's your name?</title><titleabbrev>Introduction</titleabbrev>
-
- <para role="first-line-indented">
- Without further ado, let's define terms regularly used by the &utf;.
- </para>
- <variablelist>
- <?dbhtml term-width="16%" list-width="100%"?>
- <?dbhtml term-separator=":"?>
- <?dbhtml table-summary="utf terms definition"?>
-
- <varlistentry id="test-module.def">
- <term><firstterm>The test module</firstterm></term>
- <listitem>
- <simpara>
- This is a single binary that performs the test. Physically a test module consists of one or more test source files,
- which can be built into an executable or a dynamic library. A test module that consists of a single test source
- file is called <firstterm id="single-file-test-module.def">single-file test module</firstterm>. Otherwise
- it's called <firstterm id="multi-file-test-module.def">multi-file test module</firstterm>. Logically a test
- module consists of four parts: <link linkend="test-setup.def">test setup</link> (or test initialization),
- <link linkend="test-body.def">test body</link>, <link linkend="test-cleanup.def">test cleanup</link> and
- <link linkend="test-runner.def">test runner</link>. The test runner part is optional. If a test module is built as
- an executable the test runner is built-in. If a test module is built as a dynamic library, it is run by an
- external test runner.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-body.def">
- <term><firstterm>The test body</firstterm></term>
- <listitem>
- <simpara>
- This is the part of a test module that actually performs the test.
- Logically test body is a collection of <link linkend="test-assertion.def">test assertions</link> wrapped in
- <link linkend="test-case.def">test cases</link>, which are organized in a <link linkend="test-tree.def">test tree
- </link>.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-tree.def">
- <term><firstterm>The test tree</firstterm></term>
- <listitem>
- <simpara>
- This is a hierarchical structure of <link linkend="test-suite.def">test suites</link> (non-leaf nodes) and
- <link linkend="test-case.def">test cases</link> (leaf nodes).
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-unit.def">
- <term><firstterm>The test unit</firstterm></term>
- <listitem>
- <simpara>
- This is a collective name when referred to either <link linkend="test-suite.def">test suite</link> or
- <link linkend="test-case.def">test case</link>
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-assertion.def">
- <term><firstterm>Test assertion</firstterm></term>
- <listitem>
- <simpara>
- This is a single binary condition (binary in a sense that is has two outcomes: pass and fail) checked
- by a test module.
- </simpara>
- <simpara>
- There are different schools of thought on how many test assertions a test case should consist of. Two polar
- positions are the one advocated by TDD followers - one assertion per test case; and opposite of this - all test
- assertions within single test case - advocated by those only interested in the first error in a
- test module. The &utf; supports both approaches.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-case.def">
- <term><firstterm>The test case</firstterm></term>
- <listitem>
- <simpara>
- This is an independently monitored function within a test module that
- consists of one or more test assertions. The term "independently monitored" in the definition above is
- used to emphasize the fact, that all test cases are monitored independently. An uncaught exception or other normal
- test case execution termination doesn't cause the testing to cease. Instead the error is caught by the test
- case execution monitor, reported by the &utf; and testing proceeds to the next test case. Later on you are going
- to see that this is on of the primary reasons to prefer multiple small test cases to a single big test function.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-suite.def">
- <term><firstterm>The test suite</firstterm></term>
- <listitem>
- <simpara>
- This is a container for one or more test cases. The test suite gives you an ability to group
- test cases into a single referable entity. There are various reasons why you may opt to do so, including:
- </simpara>
- <itemizedlist>
- <listitem>
- <simpara>To group test cases per subsystems of the unit being tested.</simpara>
- </listitem>
- <listitem>
- <simpara>To share test case setup/cleanup code.</simpara>
- </listitem>
- <listitem>
- <simpara>To run selected group of test cases only.</simpara>
- </listitem>
- <listitem>
- <simpara>To see test report split by groups of test cases</simpara>
- </listitem>
- <listitem>
- <simpara>To skip groups of test cases based on the result of another test unit in a test tree.</simpara>
- </listitem>
- </itemizedlist>
- <simpara>
- A test suite can also contain other test suites, thus allowing a hierarchical test tree structure to be formed.
- The &utf; requires the test tree to contain at least one test suite with at least one test case. The top level
- test suite - root node of the test tree - is called the master test suite.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-setup.def">
- <term><firstterm>The test setup</firstterm></term>
- <listitem>
- <simpara>
- This is the part of a test module that is responsible for the test
- preparation. It includes the following operations that take place prior to a start of the test:
- </simpara>
- <itemizedlist>
- <listitem>
- <simpara>
- The &utf; initialization
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Test tree construction
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Global test module setup code
- </simpara>
- </listitem>
- </itemizedlist>
- <simpara>
- Per test case" setup code, invoked for every test case it's assigned to, is also attributed to the
- test initialization, even though it's executed as a part of the test case.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-cleanup.def">
- <term><firstterm>The test cleanup</firstterm></term>
- <listitem>
- <simpara>
- This is the part of test module that is responsible for cleanup operations.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-fixture.def">
- <term><firstterm>The test fixture</firstterm></term>
- <listitem>
- <simpara>
- Matching setup and cleanup operations are frequently united into a single entity called test fixture.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-runner.def">
- <term><firstterm>The test runner</firstterm></term>
- <listitem>
- <simpara>
- This is an "executive manager" that runs the show. The test runner's functionality should include
- the following interfaces and operations:
- </simpara>
- <itemizedlist>
- <listitem>
- <simpara>
- Entry point to a test module. This is usually either the function main() itself or single function that can be
- invoked from it to start testing.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Initialize the &utf; based on runtime parameters
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Select an output media for the test log and the test results report
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Select test cases to execute based on runtime parameters
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Execute all or selected test cases
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Produce the test results report
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Generate a test module result code.
- </simpara>
- </listitem>
- </itemizedlist>
- <para role="first-line-indented">
- An advanced test runner may provide additional features, including interactive <acronym>GUI</acronym> interfaces,
- test coverage and profiling support.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="test-log.def">
- <term><firstterm>The test log</firstterm></term>
- <listitem>
- <simpara>
- This is the record of all events that occur during the testing.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry id="test-results-report.def">
- <term><firstterm>The test results report</firstterm></term>
- <listitem>
- <simpara>
- This is the report produced by the &utf; after the testing is completed, that indicates which test cases/test
- suites passed and which failed.
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist >
- </section>
-
- <section id="utf.user-guide.usage-variants">
- <title>The &utf; usage variants … or the <ulink url="http://en.wikipedia.org/wiki/Buridan's_ass">Buridan's donkey</ulink> parable</title>
- <titleabbrev>Usage variants</titleabbrev>
-
- <para role="first-line-indented">
- The &utf; presents you with 4 different variants how it can be used.
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara><link linkend="utf.user-guide.static-lib-variant">The static library variant</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.dynamic-lib-variant">The dynamic library variant</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.single-header-variant">The single-header variant</link></simpara>
- </listitem>
- <listitem>
- <simpara><link linkend="utf.user-guide.extern-test-runner-variant">The external test runner variant</link></simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- Unlike the Buridan's donkey though, you shouldn't have problems deciding which one to use, since there are
- clear reasons why would you prefer each one.
- </para>
-
- <para role="first-line-indented">
- In most cases to compile a test module based on the &utf; all you need to include is just the single header
- <filename class="headerfile">boost/test/unit_test.hpp</filename>. This header includes internally most of the other
- headers that contains the &utf; definitions. Some advanced features, like the floating point comparison or the
- logged expectations testing, are defined in independent headers and need to be included explicitly.
- </para>
-
- <section id="utf.user-guide.static-lib-variant">
- <title>The static library variant of the &utf;</title><titleabbrev>Static library</titleabbrev>
- <para role="first-line-indented">
- The &utf; can be built into a static library. If you opt to link a test module with the
- <link linkend="utf.compilation.standalone">standalone static library</link>, this usage is called the static library
- variant of the &utf;.
- </para>
-
- <para role="first-line-indented">
- The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
- module</link> initialization function that matches one of the two specifications depending on the compilation flag
- <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required
- to match the original specification. If you define the flag <xref linkend="utf.flag.alt-init-api"
- endterm="utf.flag.alt-init-api"/> during a test module compilation you are required to use the alternative
- initialization function specification. The &utf; provides an ability to
- <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
- initialization function with correct specification if no custom initialization is required by a test module.
- </para>
-
- <important>
- <simpara>
- If you opted to use an alternative initialization API, for a test module to be able to link with prebuilt library,
- the flag <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> has to be defined both during
- library and a test module compilation.
- </simpara>
- </important>
- </section>
-
- <section id="utf.user-guide.dynamic-lib-variant">
- <title>The dynamic library variant of the &utf;</title>
- <titleabbrev>Dynamic library</titleabbrev>
-
- <para role="first-line-indented">
- In the project with large number of test modules <link linkend="utf.user-guide.dynamic-lib-variant">the static
- library</link> variant of the &utf; may cause you to waste a lot of disk space, since the &utf; is linked
- statically with every test module. The solution is to link with the &utf; built into a dynamic library. If you opt
- to link a test module with the prebuilt dynamic library, this usage is called the dynamic library variant of the
- &utf;. This variant requires you to define the flag <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/>
- either in a makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
- inclusion.
- </para>
-
- <para role="first-line-indented">
- The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
- module</link> initialization function that matches the alternative initialization function signature. The &utf;
- provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link>
- an empty test module initialization function with correct signature if no custom initialization is required by a
- test module.
- </para>
-
- <note>
- <simpara>
- The name of the test module initialization function is not enforced, since the function is passed as an argument
- to the test runner.
- </simpara>
- </note>
- </section>
-
- <section id="utf.user-guide.single-header-variant">
- <title>The single-header variant of the &utf;</title>
- <titleabbrev>Single header</titleabbrev>
-
- <para role="first-line-indented">
- If you prefer to avoid the <link linkend="utf.compilation.standalone">standalone library compilation</link>, you
- should use the single-header variant of the &utf;. This variant is implemented, as it follows from its name, in
- the single header <filename class="headerfile">boost/test/included/unit_test.hpp</filename>. An inclusion of
- the header causes the complete implementation of the &utf; to be included as a part of a test module's
- source file. The header <filename class="headerfile">boost/test/unit_test.hpp</filename> doesn't have to be
- included anymore. You don't have to worry about disabling <link linkend="utf.compilation.auto-linking">
- auto-linking</link> feature either. It's done in the implementation header already. This variant
- can't be used with the <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/>.
- Otherwise it's almost identical from the usage prospective to the static library variant of the &utf;.
- In fact the only difference is the name of the include file:
- <filename class="headerfile">boost/test/included/unit_test.hpp</filename> instead of
- <filename class="headerfile">boost/test/unit_test.hpp</filename>.
- </para>
-
- <para role="first-line-indented">
- The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
- module</link> initialization function that matches one of the two specifications depending on the compilation flag
- <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required to
- match the original specification. If you define the flag
- <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> during a test module compilation you are
- required to use the alternative initialization function specification. The &utf; provides an ability to
- <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
- initialization function with correct specification if no custom initialization is required by a test module.
- </para>
- </section>
-
- <section id="utf.user-guide.extern-test-runner-variant">
- <title>The external test runner variant of the &utf;</title>
- <titleabbrev>External test runner</titleabbrev>
-
- <para role="first-line-indented">
- All other usage variants employ the build-in test runners. If you plan to use an external test runner with your
- test module you need to build it as a dynamic library. This usage of the &utf; is called the external test runner
- variant of the &utf;. The variant requires you to define the flag
- <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/> either in a makefile or before the header
- <filename class="headerfile">boost/test/unit_test.hpp</filename> inclusion. An external test runner utility is
- required to link with dynamic library.
- </para>
-
- <para role="first-line-indented">
- If an external test runner is based on the test runner built in to the dynamic library (like the standalone
- boost_test_runner utility supplied by the &utf;), it requires you to implement the <link linkend="test-module.def">
- test module</link> initialization function that matches the alternative initialization function signature. The
- &utf; provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate
- </link> an empty test module initialization function with correct signature if no custom initialization is required
- by a test module.
- </para>
-
- <note>
- <simpara>
- An advanced test runner doesn't have to be based on the build-in one and may require a different
- test module initialization function signature and/or name.
- </simpara>
- </note>
- </section>
- </section>
-
- <section id="utf.user-guide.test-runners">
- <title>The supplied test runners … or where is the entrance?</title>
- <titleabbrev>Supplied test runners</titleabbrev>
-
- <para role="first-line-indented">
- All usage variants of the &utf;, excluding the
- <link linkend="utf.user-guide.external-test-runner">external test runner</link>, supply the test runner in a form of
- free function named unit_test_main with the following signature:
- </para>
-
- <programlisting>int unit_test_main( init_unit_test_func init_func, int argc, char* argv[] );</programlisting>
-
- <para role="first-line-indented">
- To invoke the test runner you are required to supply the pointer to the <link linkend="test-module.def">test module</link>
- initialization function as the first argument to the test runner function. In majority of the cases this function is
- invoked directly from test executable entry point - function main(). In most usage variants the &utf; can
- automatically generate default function main() implementation as either part of the library or test module itself.
- Since the function main needs to refer to the initialization function by name, it is predefined by the default
- implementation and you are required to match both specific signature and name, when implementing initialization
- function. If you for any reason prefer more flexibility you can opt to implement the function main() yourself, in
- which case it's going to be your responsibility to invoke the test runner, but the initialization function name is
- not enforces the &utf;. See below for flags that needs to be defined/undefined in each usage variant to enable this.
- </para>
-
- <warning>
- <simpara>
- In spite syntactic similarity the signatures of the test runner function in fact are different for different usage
- variants. The cause is different signature of the test module initialization function referred by the
- <link linkend="utf.user-guide.initialization.signature-typedef">typedef init_unit_test_func</link>. This makes static
- and dynamic library usage variants incompatible and they can't be easily switched on a fly.
- </simpara>
- </warning>
-
- <section id="utf.user-guide.static-lib-runner">
- <title>Static library variant of the &utf;</title>
- <titleabbrev>Static library</titleabbrev>
-
- <para role="first-line-indented">
- By default this variant supplies the function main() as part of static library. If this is for any reason undesirable
- you need to define the flag <xref linkend="utf.flag.no-main" endterm="utf.flag.no-main"/> during the library
- compilation and the function main() implementation won't be generated.
- </para>
-
- <para role="first-line-indented">
- In addition to the <link linkend="utf.user-guide.static-lib-variant">initialization function signature requirement</link>
- default function main() implementation assumes the name of initialization function is init_unit_test_suite
- </para>
-
- </section>
-
- <section id="utf.user-guide.dynamic-lib-runner">
- <title>Dynamic library variant of the &utf;</title>
- <titleabbrev>Dynamic library</titleabbrev>
-
- <para role="first-line-indented">
- Unlike the static library variant function main() can't reside in the dynamic library body. Instead this variant
- supplies default function main() implementation as part of the header
- <filename class="headerfile">boost/test/unit_test.hpp</filename> to be generated as part of your test file body.
- The function main() is generated only if either the <xref linkend="utf.flag.main" endterm="utf.flag.main"/> or
- the <xref linkend="utf.flag.module" endterm="utf.flag.module"/> flags are defined during a test module compilation.
- For <link linkend="single-file-test-module.def">single-file test module</link> flags can be defined either in a
- test module's makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
- inclusion. For a <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/> flags can't
- be defined in makefile and have to be defined in only one of the test files to avoid duplicate copies of the
- function main().
- </para>
-
- <important>
- <simpara>
- The same flags also govern generation of an empty
- <link linkend="utf.user-guide.initialization">test module initialization function</link>. This means that if you
- need to implement either function main() or initialization function manually, you can't define the above flags
- and are required to manually implement both of them.
- </simpara>
- </important>
- </section>
-
- <section id="utf.user-guide.single-header-runner">
- <title>Single-header variant of the &utf;</title>
- <titleabbrev>Single header</titleabbrev>
-
- <para role="first-line-indented">
- By default this variant supplies function main() as part of the header
- <filename class="headerfile">boost/test/included/unit_test.hpp</filename> to be generated as part of your test file
- body. If this is for any reason undesirable you need to define the flag
- <xref linkend="utf.flag.no-main" endterm="utf.flag.no-main"/> during test module compilation and the function main()
- implementation won't be generated.
- </para>
- </section>
-
- <section id="utf.user-guide.external-test-runner">
- <title>External test runner variant of the &utf;</title>
- <titleabbrev>External test runner</titleabbrev>
-
- <para role="first-line-indented">
- The external test runner variant of the &utf; supplies the test runner in a form of standalone utility
- boost_test_runner. You are free to implement different, more advanced, test runners that can be used with this
- variant.
- </para>
-
- <simpara>
- <!-- TO FIX -->
- </simpara>
- </section>
-
- <section id="utf.user-guide.runners-exit-status">
- <title>Generated exit status values</title>
-
- <para role="first-line-indented">
- Once testing is finished, all supplied test runners report the results and returns an exit status value. Here are
- the summary of all possible generated values:
- </para>
-
- <table id="utf.user-guide.runners-exit-status-summary">
- <title>Generated exit status values</title>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
- <thead>
- <row>
- <entry>Value</entry>
- <entry>Meaning</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>boost::exit_success</entry>
- <entry>
- No errors occurred during the test or the success result code was explicitly requested with the no_result_code
- parameter.
- </entry>
- </row>
- <row>
- <entry>boost::exit_test_failure</entry>
- <entry>
- Non-fatal errors detected and no uncaught exceptions were thrown during testing or the &utf; fails during
- initialization.
- </entry>
- </row>
- <row>
- <entry>boost::exit_exception_failure</entry>
- <entry>
- Fatal errors were detected or uncaught exceptions thrown during testing.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- <section id="utf.user-guide.initialization">
- <title>Test module initialization … or ready, set …</title>
- <titleabbrev>Test module initialization</titleabbrev>
-
- <para role="first-line-indented">
- There are two tasks that you may need to perform before actual testing can start:
- </para>
-
- <itemizedlist>
- <listitem>
- <simpara>
- The test tree needs to be built (unless you are using automated test units registration).
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Custom test module initialization needs to be performed. This includes
- initialization of the code under test and custom tune-up of the &utf; parameters (for example the test log or the
- test results report output streams redirection).
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para role="first-line-indented">
- The function dedicated for this purpose is called the test module initialization function. Alternatively you can
- employ global fixtures, covered in details, including differences in two approaches, in
- <xref linkend="utf.user-guide.fixture"/>.
- </para>
-
- <para role="first-line-indented">
- The &utf; requires you to implement the test module initialization function. The test runner supplied with the static
- library or single-header variants of the &utf; requires the specific function specification. The test runner supplied
- with the dynamic library variant of the &utf; requires the specific initialization function signature only. <!-- TO FIX: specific specification -->
- </para>
-
- <para role="first-line-indented">
- For many <link linkend="test-module.def">test modules</link> you don't need to do any custom initialization
- and test tree construction is automated. In this case you don't really need the initialization function and
- the &utf; provides a way to automatically generate an empty one for you.
- </para>
-
- <para role="first-line-indented">
- Original design of the &utf; supported the manual test tree construction only. Later versions introduced the
- automated registration of test units. In later versions of the &utf; the original initialization function
- specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification
- was introduced. This change is not backward compatible. The test runners supplied with the static library and
- single-header variants of the &utf; by default still require original initialization function specification, but
- support <link linkend="utf.compilation.flags">compilation flags</link> that switch to the alternative one. The test
- runner supplied with dynamic library variant of the &utf; requires new specification and doesn't support
- original one. The plan is to deprecate the original initialization function specification in one of the future
- releases and ultimately to stop supporting it.
- </para>
-
- <para role="first-line-indented">
- The initialization function invocation is monitored by the &utf; the same way as all the test cases. An unexpected
- exception or system error detected during initialization function invocation is treated as initialization error and
- is reported as such.
- </para>
-
- <section id="utf.user-guide.initialization.orig-signature">
- <title>Original initialization function signature and name</title>
- <titleabbrev>Original initialization function</titleabbrev>
-
- <para role="first-line-indented">
- The original design of the &utf; initialization requires you to implement the function with the following
- specification:
- </para>
-
- <programlisting><classname>boost::unit_test::test_suite</classname>* init_unit_test_suite( int argc, char* argv[] );</programlisting>
-
- <para role="first-line-indented">
- In original design of the &utf; this function was intended to initialize and return a master test suite. The null
- value was considered an initialization error. The current design of the &utf; maintains master test suite instance
- internally and does not treat the null result value as an initialization error. In fact it's recommended to
- return null value always and register test units in the master test suite using the regular test suite add
- interface. The only way to indicate an initialization error is to throw the
- <classname>boost::unit_test::framework::setup_error</classname> exception.
- </para>
-
- <para role="first-line-indented">
- The initialization function parameters argc, argv provide the command line arguments specified during test
- module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be
- consisted with the alternative initialization function specification it's recommended though to access the
- command line arguments using the master test suite interface.
- </para>
- </section>
-
- <section id="utf.user-guide.initialization.alt-signature">
- <title>Alternative initialization function signature and name</title>
- <titleabbrev>Alternative initialization function</titleabbrev>
-
- <para role="first-line-indented">
- The alternative design of the &utf; initialization requires you to implement a function with the following
- specification:
- </para>
-
- <programlisting>bool init_unit_test();</programlisting>
-
- <para role="first-line-indented">
- The result value of this function indicates whether or not initialization was successful. To register test
- units in a master test suite use the test suite add interface. To access command line arguments use the master
- test suite interface. It's guarantied that any framework-specific command line arguments are excluded.
- </para>
- </section>
-
- <section id="utf.user-guide.initialization.signature-typedef">
- <title>Initialization function signature access</title>
-
- <para role="first-line-indented">
- The test runner interface needs to refer to the initialization function signature. The &utf; provides the typedef
- that resolves to proper signature in all configurations:
- </para>
-
- <programlisting>namespace boost {
-namespace unit_test {
-#ifdef BOOST_TEST_ALTERNATIVE_INIT_API
-typedef bool (*init_unit_test_func)();
-#else
-typedef test_suite* (*init_unit_test_func)( int, char* [] );
-#endif
-}
-}</programlisting>
-
- </section>
-
- <section id="utf.user-guide.initialization.auto-generation">
- <title>Automated generation of the test module initialization function</title>
- <titleabbrev>Automated generation</titleabbrev>
-
- <para role="first-line-indented">
- To automatically generate an empty test module initialization function you need to define
- <xref linkend="utf.flag.main" endterm="utf.flag.main"/> before including the
- <filename class="headerfile">boost/test/unit_test.hpp</filename> header. The value of this define is ignored.
- Alternatively you can define the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/> to be equal to
- any string (not necessarily in quotes). This macro causes the same result as
- <xref linkend="utf.flag.main" endterm="utf.flag.main"/>, and in addition the macro value becomes the name of the
- master test suite.
- </para>
-
- <important>
- <simpara>
- For a test module consisting of multiple source files you have to define these flags in a single test file only.
- Otherwise you end up with multiple instances of the initialization function.
- </simpara>
- </important>
- </section>
- </section>
-
- <xi:include href="utf.users-guide.test-organization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.users-guide.fixture.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.users-guide.test-output.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.user-guide.runtime-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
-</section>
Modified: trunk/libs/test/doc/src/utf.xml
==============================================================================
--- trunk/libs/test/doc/src/utf.xml (original)
+++ trunk/libs/test/doc/src/utf.xml 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -92,7 +92,7 @@
<itemizedlist mark ="square">
<listitem>
<simpara>
- Simplify writing test cases by using various <link linkend="utf.testing-tools.reference">testing tools</link>.
+ Simplify writing test cases by using various <link linkend="utf.user-guide.testing-tools.reference">testing tools</link>.
</simpara>
</listitem>
<listitem>
@@ -143,8 +143,8 @@
</itemizedlist>
<para role="first-line-indented">
- For those interested in getting started quickly please visit <ulink url="example-toc.html">collection of
- examples</ulink> presented in this documentation.
+ For those interested in getting started quickly please visit <link linkend="utf.examples">collection of
+ examples</link> presented in this documentation.
</para>
</section>
@@ -161,7 +161,9 @@
The &utf; is comparatively complicated component and is implemented in close to hundred header and source files,
so for long term usage the preferable solution is to build the &utf; as a reusable standalone library.
Depending on your platform this may save you a significant time during test module compilation and doesn't
- really require that much effort.
+ really require that much effort <footnote><simpara>If you are using Visual studio compilers do not forget to
+ set a subsystem to console when you build test modules. You can do it either in project properties or by setting
+ command line /SUBSYTEM:CONSOLE. Number of people reported link error caused specifically by this omission</simpara></footnote>.
<ulink url="http://boost.org/more/getting_started/index.html">Boost Getting started</ulink> tells you how to get
pre-built libraries for some platforms. If available, this is the easiest option and you can ignore standalone
library compilation instructions below.
@@ -229,7 +231,7 @@
</itemizedlist>
</section>
- <section id="utf.compilation.procedured">
+ <section id="utf.compilation.procedure">
<title>Compilation procedures</title>
<para role="first-line-indented">
@@ -237,9 +239,9 @@
linking with the &utf; may require additional steps. The &utf; presents you with options to either
<link linkend="utf.compilation.standalone">built and link with a standalone library</link> or
<link linkend="utf.compilation.direct-include">include the implementation directly</link> into a test module.
- If you opt to use the library the &utf; headers implement the
- <link linkend="utf.compilation.auto-linking">auto-linking support</link>. The compilation of the &utf; library and
- a test module can be configured using the following compilation flags.
+ If you opt to use the library the &utf; headers implement the <link linkend="utf.compilation.auto-linking">
+ auto-linking support</link>. The compilation of the &utf; library and a test module can be configured using the
+ following compilation flags.
</para>
<table id="utf.compilation.flags">
@@ -314,7 +316,7 @@
(for example Microsoft Visual Studio). The Boost preferred solution is Boost.Build system that is based on top of
bjam tool. Make systems require some kind of configuration file that lists all files that constitute the library
and all build options. For example the makefile that is used by make, or the Microsoft Visual Studio project file,
- Jamfile is used by Boost.Build. For the sake of simplicity let's call this file the makefile.</simpara></footnote>.
+ Jamfile is used by Boost.Build. For the sake of simplicity let's call this file the makefile.</simpara></footnote>.
</para>
<para role="first-line-indented">
@@ -409,7 +411,7 @@
</section>
</section>
- <xi:include href="utf.users-guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="utf.testing-tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.user-guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="utf.usage-recommendations.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="utf.examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</section>
Modified: trunk/libs/test/doc/src/xsl/html.xsl
==============================================================================
--- trunk/libs/test/doc/src/xsl/html.xsl (original)
+++ trunk/libs/test/doc/src/xsl/html.xsl 2011-10-17 07:13:55 EDT (Mon, 17 Oct 2011)
@@ -370,7 +370,7 @@
<xsl:variable name = "home" select = "/*[1]"/>
<xsl:variable name = "up" select = "parent::*"/>
- <xsl:variable name = "boost.test.image.src" select = "concat($boost.root, '/libs/test/docbook/img/boost.test.logo.png')"/>
+ <xsl:variable name = "boost.test.image.src" select = "concat($boost.root, '/libs/test/doc/img/boost.test.logo.png')"/>
<table width = "100%">
<tr>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk