test/doc/src/utf.user-guide.xml

<?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">
 <title>Unit Test Framework: User's guide</title><titleabbrev>User's guide</titleabbrev>

 <section id="utf.user-guide.intro">
  <title>Introduction &hellip; or where to start?</title><titleabbrev>Introduction</titleabbrev>

  <para role="first-line-indented">
    Without further ado, I'd like to start &hellip; 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>
  <para role="first-line-indented">
    Well &hellip; 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>
  <para role="first-line-indented">
    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">
    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>
  <para role="first-line-indented">
    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>
  <para role="first-line-indented">
    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>

 </section>

 <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>