libs/test/doc/html/boost_test/tests_organization/test_cases.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Test cases</title>
   5 <link rel="stylesheet" href="../../boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../index.html" title="Boost.Test">
   8 <link rel="up" href="../tests_organization.html" title="Declaring and organizing tests">
   9 <link rel="prev" href="../tests_organization.html" title="Declaring and organizing tests">
  10 <link rel="next" href="test_cases/test_organization_nullary.html" title="Test cases without parameters">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="../tests_organization.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tests_organization.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="test_cases/test_organization_nullary.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_test.tests_organization.test_cases"></a><a class="link" href="test_cases.html" title="Test cases">Test cases</a>
  28 </h3></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="test_cases/test_organization_nullary.html">Test
  31         cases without parameters</a></span></dt>
  32 <dt><span class="section"><a href="test_cases/test_case_generation.html">Data-driven
  33         test cases</a></span></dt>
  34 <dd><dl>
  35 <dt><span class="section"><a href="test_cases/test_case_generation/datasets.html">Datasets</a></span></dt>
  36 <dd><dl>
  37 <dt><span class="section"><a href="test_cases/test_case_generation/datasets.html#boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface">Dataset
  38             interface</a></span></dt>
  39 <dt><span class="section"><a href="test_cases/test_case_generation/datasets.html#boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_creation_and_delayed_cre">Dataset
  40             creation and delayed creation</a></span></dt>
  41 </dl></dd>
  42 <dt><span class="section"><a href="test_cases/test_case_generation/datasets_auto_registration.html">Declaring
  43           and registering test cases with datasets</a></span></dt>
  44 <dt><span class="section"><a href="test_cases/test_case_generation/operations.html">Operations
  45           on dataset</a></span></dt>
  46 <dd><dl>
  47 <dt><span class="section"><a href="test_cases/test_case_generation/operations.html#boost_test.tests_organization.test_cases.test_case_generation.operations.joins">Joins</a></span></dt>
  48 <dt><span class="section"><a href="test_cases/test_case_generation/operations.html#boost_test.tests_organization.test_cases.test_case_generation.operations.zips">Zips</a></span></dt>
  49 <dt><span class="section"><a href="test_cases/test_case_generation/operations.html#boost_test.tests_organization.test_cases.test_case_generation.operations.grid_cartesian_products">Grid
  50             (Cartesian products)</a></span></dt>
  51 </dl></dd>
  52 <dt><span class="section"><a href="test_cases/test_case_generation/generators.html">Datasets
  53           generators</a></span></dt>
  54 </dl></dd>
  55 <dt><span class="section"><a href="test_cases/test_organization_templates.html">Template
  56         test cases</a></span></dt>
  57 <dt><span class="section"><a href="test_cases/param_test.html">Parametrized
  58         test cases</a></span></dt>
  59 </dl></div>
  60 <p>
  61         A test case is a unit of execution that is run by the <a class="link" href="../section_glossary.html#test_runner">test
  62         runner</a>. It contains instructions and <a class="link" href="../testing_tools/boost_test_universal_macro.html" title="BOOST_TEST: universal and general purpose assertions">assertions</a>,
  63         and its execution is monitored by the <span class="emphasis"><em>Unit Test Framework</em></span>.
  64         Information about the execution is recorded, and a log/report is produced.
  65       </p>
  66 <p>
  67         The test runner should be informed of the test case in order to run it: the
  68         test case should be <span class="bold"><strong>registered</strong></span> for its inclusion
  69         into the <span class="emphasis"><em>test tree</em></span>.
  70       </p>
  71 <p>
  72         The <span class="emphasis"><em>Unit Test Framework</em></span> covers the following test case
  73         scenarios:
  74       </p>
  75 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  76 <li class="listitem">
  77             <span class="bold"><strong>test cases without parameters</strong></span>: those
  78             are similar to the run of a function in the controlled environment of
  79             the test runner.
  80           </li>
  81 <li class="listitem">
  82             <span class="bold"><strong>test cases with parameters</strong></span>: this usage
  83             is intended to run the same function with potentially many different
  84             parameters, each call with a different parameter being handled by the
  85             test runner.
  86           </li>
  87 <li class="listitem">
  88             <span class="bold"><strong>test cases on template</strong></span>: the scenario
  89             is to test the same template implementation against several type.
  90           </li>
  91 </ul></div>
  92 <p>
  93         The test case have a different <span class="bold"><strong>declaration</strong></span>
  94         APIs for each of the above scenarios. Preferred APIs will declare the test
  95         case and register it automatically in a test tree without a necessity to
  96         perform manual registration.
  97       </p>
  98 <h5>
  99 <a name="boost_test.tests_organization.test_cases.h0"></a>
 100         <span class="phrase"><a name="boost_test.tests_organization.test_cases.manual_registration"></a></span><a class="link" href="test_cases.html#boost_test.tests_organization.test_cases.manual_registration">Manual
 101         registration</a>
 102       </h5>
 103 <p>
 104         While automatic registration is preferred test case declaration API, it is
 105         also possible to declare tests manually. For this APIs, <span class="emphasis"><em>Unit Test
 106         Framework</em></span> opted for a least intrusive design based on <span class="emphasis"><em>generic
 107         callback</em></span> approach, which signatures depends on the king of test
 108         case being declared.
 109       </p>
 110 <p>
 111         The single test module may mix both automated and manual test case registration.
 112         In other words, within the same test module you can have both test cases
 113         implemented remotely and registered manually in the test module initialization
 114         function and test cases that are registered automatically at implementation
 115         point.
 116       </p>
 117 <div class="caution"><table border="0" summary="Caution">
 118 <tr>
 119 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
 120 <th align="left">Caution</th>
 121 </tr>
 122 <tr><td align="left" valign="top"><p>
 123           The design of manual test case declaration API in <span class="emphasis"><em>Unit Test Framework</em></span>
 124           assumes the test case implementation (test function body) and test case
 125           creation/registration points are remote. As a result you may forget to
 126           register the test case and it's never going to be executed, even though
 127           it's present in test file.
 128         </p></td></tr>
 129 </table></div>
 130 <p>
 131         You need to be sure you exhausted all possible ways to employ automatic registration
 132         APIs first before you opt to use manual registration. Specifically:
 133       </p>
 134 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 135 <li class="listitem">
 136             If you need optionally include/exclude some of the test cases, consider
 137             using <a class="link" href="../utf_reference/test_org_reference/decorator_enabled.html" title="enabled / disabled (decorator)"><code class="computeroutput"><span class="identifier">enabled</span></code></a> / <a class="link" href="../utf_reference/test_org_reference/decorator_enabled.html" title="enabled / disabled (decorator)"><code class="computeroutput"><span class="identifier">disabled</span></code></a> / <a class="link" href="../utf_reference/test_org_reference/decorator_enable_if.html" title="enable_if (decorator)"><code class="computeroutput"><span class="identifier">enable_if</span></code></a> decorators instead
 138           </li>
 139 <li class="listitem">
 140             If you need to register some parametrized test cases based on some data,
 141             consider <a class="link" href="test_cases/test_case_generation.html" title="Data-driven test cases">data-driven</a>
 142             test cases instead
 143           </li>
 144 <li class="listitem">
 145             If you need to specify complicated test unit dependencies, you can use
 146             <a class="link" href="../utf_reference/test_org_reference/decorator_depends_on.html" title="depends_on (decorator)"><code class="computeroutput"><span class="identifier">depends_on</span></code></a> decorator instead
 147           </li>
 148 <li class="listitem">
 149             if you need to share the logic between the test units consider using
 150             <a class="link" href="fixtures.html" title="Fixtures">fixtures</a>
 151             instead
 152           </li>
 153 </ul></div>
 154 </div>
 155 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 156 <td align="left"></td>
 157 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 158       contributors<p>
 159         Distributed under the Boost Software License, Version 1.0. (See accompanying
 160         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 161       </p>
 162 </div></td>
 163 </tr></table>
 164 <hr>
 165 <div class="spirit-nav">
 166 <a accesskey="p" href="../tests_organization.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tests_organization.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="test_cases/test_organization_nullary.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 167 </div>
 168 </body>
 169 </html>