libs/test/doc/html/boost_test/runtime_config/test_unit_filtering.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Test unit filtering</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="../runtime_config.html" title="Runtime parameters">
   9 <link rel="prev" href="../runtime_config.html" title="Runtime parameters">
  10 <link rel="next" href="custom_command_line_arguments.html" title="Custom command line arguments">
  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="../runtime_config.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../runtime_config.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="custom_command_line_arguments.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.runtime_config.test_unit_filtering"></a><a class="link" href="test_unit_filtering.html" title="Test unit filtering">Test unit
  28       filtering</a>
  29 </h3></div></div></div>
  30 <p>
  31         The <span class="emphasis"><em>Unit Test Framework</em></span> offers a number of ways to run
  32         only a subset of all test cases registered in the test tree.
  33       </p>
  34 <a name="ref_default_run_status"></a><h4>
  35 <a name="boost_test.runtime_config.test_unit_filtering.h0"></a>
  36         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.default_run_status"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.default_run_status">Default
  37         run status</a>
  38       </h4>
  39 <p>
  40         Each test unit (either test case or test suite) has an associated <span class="emphasis"><em>default
  41         run status</em></span>. It can assume one of the three values:
  42       </p>
  43 <div class="orderedlist"><ol class="orderedlist" type="1">
  44 <li class="listitem">
  45             <span class="emphasis"><em>true</em></span> -- this means that, unless some runtime parameters
  46             specify otherwise, the test unit is designated to be run.
  47           </li>
  48 <li class="listitem">
  49             <span class="emphasis"><em>false</em></span> -- this means that, unless some runtime parameters
  50             specify otherwise, the test unit is designated <span class="emphasis"><em>not</em></span>
  51             to be run.
  52           </li>
  53 <li class="listitem">
  54             <span class="emphasis"><em>inherit</em></span> -- this means that the test unit's default
  55             run status is the same as that of its immediate parent test unit. This
  56             is applied recursively.
  57           </li>
  58 </ol></div>
  59 <p>
  60         Initially, the master test suite has default run status set to <span class="emphasis"><em>true</em></span>.
  61         All other test units have default run status set to <span class="emphasis"><em>inherit</em></span>.
  62         This implies that, unless any additional configuration is applied, all tests
  63         are designated to be run.
  64       </p>
  65 <p>
  66         You can set a different default run status in any test unit by using <a class="link" href="../tests_organization/decorators.html" title="Decorators">decorators</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_enabled.html" title="enabled / disabled (decorator)"><code class="computeroutput"><span class="identifier">enabled</span></code></a> and <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>. The default run status
  67         is set once, upon testing program initialization, and cannot be changed.
  68         The disabled tests are not executed by default, but are still present in
  69         the test tree, and are listed along with other tests when you use command-line
  70         argument <a class="link" href="../utf_reference/rt_param_reference/list_content.html" title="list_content"><code class="computeroutput"><span class="identifier">list_content</span></code></a>.
  71       </p>
  72 <h6>
  73 <a name="boost_test.runtime_config.test_unit_filtering.h1"></a>
  74         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.example_descr"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.example_descr">Example:
  75         default run status</a>
  76       </h6>
  77 <div class="informaltable"><table class="table">
  78 <colgroup><col></colgroup>
  79 <thead><tr><th>
  80                 <p>
  81                   Code
  82                 </p>
  83               </th></tr></thead>
  84 <tbody><tr><td>
  85 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">decorator_20</span>
  86 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  87
  88 <span class="keyword">namespace</span> <span class="identifier">utf</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
  89
  90 <span class="keyword">const</span> <span class="keyword">bool</span> <span class="identifier">io_implemented</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
  91 <span class="keyword">const</span> <span class="keyword">bool</span> <span class="identifier">db_implemented</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span>
  92
  93 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite1</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">disabled</span><span class="special">())</span>
  94
  95   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">)</span>
  96   <span class="special">{</span>
  97     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">1</span> <span class="special">!=</span> <span class="number">1</span><span class="special">);</span>
  98   <span class="special">}</span>
  99
 100   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">enabled</span><span class="special">())</span>
 101   <span class="special">{</span>
 102     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">2</span> <span class="special">!=</span> <span class="number">2</span><span class="special">);</span>
 103   <span class="special">}</span>
 104
 105   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_io</span><span class="special">,</span>
 106     <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">enable_if</span><span class="special">&lt;</span><span class="identifier">io_implemented</span><span class="special">&gt;())</span>
 107   <span class="special">{</span>
 108     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">3</span> <span class="special">!=</span> <span class="number">3</span><span class="special">);</span>
 109   <span class="special">}</span>
 110
 111   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_db</span><span class="special">,</span>
 112     <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">enable_if</span><span class="special">&lt;</span><span class="identifier">db_implemented</span><span class="special">&gt;())</span>
 113   <span class="special">{</span>
 114     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">4</span> <span class="special">!=</span> <span class="number">4</span><span class="special">);</span>
 115   <span class="special">}</span>
 116
 117 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 118 </pre>
 119               </td></tr></tbody>
 120 </table></div>
 121 <div class="informaltable"><table class="table">
 122 <colgroup><col></colgroup>
 123 <thead><tr><th>
 124                 <p>
 125                   Output
 126                 </p>
 127               </th></tr></thead>
 128 <tbody><tr><td>
 129 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">decorator_20</span>
 130 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 131 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">18</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"suite1/test_2"</span><span class="special">:</span> <span class="identifier">check</span> <span class="number">2</span> <span class="special">!=</span> <span class="number">2</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">2</span> <span class="special">==</span> <span class="number">2</span><span class="special">]</span>
 132 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">24</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"suite1/test_io"</span><span class="special">:</span> <span class="identifier">check</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">3</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">3</span> <span class="special">==</span> <span class="number">3</span><span class="special">]</span>
 133
 134 <span class="special">***</span> <span class="number">2</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_20"</span>
 135
 136 <span class="special">&gt;</span> <span class="identifier">decorator_20</span> <span class="special">--</span><span class="identifier">list_content</span>
 137 <span class="identifier">suite1</span><span class="special">*</span>
 138     <span class="identifier">test_1</span>
 139     <span class="identifier">test_2</span><span class="special">*</span>
 140     <span class="identifier">test_io</span><span class="special">*</span>
 141     <span class="identifier">test_db</span>
 142 </pre>
 143               </td></tr></tbody>
 144 </table></div>
 145 <a name="ref_dynamic_test_dependency"></a><h4>
 146 <a name="boost_test.runtime_config.test_unit_filtering.h2"></a>
 147         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.dynamic_test_dependencies"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.dynamic_test_dependencies">Dynamic
 148         test dependencies</a>
 149       </h4>
 150 <p>
 151         Additionally, it is possible to statically associate a test unit with a condition.
 152         This associated condition is evaluated immediately before executing the test
 153         unit. If the condition is met, the test unit is executed. Otherwise, the
 154         test unit is <span class="emphasis"><em>skipped</em></span>. It is possible to add two dependencies:
 155       </p>
 156 <div class="orderedlist"><ol class="orderedlist" type="1">
 157 <li class="listitem">
 158             Upon another test unit. In this case the decorated test case is skipped
 159             if the test unit specified in the dependency is either failed or skipped
 160             or disabled. This can be declared with decorator <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>.
 161           </li>
 162 <li class="listitem">
 163             Upon an arbitrary predicate. This can be declared with decorator <a class="link" href="../utf_reference/test_org_reference/decorator_precondition.html" title="precondition (decorator)"><code class="computeroutput"><span class="identifier">precondition</span></code></a>.
 164           </li>
 165 </ol></div>
 166 <a name="ref_command_line_control"></a><h4>
 167 <a name="boost_test.runtime_config.test_unit_filtering.h3"></a>
 168         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.command_line_control"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.command_line_control">Command-line
 169         control</a>
 170       </h4>
 171 <p>
 172         Static configuration of the test-case filtering is used by default, unless
 173         command-line filtering is applied. With command-line argument <a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a> it is possible to alter
 174         the static pre-set in a number of ways:
 175       </p>
 176 <div class="orderedlist"><ol class="orderedlist" type="1">
 177 <li class="listitem">
 178             Ignore the static configuration and manually specify test cases to be
 179             run.
 180           </li>
 181 <li class="listitem">
 182             Augment the statically defined set by enabling the disabled test cases.
 183           </li>
 184 <li class="listitem">
 185             Shrink the statically defined set by disabling some of the enabled test
 186             cases.
 187           </li>
 188 </ol></div>
 189 <a name="ref_command_line_control_absolute"></a><h5>
 190 <a name="boost_test.runtime_config.test_unit_filtering.h4"></a>
 191         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.absolute_specification"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.absolute_specification">Absolute
 192         specification</a>
 193       </h5>
 194 <p>
 195         Term 'absolute' in this context means that the default run status of the
 196         test units, which has been statically set up, is completely ignored and the
 197         tests to be run are specified manually from scratch. First, in order to learn
 198         what test units are registered in the test tree the user needs to use command-line
 199         argument <a class="link" href="../utf_reference/rt_param_reference/list_content.html" title="list_content"><code class="computeroutput"><span class="identifier">list_content</span></code></a>. Next, in order to
 200         specify a set of test cases, the user needs to use command-line argument
 201         <a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a> with absolute value:
 202       </p>
 203 <pre class="programlisting"><span class="special">&gt;</span> <span class="identifier">test_program</span> <span class="special">--</span><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a><span class="special">=&lt;</span><span class="identifier">test_set</span><span class="special">&gt;</span>
 204 </pre>
 205 <p>
 206         The format of <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">test_set</span><span class="special">&gt;</span></code> value can assume a number of forms. Given
 207         the following program:
 208       </p>
 209 <pre class="programlisting"><span class="preprocessor">#define</span> <a class="link" href="../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> <span class="identifier">example</span>
 210 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 211
 212 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><a class="link" href="../utf_reference/test_org_reference/decorator_label.html" title="label (decorator)"><code class="computeroutput"><span class="identifier">label</span></code></a><span class="special">;</span>
 213
 214 <a class="link" href="../utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">test_1</span><span class="special">,</span> <span class="special">*</span><span class="identifier">label</span><span class="special">(</span><span class="string">"L1"</span><span class="special">))</span> <span class="special">{}</span>
 215 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">,</span> <span class="special">*</span><span class="identifier">label</span><span class="special">(</span><span class="string">"L1"</span><span class="special">))</span> <span class="special">{}</span>
 216
 217 <a class="link" href="../utf_reference/test_org_reference/test_org_boost_auto_test_suite.html" title="BOOST_AUTO_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_SUITE</span></code></a><span class="special">(</span><span class="identifier">suite_1</span><span class="special">)</span>
 218
 219   <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite_1</span><span class="special">)</span>
 220     <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">)</span> <span class="special">{}</span>
 221     <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">)</span> <span class="special">{}</span>
 222   <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 223
 224   <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite_2</span><span class="special">)</span>
 225     <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">,</span> <span class="special">*</span><span class="identifier">label</span><span class="special">(</span><span class="string">"L2"</span><span class="special">))</span> <span class="special">{}</span>
 226     <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">,</span> <span class="special">*</span><span class="identifier">label</span><span class="special">(</span><span class="string">"L2"</span><span class="special">))</span> <span class="special">{}</span>
 227   <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 228
 229   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">,</span> <span class="special">*</span><span class="identifier">label</span><span class="special">(</span><span class="string">"L1"</span><span class="special">))</span> <span class="special">{}</span>
 230   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">)</span> <span class="special">{}</span>
 231   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2A</span><span class="special">)</span> <span class="special">{}</span>
 232
 233 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 234 </pre>
 235 <p>
 236         The following table illustrates how different values of <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">test_set</span><span class="special">&gt;</span></code>
 237         control which test cases ware run.
 238       </p>
 239 <div class="informaltable"><table class="table">
 240 <colgroup>
 241 <col>
 242 <col>
 243 <col>
 244 </colgroup>
 245 <thead><tr>
 246 <th>
 247                 <p>
 248                   Description
 249                 </p>
 250               </th>
 251 <th>
 252                 <p>
 253                   Parameter value
 254                 </p>
 255               </th>
 256 <th>
 257                 <p>
 258                   Test cases run
 259                 </p>
 260               </th>
 261 </tr></thead>
 262 <tbody>
 263 <tr>
 264 <td>
 265                 <p>
 266                   Run single top-level test case by name
 267                 </p>
 268               </td>
 269 <td>
 270 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=test_1</pre>
 271               </td>
 272 <td>
 273 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">test_1
 274 </pre>
 275               </td>
 276 </tr>
 277 <tr>
 278 <td>
 279                 <p>
 280                   Run single nested test case by name
 281                 </p>
 282               </td>
 283 <td>
 284 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/suite_1/test_1</pre>
 285               </td>
 286 <td>
 287 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/suite_1/test_1
 288 </pre>
 289               </td>
 290 </tr>
 291 <tr>
 292 <td>
 293                 <p>
 294                   Run single test suite by name
 295                 </p>
 296               </td>
 297 <td>
 298 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/suite_2
 299 <a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/suite_2/*
 300 </pre>
 301               </td>
 302 <td>
 303 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/suite_2/test_1
 304 suite_1/suite_2/test_2
 305 </pre>
 306               </td>
 307 </tr>
 308 <tr>
 309 <td>
 310                 <p>
 311                   Run multiple test units that are <span class="bold"><strong>siblings</strong></span>
 312                   of the same test suite
 313                 </p>
 314               </td>
 315 <td>
 316 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/test_1,suite_2</pre>
 317               </td>
 318 <td>
 319 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/suite_2/test_1
 320 suite_1/suite_2/test_2
 321 suite_1/test_1
 322 </pre>
 323               </td>
 324 </tr>
 325 <tr>
 326 <td>
 327                 <p>
 328                   Run multiple test units that are not necessarily siblings
 329                 </p>
 330               </td>
 331 <td>
 332 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/test_1:test_1</pre>
 333               </td>
 334 <td>
 335 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/test_1
 336 test_1
 337 </pre>
 338               </td>
 339 </tr>
 340 <tr>
 341 <td>
 342                 <p>
 343                   Run all tests matching to a given label
 344                 </p>
 345               </td>
 346 <td>
 347 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=@L1</pre>
 348               </td>
 349 <td>
 350 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">test_1
 351 test_2
 352 suite_1/test_1
 353 </pre>
 354               </td>
 355 </tr>
 356 <tr>
 357 <td>
 358                 <p>
 359                   Run every test case in the test tree. Note that this will also
 360                   enable all disabled tests.
 361                 </p>
 362               </td>
 363 <td>
 364 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=*</pre>
 365               </td>
 366 <td>
 367 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">test_1
 368 test_2
 369 suite_1/suite_1/test_1
 370 suite_1/suite_1/test_2
 371 suite_1/suite_2/test_1
 372 suite_1/suite_2/test_2
 373 suite_1/test_1
 374 suite_1/test_2
 375 suite_1/test_2A
 376 </pre>
 377               </td>
 378 </tr>
 379 <tr>
 380 <td>
 381                 <p>
 382                   Run every test unit in a given suite with a given prefix
 383                 </p>
 384               </td>
 385 <td>
 386 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/test*</pre>
 387               </td>
 388 <td>
 389 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/test_1
 390 suite_1/test_2
 391 suite_1/test_2A
 392 </pre>
 393               </td>
 394 </tr>
 395 <tr>
 396 <td>
 397                 <p>
 398                   Run every test unit in a given suite with a given suffix
 399                 </p>
 400               </td>
 401 <td>
 402 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/*_1</pre>
 403               </td>
 404 <td>
 405 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/suite_1/test_1
 406 suite_1/suite_1/test_2
 407 suite_1/test_1
 408 </pre>
 409               </td>
 410 </tr>
 411 <tr>
 412 <td>
 413                 <p>
 414                   Run every test unit in a given suite with a given infix
 415                 </p>
 416               </td>
 417 <td>
 418 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=suite_1/*_2*</pre>
 419               </td>
 420 <td>
 421 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/suite_2/test_1
 422 suite_1/suite_2/test_2
 423 suite_1/test_2
 424 suite_1/test_2A
 425 </pre>
 426               </td>
 427 </tr>
 428 <tr>
 429 <td>
 430                 <p>
 431                   Run test(s) with given name in any N-level suite
 432                 </p>
 433               </td>
 434 <td>
 435 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=*/*/test_2</pre>
 436               </td>
 437 <td>
 438 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">suite_1/suite_1/test_2
 439 suite_1/suite_2/test_2
 440 </pre>
 441               </td>
 442 </tr>
 443 </tbody>
 444 </table></div>
 445 <p>
 446         For the syntax productions describing the structure of <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">test_set</span><span class="special">&gt;</span></code>
 447         value see <a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test">here</a>.
 448       </p>
 449 <p>
 450         While using manual absolute test case specification ignores the default run
 451         status, it does not ignore the dynamic test dependencies. If test unit <code class="computeroutput"><span class="identifier">B</span></code> depends on test unit <code class="computeroutput"><span class="identifier">A</span></code>
 452         and test <code class="computeroutput"><span class="identifier">B</span></code> is specified to
 453         be run by <a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>, <code class="computeroutput"><span class="identifier">A</span></code>
 454         is also run, even if it is not specified, and its failure may cause the execution
 455         of <code class="computeroutput"><span class="identifier">B</span></code> to be skipped. Similarly,
 456         the failed check of the <a class="link" href="../utf_reference/test_org_reference/decorator_precondition.html" title="precondition (decorator)"><code class="computeroutput"><span class="identifier">precondition</span></code></a> may cause the test
 457         selected test to be skipped.
 458       </p>
 459 <h6>
 460 <a name="boost_test.runtime_config.test_unit_filtering.h5"></a>
 461         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.example_descr0"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.example_descr0">Example:
 462         run_test and dynamic dependencies</a>
 463       </h6>
 464 <div class="informaltable"><table class="table">
 465 <colgroup><col></colgroup>
 466 <thead><tr><th>
 467                 <p>
 468                   Code
 469                 </p>
 470               </th></tr></thead>
 471 <tbody><tr><td>
 472 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">decorator_21</span>
 473 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 474
 475 <span class="keyword">namespace</span> <span class="identifier">utf</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 476 <span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>
 477
 478 <span class="identifier">tt</span><span class="special">::</span><span class="identifier">assertion_result</span> <span class="identifier">fail</span><span class="special">(</span><span class="identifier">utf</span><span class="special">::</span><span class="identifier">test_unit_id</span><span class="special">)</span>
 479 <span class="special">{</span>
 480   <span class="identifier">tt</span><span class="special">::</span><span class="identifier">assertion_result</span> <span class="identifier">ans</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
 481   <span class="identifier">ans</span><span class="special">.</span><span class="identifier">message</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"precondition failed"</span><span class="special">;</span>
 482   <span class="keyword">return</span> <span class="identifier">ans</span><span class="special">;</span>
 483 <span class="special">}</span>
 484
 485 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">)</span>
 486 <span class="special">{</span>
 487   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
 488 <span class="special">}</span>
 489
 490 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">,</span>
 491   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">depends_on</span><span class="special">(</span><span class="string">"test_1"</span><span class="special">))</span>
 492 <span class="special">{</span>
 493   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 494 <span class="special">}</span>
 495
 496 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_3</span><span class="special">,</span>
 497   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">precondition</span><span class="special">(</span><span class="identifier">fail</span><span class="special">))</span>
 498 <span class="special">{</span>
 499   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 500 <span class="special">}</span>
 501 </pre>
 502               </td></tr></tbody>
 503 </table></div>
 504 <div class="informaltable"><table class="table">
 505 <colgroup><col></colgroup>
 506 <thead><tr><th>
 507                 <p>
 508                   Output
 509                 </p>
 510               </th></tr></thead>
 511 <tbody><tr><td>
 512 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">decorator_21</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="identifier">test_2</span><span class="special">,</span><span class="identifier">test_3</span>
 513 <span class="identifier">Including</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="identifier">test_1</span> <span class="identifier">as</span> <span class="identifier">a</span> <span class="identifier">dependency</span> <span class="identifier">of</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="identifier">test_2</span>
 514 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 515 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_21"</span>
 516 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">14</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 517 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">16</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_1"</span><span class="special">:</span> <span class="identifier">check</span> <span class="keyword">false</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 518 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">14</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">3</span><span class="identifier">ms</span>
 519 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">26</span><span class="special">):</span> <span class="identifier">Test</span> <span class="keyword">case</span> <span class="string">"test_3"</span> <span class="identifier">is</span> <span class="identifier">skipped</span> <span class="identifier">because</span> <span class="identifier">precondition</span> <span class="identifier">failed</span>
 520 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">20</span><span class="special">):</span> <span class="identifier">Test</span> <span class="keyword">case</span> <span class="string">"test_2"</span> <span class="identifier">is</span> <span class="identifier">skipped</span> <span class="identifier">because</span> <span class="identifier">dependency</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 521 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_21"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">17</span><span class="identifier">ms</span>
 522
 523 <span class="special">***</span> <span class="number">1</span> <span class="identifier">failure</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_21"</span>
 524 </pre>
 525               </td></tr></tbody>
 526 </table></div>
 527 <a name="ref_command_line_control_enablers"></a><h5>
 528 <a name="boost_test.runtime_config.test_unit_filtering.h6"></a>
 529         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.relative_specification"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.relative_specification">Relative
 530         specification</a>
 531       </h5>
 532 <p>
 533         Term 'relative' in this context means that the configuration is based on
 534         either the default run status of the test units or by the command-line override
 535         specified by the <span class="emphasis"><em>absolute specification</em></span>; and atop of
 536         this, we additionally either enable some disabled test units or disable some
 537         enabled tests units. The relative specification is controlled by command-line
 538         argument <a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>, with the value using similar
 539         syntax as in the absolute specification, but preceded with either character
 540         <code class="computeroutput"><span class="char">'!'</span></code> for disabling enabled test
 541         units or with character <code class="computeroutput"><span class="char">'+'</span></code> for
 542         enabling the disabled test units. This can be summarized with the following
 543         table:
 544       </p>
 545 <div class="informaltable"><table class="table">
 546 <colgroup>
 547 <col>
 548 <col>
 549 <col>
 550 </colgroup>
 551 <thead><tr>
 552 <th>
 553                 <p>
 554                   command
 555                 </p>
 556               </th>
 557 <th>
 558                 <p>
 559                   specification type
 560                 </p>
 561               </th>
 562 <th>
 563                 <p>
 564                   semantics
 565                 </p>
 566               </th>
 567 </tr></thead>
 568 <tbody>
 569 <tr>
 570 <td>
 571 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">&gt; test_program --<a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=!&lt;absolute_spec&gt;</pre>
 572               </td>
 573 <td>
 574                 <p>
 575                   disabler
 576                 </p>
 577               </td>
 578 <td>
 579                 <p>
 580                   Enabled test units that match <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">absolute_spec</span><span class="special">&gt;</span></code>
 581                   become disabled.
 582                 </p>
 583               </td>
 584 </tr>
 585 <tr>
 586 <td>
 587 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">&gt; test_program --<a class="link" href="../utf_reference/rt_param_reference/run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>=+&lt;absolute_spec&gt;</pre>
 588               </td>
 589 <td>
 590                 <p>
 591                   enabler
 592                 </p>
 593               </td>
 594 <td>
 595                 <p>
 596                   Disabled test units that match <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">absolute_spec</span><span class="special">&gt;</span></code>
 597                   as well as their upstream dependencies become enabled.
 598                 </p>
 599               </td>
 600 </tr>
 601 </tbody>
 602 </table></div>
 603 <p>
 604         The <span class="emphasis"><em>enabler</em></span> specification is used to enable a set of
 605         test units which are initially disabled.
 606       </p>
 607 <h6>
 608 <a name="boost_test.runtime_config.test_unit_filtering.h7"></a>
 609         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.example_descr1"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.example_descr1">Example:
 610         command-line enabler</a>
 611       </h6>
 612 <div class="informaltable"><table class="table">
 613 <colgroup><col></colgroup>
 614 <thead><tr><th>
 615                 <p>
 616                   Code
 617                 </p>
 618               </th></tr></thead>
 619 <tbody><tr><td>
 620 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">decorator_22</span>
 621 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 622
 623 <span class="keyword">namespace</span> <span class="identifier">utf</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 624
 625 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">)</span>
 626 <span class="special">{</span>
 627   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 628 <span class="special">}</span>
 629
 630 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_net</span><span class="special">,</span>
 631   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">disabled</span><span class="special">()</span>
 632   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"requires network"</span><span class="special">))</span>
 633 <span class="special">{</span>
 634   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 635 <span class="special">}</span>
 636 </pre>
 637               </td></tr></tbody>
 638 </table></div>
 639 <div class="informaltable"><table class="table">
 640 <colgroup><col></colgroup>
 641 <thead><tr><th>
 642                 <p>
 643                   Output
 644                 </p>
 645               </th></tr></thead>
 646 <tbody><tr><td>
 647 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">decorator_22</span> <span class="special">--</span><span class="identifier">list_content</span>
 648 <span class="identifier">test_1</span><span class="special">*</span>
 649 <span class="identifier">test_net</span> <span class="special">:</span> <span class="identifier">requires</span> <span class="identifier">network</span>
 650
 651
 652 <span class="special">&gt;</span> <span class="identifier">decorator_22</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span>
 653 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 654 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_22"</span>
 655 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 656 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 657 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_22"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">5</span><span class="identifier">ms</span>
 658
 659 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 660
 661
 662 <span class="special">&gt;</span> <span class="identifier">decorator_22</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=+</span><span class="identifier">test_net</span>
 663 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 664 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_22"</span>
 665 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 666 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span><span class="identifier">ms</span>
 667 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_net"</span>
 668 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_net"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span><span class="identifier">ms</span>
 669 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_22"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">16</span><span class="identifier">ms</span>
 670
 671 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 672 </pre>
 673               </td></tr></tbody>
 674 </table></div>
 675 <p>
 676         Conversely, the <span class="emphasis"><em>disabler</em></span> specification is used to disable
 677         a set of test units which are initially enabled.
 678       </p>
 679 <h6>
 680 <a name="boost_test.runtime_config.test_unit_filtering.h8"></a>
 681         <span class="phrase"><a name="boost_test.runtime_config.test_unit_filtering.example_descr2"></a></span><a class="link" href="test_unit_filtering.html#boost_test.runtime_config.test_unit_filtering.example_descr2">Example:
 682         command-line disabler</a>
 683       </h6>
 684 <div class="informaltable"><table class="table">
 685 <colgroup><col></colgroup>
 686 <thead><tr><th>
 687                 <p>
 688                   Code
 689                 </p>
 690               </th></tr></thead>
 691 <tbody><tr><td>
 692 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">decorator_23</span>
 693 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 694
 695 <span class="keyword">namespace</span> <span class="identifier">utf</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 696
 697 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">)</span>
 698 <span class="special">{</span>
 699   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 700 <span class="special">}</span>
 701
 702 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_net</span><span class="special">,</span>
 703   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"requires network"</span><span class="special">))</span>
 704 <span class="special">{</span>
 705   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 706 <span class="special">}</span>
 707 </pre>
 708               </td></tr></tbody>
 709 </table></div>
 710 <div class="informaltable"><table class="table">
 711 <colgroup><col></colgroup>
 712 <thead><tr><th>
 713                 <p>
 714                   Output
 715                 </p>
 716               </th></tr></thead>
 717 <tbody><tr><td>
 718 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">decorator_23</span> <span class="special">--</span><span class="identifier">list_content</span>
 719 <span class="identifier">test_1</span><span class="special">*</span>
 720 <span class="identifier">test_net</span><span class="special">*:</span> <span class="identifier">requires</span> <span class="identifier">network</span>
 721
 722
 723 <span class="special">&gt;</span> <span class="identifier">decorator_23</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span>
 724 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 725 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_23"</span>
 726 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 727 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 728 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">12</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_net"</span>
 729 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">12</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_net"</span>
 730 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_23"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">14</span><span class="identifier">ms</span>
 731
 732 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 733
 734
 735 <span class="special">&gt;</span> <span class="identifier">decorator_23</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=!</span><span class="identifier">test_net</span>
 736 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 737 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_23"</span>
 738 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 739 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_1"</span>
 740 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"decorator_23"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">5</span><span class="identifier">ms</span>
 741 </pre>
 742               </td></tr></tbody>
 743 </table></div>
 744 <p>
 745         If there are both an enabler and disabler on one command line that specify
 746         the same test, the test becomes disabled. I.e., the disabler takes the precedence
 747         over the enabler.
 748       </p>
 749 <div class="note"><table border="0" summary="Note">
 750 <tr>
 751 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
 752 <th align="left">Note</th>
 753 </tr>
 754 <tr><td align="left" valign="top"><p>
 755           While enabler additionally enables the upstream dependencies (introduced
 756           with decorator <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>), disabler does not
 757           disable them. Therefore when you enable and then disable the same test,
 758           you do not disable its upstream dependencies.
 759         </p></td></tr>
 760 </table></div>
 761 </div>
 762 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 763 <td align="left"></td>
 764 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 765       contributors<p>
 766         Distributed under the Boost Software License, Version 1.0. (See accompanying
 767         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>)
 768       </p>
 769 </div></td>
 770 </tr></table>
 771 <hr>
 772 <div class="spirit-nav">
 773 <a accesskey="p" href="../runtime_config.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../runtime_config.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="custom_command_line_arguments.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 774 </div>
 775 </body>
 776 </html>