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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Custom command line arguments</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="test_unit_filtering.html" title="Test unit filtering">
  10 <link rel="next" href="summary.html" title="Summary of run-time 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="test_unit_filtering.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="summary.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.custom_command_line_arguments"></a><a class="link" href="custom_command_line_arguments.html" title="Custom command line arguments">Custom
  28       command line arguments</a>
  29 </h3></div></div></div>
  30 <p>
  31         It is possible to pass custom command line arguments to the test module.
  32         The general format for passing custom arguments is the following:
  33       </p>
  34 <pre class="programlisting"><span class="special">&lt;</span><span class="identifier">boost_test_module</span><span class="special">&gt;</span> <span class="special">[&lt;</span><span class="identifier">boost_test_arg1</span><span class="special">&gt;...]</span> <span class="special">[--</span> <span class="special">[&lt;</span><span class="identifier">custom_parameter1</span><span class="special">&gt;...]</span>
  35 </pre>
  36 <p>
  37         This means that everything that is passed after "<code class="computeroutput"><span class="special">--</span></code>"
  38         is considered as a custom parameter and will not be intercepted nor interpreted
  39         by the <span class="emphasis"><em>Unit Test Framework</em></span>. This avoids any troubleshooting
  40         between the <span class="emphasis"><em>Unit Test Framework</em></span> parameters and the custom
  41         ones.
  42       </p>
  43 <p>
  44         There are several use cases for accessing the arguments passed on the command
  45         line:
  46       </p>
  47 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  48 <li class="listitem">
  49             instantiating an object used in test cases and which is dependant on
  50             parameters external to the test-module: the name of the graphic card,
  51             the credentials for a database connection, etc. The rest of the test
  52             module would check that the functions in test are not sensitive to this
  53             type of parametrization. One can also imagine running this same test
  54             module with different parameters (different graphic cards...) in a batched
  55             manner,
  56           </li>
  57 <li class="listitem">
  58             modifying the test tree by adding or parametrizing test cases: the arguments
  59             passed on the command line may contain for instance a set of parameters
  60             that define test cases.
  61           </li>
  62 </ul></div>
  63 <p>
  64         In the first scenario, <a class="link" href="custom_command_line_arguments.html#ref_consuming_cmd_test_case">test cases</a>
  65         or fixtures, including <a class="link" href="custom_command_line_arguments.html#ref_consuming_cmd_global_fixture">global
  66         fixtures</a>, may be used. Since those are part of the test tree, they
  67         can benefit from the <span class="emphasis"><em>Unit Test Framework</em></span> rich set of
  68         assertions and controlled execution environment.
  69       </p>
  70 <p>
  71         In the second scenario, the command line argument interact directly with
  72         the content of the test tree: by passing specific arguments, different set
  73         of tests are created. There are mainly two options for achieving this: using
  74         a dedicated <a class="link" href="custom_command_line_arguments.html#ref_consuming_cmd_init_function">initialization
  75         function</a> or using <a class="link" href="custom_command_line_arguments.html#ref_consuming_cmd_dataset">data driven</a>
  76         test cases. The error handling of the command line parameters needs however
  77         to be adapted.
  78       </p>
  79 <a name="ref_consuming_cmd_test_case"></a><h5>
  80 <a name="boost_test.runtime_config.custom_command_line_arguments.h0"></a>
  81         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.consuming_custom_arguments_from_"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.consuming_custom_arguments_from_">Consuming
  82         custom arguments from a test case</a>
  83       </h5>
  84 <p>
  85         The <a class="link" href="../tests_organization/test_tree/master_test_suite.html" title="Master test suite">master
  86         test suite</a> collects the custom arguments passed to the test module
  87         in the following way:
  88       </p>
  89 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  90 <li class="listitem">
  91             <code class="computeroutput"><span class="identifier">argv</span><span class="special">[</span><span class="number">0</span><span class="special">]</span></code>, usually
  92             set by the operating system as the executable name, remains unchanged
  93           </li>
  94 <li class="listitem">
  95             any argument interpreted by the test module is removed from <code class="computeroutput"><span class="identifier">argv</span></code>
  96           </li>
  97 <li class="listitem">
  98             the empty token <code class="computeroutput"><span class="special">--</span></code> is removed
  99             as well
 100           </li>
 101 <li class="listitem">
 102             any additional argument passed after the empty token is reported in
 103             <code class="computeroutput"><span class="identifier">argv</span></code> starting at index
 104             <code class="computeroutput"><span class="number">1</span></code>
 105           </li>
 106 </ul></div>
 107 <h6>
 108 <a name="boost_test.runtime_config.custom_command_line_arguments.h1"></a>
 109         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.example_descr"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.example_descr">Example:
 110         Basic custom command line</a>
 111       </h6>
 112 <div class="informaltable"><table class="table">
 113 <colgroup><col></colgroup>
 114 <thead><tr><th>
 115                 <p>
 116                   Code
 117                 </p>
 118               </th></tr></thead>
 119 <tbody><tr><td>
 120 <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">runtime_configuration1</span>
 121 <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>
 122 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 123
 124 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_accessing_command_line</span><span class="special">)</span>
 125 <span class="special">{</span>
 126     <span class="identifier">BOOST_TEST_REQUIRE</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">==</span> <span class="number">3</span> <span class="special">);</span>
 127     <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">==</span> <span class="string">"--specific-param"</span> <span class="special">);</span>
 128     <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">==</span> <span class="string">"'additional value with quotes'"</span> <span class="special">);</span>
 129     <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span> <span class="string">"'argv[0]' contains "</span> <span class="special">&lt;&lt;</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">);</span>
 130 <span class="special">}</span>
 131 </pre>
 132               </td></tr></tbody>
 133 </table></div>
 134 <div class="informaltable"><table class="table">
 135 <colgroup><col></colgroup>
 136 <thead><tr><th>
 137                 <p>
 138                   Output
 139                 </p>
 140               </th></tr></thead>
 141 <tbody><tr><td>
 142 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">runtime_configuration1</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span> <span class="special">--</span><span class="identifier">no_color</span> <span class="special">--</span> <span class="special">--</span><span class="identifier">specific</span><span class="special">-</span><span class="identifier">param</span> <span class="string">"'additional value with quotes'"</span>
 143 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 144 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration"</span>
 145 <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_accessing_command_line"</span>
 146 <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">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">==</span> <span class="number">3</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 147 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">==</span> <span class="string">"--specific-param"</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 148 <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">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">==</span> <span class="string">"'additional value with quotes'"</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 149 <span class="char">'argv[0]'</span> <span class="identifier">contains</span> <span class="identifier">runtime_configuration1</span>
 150 <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_accessing_command_line"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">178u</span><span class="identifier">s</span>
 151 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">220u</span><span class="identifier">s</span>
 152
 153 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 154 </pre>
 155               </td></tr></tbody>
 156 </table></div>
 157 <a name="ref_consuming_cmd_global_fixture"></a><h5>
 158 <a name="boost_test.runtime_config.custom_command_line_arguments.h2"></a>
 159         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.consuming_custom_arguments_from0"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.consuming_custom_arguments_from0">Consuming
 160         custom arguments from a global fixture</a>
 161       </h5>
 162 <p>
 163         Another possibility for consuming the custom command line arguments would
 164         be from within a <a class="link" href="../tests_organization/fixtures/global.html" title="Global fixture">global
 165         fixture</a>. This is especially useful when external parameters are needed
 166         for instantiating global objects used in the test module.
 167       </p>
 168 <p>
 169         The usage is the same as for test cases. The following example runs the test
 170         module twice with different arguments, and illustrate the feature.
 171       </p>
 172 <div class="tip"><table border="0" summary="Tip">
 173 <tr>
 174 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
 175 <th align="left">Tip</th>
 176 </tr>
 177 <tr><td align="left" valign="top"><p>
 178           The global fixture can check for the correctness of the custom arguments
 179           and may abort the full run of the test module.
 180         </p></td></tr>
 181 </table></div>
 182 <h6>
 183 <a name="boost_test.runtime_config.custom_command_line_arguments.h3"></a>
 184         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.example_descr0"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.example_descr0">Example:
 185         Command line arguments interpreted in a global fixtures</a>
 186       </h6>
 187 <div class="informaltable"><table class="table">
 188 <colgroup><col></colgroup>
 189 <thead><tr><th>
 190                 <p>
 191                   Code
 192                 </p>
 193               </th></tr></thead>
 194 <tbody><tr><td>
 195 <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">runtime_configuration2</span>
 196 <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>
 197 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 198
 199 <span class="comment">/// The interface with the device driver.</span>
 200 <span class="keyword">class</span> <span class="identifier">DeviceInterface</span> <span class="special">{</span>
 201 <span class="keyword">public</span><span class="special">:</span>
 202     <span class="comment">// acquires a specific device based on its name</span>
 203     <span class="keyword">static</span> <span class="identifier">DeviceInterface</span><span class="special">*</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">device_name</span><span class="special">);</span>
 204     <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">DeviceInterface</span><span class="special">(){}</span>
 205
 206     <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">setup</span><span class="special">()</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 207     <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">teardown</span><span class="special">()</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 208     <span class="keyword">virtual</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_device_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 209 <span class="special">};</span>
 210
 211 <span class="keyword">class</span> <span class="identifier">MockDevice</span><span class="special">:</span> <span class="keyword">public</span> <span class="identifier">DeviceInterface</span> <span class="special">{</span>
 212     <span class="keyword">bool</span> <span class="identifier">setup</span><span class="special">()</span> <span class="identifier">final</span> <span class="special">{</span>
 213         <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 214     <span class="special">}</span>
 215     <span class="keyword">bool</span> <span class="identifier">teardown</span><span class="special">()</span> <span class="identifier">final</span> <span class="special">{</span>
 216         <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 217     <span class="special">}</span>
 218     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_device_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span>
 219         <span class="keyword">return</span> <span class="string">"mock_device"</span><span class="special">;</span>
 220     <span class="special">}</span>
 221 <span class="special">};</span>
 222
 223 <span class="identifier">DeviceInterface</span><span class="special">*</span> <span class="identifier">DeviceInterface</span><span class="special">::</span><span class="identifier">factory</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">device_name</span><span class="special">)</span> <span class="special">{</span>
 224     <span class="keyword">if</span><span class="special">(</span><span class="identifier">device_name</span> <span class="special">==</span> <span class="string">"mock_device"</span><span class="special">)</span> <span class="special">{</span>
 225         <span class="keyword">return</span> <span class="keyword">new</span> <span class="identifier">MockDevice</span><span class="special">();</span>
 226     <span class="special">}</span>
 227     <span class="keyword">return</span> <span class="keyword">nullptr</span><span class="special">;</span>
 228 <span class="special">}</span>
 229
 230 <span class="keyword">struct</span> <span class="identifier">CommandLineDeviceInit</span> <span class="special">{</span>
 231   <span class="identifier">CommandLineDeviceInit</span><span class="special">()</span> <span class="special">{</span>
 232       <span class="identifier">BOOST_TEST_REQUIRE</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">==</span> <span class="number">3</span> <span class="special">);</span>
 233       <span class="identifier">BOOST_TEST_REQUIRE</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">==</span> <span class="string">"--device-name"</span> <span class="special">);</span>
 234   <span class="special">}</span>
 235   <span class="keyword">void</span> <span class="identifier">setup</span><span class="special">()</span> <span class="special">{</span>
 236       <span class="identifier">device</span> <span class="special">=</span> <span class="identifier">DeviceInterface</span><span class="special">::</span><span class="identifier">factory</span><span class="special">(</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]);</span>
 237       <span class="identifier">BOOST_TEST_REQUIRE</span><span class="special">(</span>
 238         <span class="identifier">device</span> <span class="special">!=</span> <span class="keyword">nullptr</span><span class="special">,</span>
 239         <span class="string">"Cannot create the device "</span> <span class="special">&lt;&lt;</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">);</span>
 240       <span class="identifier">BOOST_TEST_REQUIRE</span><span class="special">(</span>
 241         <span class="identifier">device</span><span class="special">-&gt;</span><span class="identifier">setup</span><span class="special">(),</span>
 242         <span class="string">"Cannot initialize the device "</span> <span class="special">&lt;&lt;</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">);</span>
 243   <span class="special">}</span>
 244   <span class="keyword">void</span> <span class="identifier">teardown</span><span class="special">()</span> <span class="special">{</span>
 245       <span class="keyword">if</span><span class="special">(</span><span class="identifier">device</span><span class="special">)</span> <span class="special">{</span>
 246         <span class="identifier">BOOST_TEST</span><span class="special">(</span>
 247           <span class="identifier">device</span><span class="special">-&gt;</span><span class="identifier">teardown</span><span class="special">(),</span>
 248           <span class="string">"Cannot tear-down the device "</span> <span class="special">&lt;&lt;</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]);</span>
 249       <span class="special">}</span>
 250       <span class="keyword">delete</span> <span class="identifier">device</span><span class="special">;</span>
 251   <span class="special">}</span>
 252   <span class="keyword">static</span> <span class="identifier">DeviceInterface</span> <span class="special">*</span><span class="identifier">device</span><span class="special">;</span>
 253 <span class="special">};</span>
 254 <span class="identifier">DeviceInterface</span><span class="special">*</span> <span class="identifier">CommandLineDeviceInit</span><span class="special">::</span><span class="identifier">device</span> <span class="special">=</span> <span class="keyword">nullptr</span><span class="special">;</span>
 255
 256 <span class="identifier">BOOST_TEST_GLOBAL_FIXTURE</span><span class="special">(</span> <span class="identifier">CommandLineDeviceInit</span> <span class="special">);</span>
 257
 258 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">check_device_has_meaningful_name</span><span class="special">)</span>
 259 <span class="special">{</span>
 260     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">CommandLineDeviceInit</span><span class="special">::</span><span class="identifier">device</span><span class="special">-&gt;</span><span class="identifier">get_device_name</span><span class="special">()</span> <span class="special">!=</span> <span class="string">""</span><span class="special">);</span>
 261 <span class="special">}</span>
 262 </pre>
 263               </td></tr></tbody>
 264 </table></div>
 265 <div class="informaltable"><table class="table">
 266 <colgroup><col></colgroup>
 267 <thead><tr><th>
 268                 <p>
 269                   Output
 270                 </p>
 271               </th></tr></thead>
 272 <tbody><tr><td>
 273 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">1</span>
 274 <span class="special">&gt;</span> <span class="identifier">runtime_configuration2</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>  <span class="special">--</span> <span class="special">--</span><span class="identifier">some</span><span class="special">-</span><span class="identifier">wrong</span><span class="special">-</span><span class="identifier">random</span><span class="special">-</span><span class="identifier">string</span> <span class="identifier">mock_device</span>
 275 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 276 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration2"</span>
 277 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">46</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">==</span> <span class="number">3</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 278 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">47</span><span class="special">:</span> <span class="identifier">fatal</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"runtime_configuration2"</span><span class="special">:</span> <span class="identifier">critical</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">==</span> <span class="string">"--device-name"</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[--</span><span class="identifier">some</span><span class="special">-</span><span class="identifier">wrong</span><span class="special">-</span><span class="identifier">random</span><span class="special">-</span><span class="identifier">string</span> <span class="special">!=</span> <span class="special">--</span><span class="identifier">device</span><span class="special">-</span><span class="identifier">name</span><span class="special">]</span>
 279 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration2"</span>
 280
 281 <span class="special">***</span> <span class="identifier">The</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration2"</span> <span class="identifier">was</span> <span class="identifier">aborted</span><span class="special">;</span> <span class="identifier">see</span> <span class="identifier">standard</span> <span class="identifier">output</span> <span class="keyword">for</span> <span class="identifier">details</span>
 282 <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">"runtime_configuration2"</span>
 283
 284 <span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">2</span>
 285 <span class="special">&gt;</span> <span class="identifier">runtime_configuration2</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span> <span class="special">--</span> <span class="special">--</span><span class="identifier">device</span><span class="special">-</span><span class="identifier">name</span> <span class="identifier">mock_device</span>
 286 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 287 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration2"</span>
 288 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">46</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">==</span> <span class="number">3</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 289 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">47</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">==</span> <span class="string">"--device-name"</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 290 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">53</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="char">'Cannot create the device mock_device'</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 291 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">56</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="char">'Cannot initialize the device mock_device'</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 292 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">72</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"check_device_has_meaningful_name"</span>
 293 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">74</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">CommandLineDeviceInit</span><span class="special">::</span><span class="identifier">device</span><span class="special">-&gt;</span><span class="identifier">get_device_name</span><span class="special">()</span> <span class="special">!=</span> <span class="string">""</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 294 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">72</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"check_device_has_meaningful_name"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">127u</span><span class="identifier">s</span>
 295 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">62</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="char">'Cannot tear-down the device mock_device'</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 296 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration2"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">177u</span><span class="identifier">s</span>
 297
 298 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 299 </pre>
 300               </td></tr></tbody>
 301 </table></div>
 302 <p>
 303         The above example instantiates a specific device through the <code class="computeroutput"><span class="identifier">DeviceInterface</span><span class="special">::</span><span class="identifier">factory</span></code> member function. The name of the
 304         device to instantiate is passed via the command line argument <code class="computeroutput"><span class="special">--</span><span class="identifier">device</span><span class="special">-</span><span class="identifier">name</span></code>,
 305         and the instantiated device is available through the global object <code class="computeroutput"><span class="identifier">CommandLineDeviceInit</span><span class="special">::</span><span class="identifier">device</span></code>. The module requires <code class="computeroutput"><span class="number">3</span></code> arguments on the command line:
 306       </p>
 307 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 308 <li class="listitem">
 309             <code class="computeroutput"><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">0</span><span class="special">]</span></code> is the
 310             test module name as explained in the previous paragraph
 311           </li>
 312 <li class="listitem">
 313             <code class="computeroutput"><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">]</span></code> should
 314             be equal to <code class="computeroutput"><span class="special">--</span><span class="identifier">device</span><span class="special">-</span><span class="identifier">name</span></code>
 315           </li>
 316 <li class="listitem">
 317             <code class="computeroutput"><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]</span></code> should
 318             be the name of the device to instantiate
 319           </li>
 320 </ul></div>
 321 <p>
 322         As it can be seen in the shell outputs, any command line argument consumed
 323         by the <span class="emphasis"><em>Unit Test Framework</em></span> is removed from <code class="computeroutput"><span class="identifier">argc</span></code> / <code class="computeroutput"><span class="identifier">argv</span></code>.
 324         Since global fixtures are running in the <span class="emphasis"><em>Unit Test Framework</em></span>
 325         controlled environment, any fatal error reported by the fixture (through
 326         the <a class="link" href="../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST_REQUIRE</span></code></a> assertion) aborts
 327         the test execution. Non fatal errors on the other hand do not abort the test-module
 328         and are reported as assertion failure, and would not prevent the execution
 329         of the test case <code class="computeroutput"><span class="identifier">check_device_has_meaningful_name</span></code>.
 330       </p>
 331 <div class="note"><table border="0" summary="Note">
 332 <tr>
 333 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
 334 <th align="left">Note</th>
 335 </tr>
 336 <tr><td align="left" valign="top"><p>
 337           It is possible to have several global fixtures in a test module, spread
 338           over several compilation units. Each of those fixture may in turn be accessing
 339           a specific part of the command line.
 340         </p></td></tr>
 341 </table></div>
 342 <a name="ref_consuming_cmd_init_function"></a><h5>
 343 <a name="boost_test.runtime_config.custom_command_line_arguments.h4"></a>
 344         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.parametrizing_the_test_tree_from"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.parametrizing_the_test_tree_from">Parametrizing
 345         the test tree from command line in the initialization function</a>
 346       </h5>
 347 <p>
 348         The initialization function are described in details in this <a class="link" href="../adv_scenarios/test_module_init_overview.html" title="Test module's initialization">section</a>.
 349         The initialization function is called before any other test or fixture, and
 350         before entering the master test suite. The initialization function is not
 351         considered as a test-case, although it is called under the controlled execution
 352         environment of the <span class="emphasis"><em>Unit Test Framework</em></span>. This means that:
 353       </p>
 354 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 355 <li class="listitem">
 356             the errors will be properly handled,
 357           </li>
 358 <li class="listitem">
 359             loggers are not fully operational,
 360           </li>
 361 <li class="listitem">
 362             it is not possible to use the <span class="emphasis"><em>Unit Test Framework</em></span>
 363             assertion macros like <a class="link" href="../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> as it is not a test-case.
 364           </li>
 365 </ul></div>
 366 <p>
 367         The following example shows how to use the command line arguments parsing
 368         described above to create/add new test cases to the test tree. It also shows
 369         very limited support to messages (does not work for all loggers), and error
 370         handling.
 371       </p>
 372 <h6>
 373 <a name="boost_test.runtime_config.custom_command_line_arguments.h5"></a>
 374         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.example_descr1"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.example_descr1">Example:
 375         Init function parametrized from the command line</a>
 376       </h6>
 377 <div class="informaltable"><table class="table">
 378 <colgroup><col></colgroup>
 379 <thead><tr><th>
 380                 <p>
 381                   Code
 382                 </p>
 383               </th></tr></thead>
 384 <tbody><tr><td>
 385 <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_ALTERNATIVE_INIT_API</span>
 386 <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>
 387 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span>
 388 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
 389
 390 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 391
 392 <span class="keyword">void</span> <span class="identifier">test_function</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span>
 393   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">i</span> <span class="special">&gt;=</span> <span class="number">1</span><span class="special">);</span>
 394 <span class="special">}</span>
 395
 396 <span class="comment">// helper</span>
 397 <span class="keyword">int</span> <span class="identifier">read_integer</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&amp;</span><span class="identifier">str</span><span class="special">)</span> <span class="special">{</span>
 398   <span class="identifier">std</span><span class="special">::</span><span class="identifier">istringstream</span> <span class="identifier">buff</span><span class="special">(</span> <span class="identifier">str</span> <span class="special">);</span>
 399   <span class="keyword">int</span> <span class="identifier">number</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 400   <span class="identifier">buff</span> <span class="special">&gt;&gt;</span> <span class="identifier">number</span><span class="special">;</span>
 401   <span class="keyword">if</span><span class="special">(</span><span class="identifier">buff</span><span class="special">.</span><span class="identifier">fail</span><span class="special">())</span> <span class="special">{</span>
 402     <span class="comment">// it is also possible to raise a boost.test specific exception.</span>
 403     <span class="keyword">throw</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">setup_error</span><span class="special">(</span><span class="string">"Argument '"</span> <span class="special">+</span> <span class="identifier">str</span> <span class="special">+</span> <span class="string">"' not integer"</span><span class="special">);</span>
 404   <span class="special">}</span>
 405   <span class="keyword">return</span> <span class="identifier">number</span><span class="special">;</span>
 406 <span class="special">}</span>
 407
 408 <span class="keyword">bool</span> <span class="identifier">init_unit_test</span><span class="special">()</span>
 409 <span class="special">{</span>
 410   <span class="keyword">int</span> <span class="identifier">argc</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span><span class="special">;</span>
 411   <span class="keyword">char</span><span class="special">**</span> <span class="identifier">argv</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">;</span>
 412
 413   <span class="keyword">if</span><span class="special">(</span> <span class="identifier">argc</span> <span class="special">&lt;=</span> <span class="number">1</span><span class="special">)</span> <span class="special">{</span>
 414       <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span> <span class="comment">// returning false to indicate an error</span>
 415   <span class="special">}</span>
 416
 417   <span class="keyword">if</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">])</span> <span class="special">==</span> <span class="string">"--create-parametrized"</span> <span class="special">)</span> <span class="special">{</span>
 418     <span class="keyword">if</span><span class="special">(</span><span class="identifier">argc</span> <span class="special">&lt;</span> <span class="number">3</span><span class="special">)</span> <span class="special">{</span>
 419       <span class="comment">// the logging availability depends on the logger type</span>
 420       <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"Not enough parameters"</span><span class="special">);</span>
 421       <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 422     <span class="special">}</span>
 423
 424     <span class="keyword">int</span> <span class="identifier">number_tests</span> <span class="special">=</span> <span class="identifier">read_integer</span><span class="special">(</span><span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">]);</span>
 425     <span class="keyword">int</span> <span class="identifier">test_start</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 426     <span class="keyword">if</span><span class="special">(</span><span class="identifier">argc</span> <span class="special">&gt;</span> <span class="number">3</span><span class="special">)</span> <span class="special">{</span>
 427         <span class="identifier">test_start</span> <span class="special">=</span> <span class="identifier">read_integer</span><span class="special">(</span><span class="identifier">argv</span><span class="special">[</span><span class="number">3</span><span class="special">]);</span>
 428     <span class="special">}</span>
 429
 430     <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">test_start</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">number_tests</span><span class="special">;</span> <span class="identifier">i</span><span class="special">++)</span> <span class="special">{</span>
 431         <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">ostr</span><span class="special">;</span>
 432         <span class="identifier">ostr</span> <span class="special">&lt;&lt;</span> <span class="string">"name "</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">;</span>
 433         <span class="comment">// create test-cases, avoiding duplicate names</span>
 434         <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
 435             <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE_NAME</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&amp;</span><span class="identifier">test_function</span><span class="special">,</span> <span class="identifier">i</span><span class="special">),</span> <span class="identifier">ostr</span><span class="special">.</span><span class="identifier">str</span><span class="special">().</span><span class="identifier">c_str</span><span class="special">()</span> <span class="special">)</span> <span class="special">);</span>
 436     <span class="special">}</span>
 437   <span class="special">}</span>
 438   <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 439 <span class="special">}</span>
 440 </pre>
 441               </td></tr></tbody>
 442 </table></div>
 443 <div class="informaltable"><table class="table">
 444 <colgroup><col></colgroup>
 445 <thead><tr><th>
 446                 <p>
 447                   Output
 448                 </p>
 449               </th></tr></thead>
 450 <tbody><tr><td>
 451 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">1</span>
 452 <span class="special">&gt;</span> <span class="identifier">runtime_configuration3</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>  <span class="special">--</span> <span class="special">--</span><span class="identifier">create</span><span class="special">-</span><span class="identifier">parametrized</span> <span class="number">3</span>
 453 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 454 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span>
 455 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">59</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"name 0"</span>
 456 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"name 0"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special">&gt;=</span> <span class="number">1</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">0</span> <span class="special">&lt;</span> <span class="number">1</span><span class="special">]</span>
 457 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">59</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"name 0"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">179u</span><span class="identifier">s</span>
 458 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">59</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"name 1"</span>
 459 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special">&gt;=</span> <span class="number">1</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 460 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">59</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"name 1"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">45u</span><span class="identifier">s</span>
 461 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">59</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"name 2"</span>
 462 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special">&gt;=</span> <span class="number">1</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 463 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">59</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"name 2"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">34u</span><span class="identifier">s</span>
 464 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">443u</span><span class="identifier">s</span>
 465
 466 <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">"Master Test Suite"</span>
 467
 468 <span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">2</span>
 469 <span class="special">&gt;</span> <span class="identifier">runtime_configuration3</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>  <span class="special">--</span> <span class="special">--</span><span class="identifier">create</span><span class="special">-</span><span class="identifier">parametrized</span>
 470 <span class="identifier">Not</span> <span class="identifier">enough</span> <span class="identifier">parameters</span>
 471 <span class="identifier">Test</span> <span class="identifier">setup</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">:</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="identifier">initialization</span> <span class="identifier">failed</span>
 472
 473 <span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">3</span>
 474 <span class="special">&gt;</span> <span class="identifier">runtime_configuration3</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>  <span class="special">--</span> <span class="special">--</span><span class="identifier">create</span><span class="special">-</span><span class="identifier">parametrized</span> <span class="identifier">dummy</span>
 475 <span class="identifier">Test</span> <span class="identifier">setup</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">setup_error</span><span class="special">:</span> <span class="identifier">Argument</span> <span class="char">'dummy'</span> <span class="keyword">not</span> <span class="identifier">integer</span>
 476 </pre>
 477               </td></tr></tbody>
 478 </table></div>
 479 <p>
 480         As seen in this example, the error handling is quite different than a regular
 481         test-case:
 482       </p>
 483 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 484 <li class="listitem">
 485             For the <span class="emphasis"><em>alternative</em></span> initialization API (see <a class="link" href="../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>),
 486             the easiest way to indicate an error would be to return <code class="computeroutput"><span class="keyword">false</span></code> in case of failure.
 487           </li>
 488 <li class="listitem">
 489             For the <span class="emphasis"><em>obsolete</em></span> and <span class="emphasis"><em>alternative</em></span>,
 490             raising an exception such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code>
 491             or <code class="computeroutput"><a class="link" href="../../boost/unit_test/framework/setup_error.html" title="Struct setup_error">boost::unit_test::framework::setup_error</a></code>
 492             as above works as well.
 493           </li>
 494 </ul></div>
 495 <a name="ref_consuming_cmd_dataset"></a><h5>
 496 <a name="boost_test.runtime_config.custom_command_line_arguments.h6"></a>
 497         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.data_driven_test_cases_parametri"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.data_driven_test_cases_parametri">Data-driven
 498         test cases parametrized from the command line</a>
 499       </h5>
 500 <p>
 501         It is possible to use the command line arguments to manipulate the dataset
 502         generated by a data-drive test case.
 503       </p>
 504 <p>
 505         By default, datasets are created before entering the <code class="computeroutput"><span class="identifier">main</span></code>
 506         of the test module, and try to be efficient in the number of copies of their
 507         arguments. It is however possible to indicate a delay for the evaluation
 508         of the dataset by constructing the dataset with the <code class="computeroutput"><span class="identifier">make_delayed</span></code>
 509         function.
 510       </p>
 511 <p>
 512         With the <code class="computeroutput"><span class="identifier">make_delayed</span></code>, the
 513         construction of the dataset will happen at the same time as the construction
 514         of the test tree during the test module initialization, and not before. It
 515         is this way possible to access the <a class="link" href="../tests_organization/test_tree/master_test_suite.html" title="Master test suite">master
 516         test suite</a> and its command line arguments.
 517       </p>
 518 <p>
 519         The example below shows a complex dataset generation from the content of
 520         an external file. The data contained in the file participates to the definition
 521         of the test case.
 522       </p>
 523 <h6>
 524 <a name="boost_test.runtime_config.custom_command_line_arguments.h7"></a>
 525         <span class="phrase"><a name="boost_test.runtime_config.custom_command_line_arguments.example_descr2"></a></span><a class="link" href="custom_command_line_arguments.html#boost_test.runtime_config.custom_command_line_arguments.example_descr2">Example:
 526         Dataset test case parametrized from the command line</a>
 527       </h6>
 528 <div class="informaltable"><table class="table">
 529 <colgroup><col></colgroup>
 530 <thead><tr><th>
 531                 <p>
 532                   Code
 533                 </p>
 534               </th></tr></thead>
 535 <tbody><tr><td>
 536 <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">runtime_configuration4</span>
 537
 538 <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>
 539 <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">data</span><span class="special">/</span><span class="identifier">test_case</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 540
 541 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 542 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">functional</span><span class="special">&gt;</span>
 543 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">sstream</span><span class="special">&gt;</span>
 544 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">fstream</span><span class="special">&gt;</span>
 545
 546 <span class="comment">// this dataset loads a file that contains a list of strings</span>
 547 <span class="comment">// this list is used to create a dataset test case.</span>
 548 <span class="keyword">class</span> <span class="identifier">file_dataset</span>
 549 <span class="special">{</span>
 550 <span class="keyword">private</span><span class="special">:</span>
 551     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">m_filename</span><span class="special">;</span>
 552     <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">m_line_start</span><span class="special">;</span>
 553     <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">m_line_end</span><span class="special">;</span>
 554
 555 <span class="keyword">public</span><span class="special">:</span>
 556     <span class="keyword">enum</span> <span class="special">{</span> <span class="identifier">arity</span> <span class="special">=</span> <span class="number">2</span> <span class="special">};</span>
 557
 558 <span class="keyword">public</span><span class="special">:</span>
 559     <span class="identifier">file_dataset</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">line_start</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">line_end</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">(-</span><span class="number">1</span><span class="special">))</span>
 560     <span class="special">:</span> <span class="identifier">m_line_start</span><span class="special">(</span><span class="identifier">line_start</span><span class="special">)</span>
 561     <span class="special">,</span> <span class="identifier">m_line_end</span><span class="special">(</span><span class="identifier">line_end</span><span class="special">)</span>
 562     <span class="special">{</span>
 563       <span class="keyword">int</span> <span class="identifier">argc</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span><span class="special">;</span>
 564       <span class="keyword">char</span><span class="special">**</span> <span class="identifier">argv</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span><span class="special">;</span>
 565
 566       <span class="keyword">if</span><span class="special">(</span><span class="identifier">argc</span> <span class="special">!=</span> <span class="number">3</span><span class="special">)</span>
 567         <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span><span class="special">(</span><span class="string">"Incorrect number of arguments"</span><span class="special">);</span>
 568       <span class="keyword">if</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="identifier">argv</span><span class="special">[</span><span class="number">1</span><span class="special">])</span> <span class="special">!=</span> <span class="string">"--test-file"</span><span class="special">)</span>
 569         <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span><span class="special">(</span><span class="string">"First argument != '--test-file'"</span><span class="special">);</span>
 570       <span class="keyword">if</span><span class="special">(!(</span><span class="identifier">m_line_start</span> <span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">(-</span><span class="number">1</span><span class="special">)))</span>
 571         <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span><span class="special">(</span><span class="string">"Incorrect line start/end"</span><span class="special">);</span>
 572
 573       <span class="identifier">m_filename</span> <span class="special">=</span> <span class="identifier">argv</span><span class="special">[</span><span class="number">2</span><span class="special">];</span>
 574
 575       <span class="identifier">std</span><span class="special">::</span><span class="identifier">ifstream</span> <span class="identifier">file</span><span class="special">(</span><span class="identifier">m_filename</span><span class="special">);</span>
 576       <span class="keyword">if</span><span class="special">(!</span><span class="identifier">file</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">())</span>
 577         <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span><span class="special">(</span><span class="string">"Cannot open the file '"</span> <span class="special">+</span> <span class="identifier">m_filename</span> <span class="special">+</span> <span class="string">"'"</span><span class="special">);</span>
 578       <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">nb_lines</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">count_if</span><span class="special">(</span>
 579         <span class="identifier">std</span><span class="special">::</span><span class="identifier">istreambuf_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">file</span><span class="special">),</span>
 580         <span class="identifier">std</span><span class="special">::</span><span class="identifier">istreambuf_iterator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(),</span>
 581         <span class="special">[](</span><span class="keyword">char</span> <span class="identifier">c</span><span class="special">){</span> <span class="keyword">return</span> <span class="identifier">c</span> <span class="special">==</span> <span class="char">'\n'</span><span class="special">;});</span>
 582
 583       <span class="identifier">m_line_end</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">min</span><span class="special">)(</span><span class="identifier">nb_lines</span><span class="special">,</span> <span class="identifier">m_line_end</span><span class="special">);</span>
 584       <span class="keyword">if</span><span class="special">(!(</span><span class="identifier">m_line_start</span> <span class="special">&lt;=</span> <span class="identifier">m_line_end</span><span class="special">))</span>
 585         <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span><span class="special">(</span><span class="string">"Incorrect line start/end"</span><span class="special">);</span>
 586     <span class="special">}</span>
 587
 588     <span class="keyword">struct</span> <span class="identifier">iterator</span> <span class="special">{</span>
 589         <span class="identifier">iterator</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">filename</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">line_start</span><span class="special">)</span>
 590         <span class="special">:</span> <span class="identifier">file</span><span class="special">(</span><span class="identifier">filename</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios</span><span class="special">::</span><span class="identifier">binary</span><span class="special">)</span> <span class="special">{</span>
 591           <span class="keyword">if</span><span class="special">(!</span><span class="identifier">file</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">())</span>
 592             <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span><span class="string">"Cannot open the file"</span><span class="special">);</span>
 593           <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">line_start</span><span class="special">;</span> <span class="identifier">i</span><span class="special">++)</span> <span class="special">{</span>
 594             <span class="identifier">getline</span><span class="special">(</span><span class="identifier">file</span><span class="special">,</span> <span class="identifier">m_current_line</span><span class="special">);</span>
 595           <span class="special">}</span>
 596         <span class="special">}</span>
 597
 598         <span class="keyword">auto</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span> <span class="special">-&gt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">,</span> <span class="keyword">float</span><span class="special">&gt;</span> <span class="special">{</span>
 599           <span class="keyword">float</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">;</span>
 600           <span class="identifier">std</span><span class="special">::</span><span class="identifier">istringstream</span> <span class="identifier">istr</span><span class="special">(</span><span class="identifier">m_current_line</span><span class="special">);</span>
 601           <span class="identifier">istr</span> <span class="special">&gt;&gt;</span> <span class="identifier">a</span> <span class="special">&gt;&gt;</span> <span class="identifier">b</span><span class="special">;</span>
 602           <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">,</span> <span class="keyword">float</span><span class="special">&gt;(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">);</span>
 603         <span class="special">}</span>
 604
 605         <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">++()</span> <span class="special">{</span>
 606           <span class="identifier">getline</span><span class="special">(</span><span class="identifier">file</span><span class="special">,</span> <span class="identifier">m_current_line</span><span class="special">);</span>
 607         <span class="special">}</span>
 608     <span class="keyword">private</span><span class="special">:</span>
 609         <span class="identifier">std</span><span class="special">::</span><span class="identifier">ifstream</span> <span class="identifier">file</span><span class="special">;</span>
 610         <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">m_current_line</span><span class="special">;</span>
 611     <span class="special">};</span>
 612
 613     <span class="comment">// size of the DS</span>
 614     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span>
 615       <span class="keyword">return</span> <span class="identifier">m_line_end</span> <span class="special">-</span> <span class="identifier">m_line_start</span><span class="special">;</span>
 616     <span class="special">}</span>
 617
 618     <span class="comment">// iterator over the lines of the file</span>
 619     <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">()</span> <span class="keyword">const</span>   <span class="special">{</span>
 620       <span class="keyword">return</span> <span class="identifier">iterator</span><span class="special">(</span><span class="identifier">m_filename</span><span class="special">,</span> <span class="identifier">m_line_start</span><span class="special">);</span>
 621     <span class="special">}</span>
 622 <span class="special">};</span>
 623
 624 <span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">unit_test</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">data</span> <span class="special">{</span>
 625
 626 <span class="keyword">namespace</span> <span class="identifier">monomorphic</span> <span class="special">{</span>
 627   <span class="keyword">template</span> <span class="special">&lt;&gt;</span>
 628   <span class="keyword">struct</span> <span class="identifier">is_dataset</span><span class="special">&lt;</span><span class="identifier">file_dataset</span><span class="special">&gt;</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> <span class="special">{};</span>
 629 <span class="special">}</span>
 630 <span class="special">}}}</span>
 631
 632 <span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span><span class="identifier">command_line_test_file</span><span class="special">,</span>
 633     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">::</span><span class="identifier">make_delayed</span><span class="special">&lt;</span><span class="identifier">file_dataset</span><span class="special">&gt;(</span> <span class="number">3</span><span class="special">,</span> <span class="number">10</span> <span class="special">),</span>
 634     <span class="identifier">input</span><span class="special">,</span> <span class="identifier">expected</span><span class="special">)</span> <span class="special">{</span>
 635     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">input</span> <span class="special">&lt;=</span> <span class="identifier">expected</span><span class="special">);</span>
 636 <span class="special">}</span>
 637 </pre>
 638               </td></tr></tbody>
 639 </table></div>
 640 <div class="informaltable"><table class="table">
 641 <colgroup><col></colgroup>
 642 <thead><tr><th>
 643                 <p>
 644                   Output
 645                 </p>
 646               </th></tr></thead>
 647 <tbody><tr><td>
 648 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor"># content</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">file</span>
 649 <span class="special">&gt;</span> <span class="identifier">more</span> <span class="identifier">test_file</span><span class="special">.</span><span class="identifier">txt</span>
 650 <span class="number">10.2</span> <span class="number">30.4</span>
 651 <span class="number">10.3</span> <span class="number">30.2</span>
 652 <span class="number">15.987984</span> <span class="number">15.9992</span>
 653 <span class="number">15.997984</span> <span class="number">15.9962</span>
 654
 655 <span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">1</span>
 656 <span class="special">&gt;</span> <span class="identifier">runtime_configuration4</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>  <span class="special">--</span> <span class="special">--</span><span class="identifier">test</span><span class="special">-</span><span class="identifier">file</span> <span class="identifier">test_file</span><span class="special">.</span><span class="identifier">txt</span>
 657 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 658 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration4"</span>
 659 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">107</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"command_line_test_file"</span>
 660 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">107</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"_0"</span>
 661 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">108</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">input</span> <span class="special">&lt;=</span> <span class="identifier">expected</span> <span class="identifier">has</span> <span class="identifier">passed</span>
 662 <span class="identifier">Assertion</span> <span class="identifier">occurred</span> <span class="identifier">in</span> <span class="identifier">a</span> <span class="identifier">following</span> <span class="identifier">context</span><span class="special">:</span>
 663     <span class="identifier">input</span> <span class="special">=</span> <span class="number">15.9879837</span><span class="special">;</span> <span class="identifier">expected</span> <span class="special">=</span> <span class="number">15.9991999</span><span class="special">;</span>
 664 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">107</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"_0"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">433u</span><span class="identifier">s</span>
 665 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">107</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"_1"</span>
 666 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">108</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"command_line_test_file/_1"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">input</span> <span class="special">&lt;=</span> <span class="identifier">expected</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">15.9979839</span> <span class="special">&gt;</span> <span class="number">15.9961996</span><span class="special">]</span>
 667 <span class="identifier">Failure</span> <span class="identifier">occurred</span> <span class="identifier">in</span> <span class="identifier">a</span> <span class="identifier">following</span> <span class="identifier">context</span><span class="special">:</span>
 668     <span class="identifier">input</span> <span class="special">=</span> <span class="number">15.9979839</span><span class="special">;</span> <span class="identifier">expected</span> <span class="special">=</span> <span class="number">15.9961996</span><span class="special">;</span>
 669 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">107</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"_1"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">114u</span><span class="identifier">s</span>
 670 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">107</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"command_line_test_file"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">616u</span><span class="identifier">s</span>
 671 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"runtime_configuration4"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">881u</span><span class="identifier">s</span>
 672
 673 <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">"runtime_configuration4"</span>
 674
 675 <span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">2</span>
 676 <span class="special">&gt;</span> <span class="identifier">runtime_configuration4</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>  <span class="special">--</span> <span class="special">--</span><span class="identifier">test</span><span class="special">-</span><span class="identifier">file</span> <span class="identifier">non</span><span class="special">-</span><span class="identifier">existant</span><span class="special">.</span><span class="identifier">txt</span>
 677 <span class="identifier">Test</span> <span class="identifier">setup</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">Cannot</span> <span class="identifier">open</span> <span class="identifier">the</span> <span class="identifier">file</span> <span class="char">'non-existant.txt'</span>
 678
 679 <span class="preprocessor"># Example</span> <span class="identifier">run</span> <span class="number">3</span>
 680 <span class="special">&gt;</span> <span class="identifier">runtime_configuration4</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
 681 <span class="identifier">Test</span> <span class="identifier">setup</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">Incorrect</span> <span class="identifier">number</span> <span class="identifier">of</span> <span class="identifier">arguments</span>
 682 </pre>
 683               </td></tr></tbody>
 684 </table></div>
 685 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 686 <li class="listitem">
 687             Using <code class="computeroutput"><span class="identifier">make_delayed</span></code>, the
 688             tests generated from a dataset are instantiated during the framework
 689             setup. This let the dataset generator access the <code class="computeroutput"><span class="identifier">argc</span></code>
 690             and <code class="computeroutput"><span class="identifier">argv</span></code> of the master
 691             test suite.
 692           </li>
 693 <li class="listitem">
 694             The generation of the test-cases out of this dataset happens before the
 695             global fixture are reached (and before any test cases), and after the
 696             initialization function.
 697           </li>
 698 <li class="listitem">
 699             The generator of the dataset is <span class="bold"><strong>not</strong></span>
 700             considered being a test case and the <span class="emphasis"><em>Unit Test Framework</em></span>
 701             assertions are not accessible. However, the <span class="emphasis"><em>Unit Test Framework</em></span>
 702             will catch the exceptions raised during the generation of the test-cases
 703             by the dataset. To report an error, a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span></code>
 704             or <code class="computeroutput"><a class="link" href="../../boost/unit_test/framework/setup_error.html" title="Struct setup_error">boost::unit_test::framework::setup_error</a></code>
 705             can be raised and will be reported by the <span class="emphasis"><em>Unit Test Framework</em></span>.
 706           </li>
 707 </ul></div>
 708 </div>
 709 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 710 <td align="left"></td>
 711 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 712       contributors<p>
 713         Distributed under the Boost Software License, Version 1.0. (See accompanying
 714         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>)
 715       </p>
 716 </div></td>
 717 </tr></table>
 718 <hr>
 719 <div class="spirit-nav">
 720 <a accesskey="p" href="test_unit_filtering.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="summary.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 721 </div>
 722 </body>
 723 </html>