1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>list_content</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="../rt_param_reference.html" title="Runtime parameters reference"> 9<link rel="prev" href="help.html" title="help"> 10<link rel="next" href="list_labels.html" title="list_labels"> 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="help.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rt_param_reference.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="list_labels.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_test.utf_reference.rt_param_reference.list_content"></a><a class="link" href="list_content.html" title="list_content"><code class="computeroutput"><span class="identifier">list_content</span></code></a> 28</h4></div></div></div> 29<p> 30 Lists the name of the <a class="link" href="../../section_glossary.html#ref_test_unit">test units</a> contained 31 in the <a class="link" href="../../section_glossary.html#ref_test_module">test module</a> and exits (no 32 test is run). 33 </p> 34<p> 35 This command line parameter accepts an <span class="emphasis"><em>optional</em></span> string 36 value indicating the format of the output. The framework supports the following 37 two formats: 38 </p> 39<div class="orderedlist"><ol class="orderedlist" type="1"> 40<li class="listitem"> 41 HRF (default), standing for <span class="emphasis"><em>Human Readable Format</em></span>, 42 </li> 43<li class="listitem"> 44 DOT, standing for the <a href="http://www.graphviz.org/doc/info/lang.html" target="_top">Graphviz 45 graph format</a>. This format may be automatically parsed or rendered. 46 </li> 47</ol></div> 48<h5> 49<a name="boost_test.utf_reference.rt_param_reference.list_content.h0"></a> 50 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.hrf"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.hrf">HRF</a> 51 </h5> 52<p> 53 For HRF, the <a class="link" href="../../section_glossary.html#ref_test_tree">test tree</a> (test suites 54 and test cases) is presented in a tree like form with each test unit name 55 on a separate line with horizontal indentation in relation to the parent 56 test suite. In addition, test units which are enabled by default have an 57 asterisk <code class="computeroutput"><span class="special">*</span></code> next to the test 58 unit name. For example, the following output: 59 </p> 60<pre class="programlisting"><span class="identifier">testsuite1</span><span class="special">*</span> 61 <span class="identifier">testcase1</span><span class="special">*</span> 62 <span class="identifier">testcase2</span> 63<span class="identifier">testsuite2</span><span class="special">*</span> 64 <span class="identifier">testcase3</span><span class="special">*</span> 65</pre> 66<p> 67 represents test module consisting of two test suites: <code class="computeroutput"><span class="identifier">testsuite1</span></code> 68 and <code class="computeroutput"><span class="identifier">testsuite2</span></code>, and three 69 test cases: <code class="computeroutput"><span class="identifier">testcase1</span></code>, 70 <code class="computeroutput"><span class="identifier">testcase2</span></code>, and <code class="computeroutput"><span class="identifier">testcase3</span></code>. The formatting reflects the 71 test-tree: the first two test cases belong to the first test suite and 72 last one belongs to the second. Out of three test cases only two are enabled 73 by default: <code class="computeroutput"><span class="identifier">testcase1</span></code> and 74 <code class="computeroutput"><span class="identifier">testcase3</span></code>. <code class="computeroutput"><span class="identifier">testcase2</span></code> is not enabled by default, 75 but can be enabled by using the parameter <a class="link" href="run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>. 76 </p> 77<h5> 78<a name="boost_test.utf_reference.rt_param_reference.list_content.h1"></a> 79 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.dot"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.dot">DOT</a> 80 </h5> 81<p> 82 DOT output generates a graph representing the module's <a class="link" href="../../section_glossary.html#ref_test_tree">test 83 tree</a> in a <a href="http://www.graphviz.org/doc/info/lang.html" target="_top">dot 84 format</a>. This output includes much more information about the test 85 tree including labels, timeouts, expected failures, and dependencies. 86 </p> 87<p> 88 The legend is as follow: 89 </p> 90<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 91<li class="listitem"> 92 the master test suite is represented as an ellipse 93 </li> 94<li class="listitem"> 95 a test unit (suite, case) is in a rounded rectangle 96 </li> 97<li class="listitem"> 98 test unit declaration location, <a class="link" href="../../tests_organization/tests_grouping.html" title="Grouping tests into logical units by labels">labels</a>, 99 <a class="link" href="../../testing_tools/expected_failures.html" title="Expected failures specification">expected 100 failures</a>, <a class="link" href="../../testing_tools/timeout.html" title="Time-out for test cases">timeouts</a> 101 are appended, 102 </li> 103<li class="listitem"> 104 a green box indicates that the test unit that is enabled, otherwise 105 its color is yellow, 106 </li> 107<li class="listitem"> 108 a plain black arrow goes from a test unit to each of its children, 109 following the test tree (the arrow pointing to the child), 110 </li> 111<li class="listitem"> 112 a dashed red arrow indicates a runtime dependence on test units, the 113 arrow pointing to the parent in the dependency graph. 114 </li> 115</ul></div> 116<h5> 117<a name="boost_test.utf_reference.rt_param_reference.list_content.h2"></a> 118 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.acceptable_values"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.acceptable_values">Acceptable 119 values</a> 120 </h5> 121<p> 122 <a class="link" href="../rt_param_reference.html#enum_param_value">Enumeration</a> names: 123 </p> 124<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 125<li class="listitem"> 126 <span class="bold"><strong>HRF</strong></span> (default) 127 </li> 128<li class="listitem"> 129 DOT 130 </li> 131</ul></div> 132<h5> 133<a name="boost_test.utf_reference.rt_param_reference.list_content.h3"></a> 134 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.command_line_syntax"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.command_line_syntax">Command 135 line syntax</a> 136 </h5> 137<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 138 <code class="computeroutput"><span class="special">--</span><span class="identifier">list_content</span><span class="special">[=<</span><span class="identifier">format</span><span class="special">>]</span></code> 139 </li></ul></div> 140<h5> 141<a name="boost_test.utf_reference.rt_param_reference.list_content.h4"></a> 142 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.environment_variable"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.environment_variable">Environment 143 variable</a> 144 </h5> 145<pre class="programlisting"><span class="identifier">BOOST_TEST_LIST_CONTENT</span> 146</pre> 147<h5> 148<a name="boost_test.utf_reference.rt_param_reference.list_content.h5"></a> 149 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.example"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.example">Example</a> 150 </h5> 151<p> 152 The following <span class="emphasis"><em>deliberately</em></span> complicated example illustrates 153 the purpose of the <code class="computeroutput"><span class="special">--</span><span class="identifier">list_content</span></code> 154 directive. The SVG generated from the produced Graphviz/dot file can be 155 downloaded <a href="../../../images/boost_runtime_list_content.svg" target="_top">here</a>. 156 </p> 157<h6> 158<a name="boost_test.utf_reference.rt_param_reference.list_content.h6"></a> 159 <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.list_content.example_descr"></a></span><a class="link" href="list_content.html#boost_test.utf_reference.rt_param_reference.list_content.example_descr">Example: 160 <code class="computeroutput"><span class="special">--</span><span class="identifier">list_content</span></code> 161 illustration</a> 162 </h6> 163<div class="informaltable"><table class="table"> 164<colgroup><col></colgroup> 165<thead><tr><th> 166 <p> 167 Code 168 </p> 169 </th></tr></thead> 170<tbody><tr><td> 171<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">list_content</span> 172<span class="preprocessor">#include</span> <span class="special"><</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">></span> 173<span class="keyword">namespace</span> <span class="identifier">utf</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span> 174 175<span class="comment">//// --------------------------------------------------------------------------</span> 176<span class="comment">// Test suite 1, disabled by default, s1/test2 is explicitely enabled.</span> 177<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">s1</span><span class="special">,</span> 178<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">disabled</span><span class="special">()</span> <span class="comment">// suite is not disabled because of the</span> 179<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span> <span class="string">"disabled suite 1"</span><span class="special">)</span> <span class="comment">// extra declaration at the end of the file</span> 180<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span> <span class="string">"label1"</span> <span class="special">)</span> 181<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span> <span class="string">"label2"</span> <span class="special">))</span> 182 183<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test1</span><span class="special">,</span> <span class="comment">// s1/test1</span> 184<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">enabled</span><span class="special">()</span> <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"enabled"</span><span class="special">))</span> 185<span class="special">{</span> 186 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span> 187<span class="special">}</span> 188 189<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test2</span><span class="special">,</span> <span class="comment">// s1/test2</span> 190<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span> <span class="string">"defaulted"</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">expected_failures</span><span class="special">(</span> <span class="number">1</span> <span class="special">))</span> 191<span class="special">{</span> 192 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 193<span class="special">}</span> 194 195<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test3</span><span class="special">,</span> <span class="comment">// s1/test3</span> 196<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span> <span class="string">"defaulted"</span><span class="special">))</span> 197<span class="special">{</span> 198 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 199<span class="special">}</span> 200<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span> 201 202 203<span class="comment">//// --------------------------------------------------------------------------</span> 204<span class="comment">// Test suite 2, disabled by default, s2/test2 is explicitely enabled.</span> 205<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">s2</span><span class="special">,</span> 206<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">disabled</span><span class="special">()</span> 207<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span> <span class="string">"label1"</span> <span class="special">)</span> 208<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">expected_failures</span><span class="special">(</span> <span class="number">3</span> <span class="special">))</span> 209 210<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test1</span><span class="special">,</span> <span class="comment">// s2/test1</span> 211<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span> <span class="string">"defaulted"</span><span class="special">))</span> 212<span class="special">{</span> 213 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 214<span class="special">}</span> 215 216<span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">assertion_result</span> <span class="identifier">do_it</span><span class="special">(</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">test_unit_id</span> <span class="special">)</span> 217<span class="special">{</span> 218 <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span> 219<span class="special">}</span> 220 221<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test2</span><span class="special">,</span> <span class="comment">// s2/test2</span> 222<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">enabled</span><span class="special">()</span> 223<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span> <span class="string">"enabled w. precondition"</span><span class="special">)</span> 224<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">precondition</span><span class="special">(</span><span class="identifier">do_it</span><span class="special">))</span> 225<span class="special">{</span> 226 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 227<span class="special">}</span> 228 229<span class="comment">//// --------------------------------------------------------------------------</span> 230<span class="comment">// Test suite s2/s23, disabled</span> 231<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">s23</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">disabled</span><span class="special">())</span> 232 233<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test1</span> <span class="special">)</span> <span class="comment">// s2/s23/test1</span> 234<span class="special">{</span> 235 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> 236<span class="special">}</span> 237 238<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test2</span><span class="special">,</span> <span class="comment">// s2/s23/test2</span> 239<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">(</span> <span class="number">10</span> <span class="special">))</span> 240<span class="special">{</span> 241 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span> 242<span class="special">}</span> 243 244<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test3</span><span class="special">,</span> <span class="comment">// s2/s23/test3</span> 245<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">enabled</span><span class="special">()</span> 246<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">depends_on</span><span class="special">(</span> <span class="string">"s2/test2"</span> <span class="special">))</span> 247<span class="special">{</span> 248 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span> 249<span class="special">}</span> 250<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span> <span class="comment">// s2/s23</span> 251<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span> <span class="comment">// s2</span> 252 253 254 255<span class="comment">//// --------------------------------------------------------------------------</span> 256<span class="comment">// Test suite s1 continued</span> 257<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">s1</span> <span class="special">)</span> 258<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">s14</span><span class="special">,</span> 259<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">depends_on</span><span class="special">(</span> <span class="string">"s2/s23/test3"</span> <span class="special">)</span> 260<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span> <span class="string">"test suite which depends on another test suite"</span><span class="special">))</span> 261 262<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test1</span><span class="special">,</span> <span class="comment">// s1/s14/test1</span> 263<span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">depends_on</span><span class="special">(</span> <span class="string">"s2"</span> <span class="special">))</span> 264<span class="special">{</span> 265 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="string">"s14"</span> <span class="special">==</span> <span class="string">"test"</span> <span class="special">);</span> 266<span class="special">}</span> 267 268<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span> <span class="comment">// s1/s14</span> 269<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span> <span class="comment">// s1</span> 270</pre> 271 </td></tr></tbody> 272</table></div> 273<div class="informaltable"><table class="table"> 274<colgroup><col></colgroup> 275<thead><tr><th> 276 <p> 277 Output 278 </p> 279 </th></tr></thead> 280<tbody><tr><td> 281<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="special">./</span><span class="identifier">boost_runtime_list_content</span> <span class="special">--</span><span class="identifier">list_content</span> 282<span class="identifier">s1</span><span class="special">*:</span> <span class="identifier">disabled</span> <span class="identifier">suite</span> <span class="number">1</span> 283 <span class="identifier">test1</span><span class="special">*:</span> <span class="identifier">enabled</span> 284 <span class="identifier">test2</span> <span class="special">:</span> <span class="identifier">defaulted</span> 285 <span class="identifier">test3</span> <span class="special">:</span> <span class="identifier">defaulted</span> 286 <span class="identifier">s14</span> <span class="special">:</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="identifier">which</span> <span class="identifier">depends</span> <span class="identifier">on</span> <span class="identifier">another</span> <span class="identifier">test</span> <span class="identifier">suite</span> 287 <span class="identifier">test1</span> 288<span class="identifier">s2</span><span class="special">*</span> 289 <span class="identifier">test1</span> <span class="special">:</span> <span class="identifier">defaulted</span> 290 <span class="identifier">test2</span><span class="special">*:</span> <span class="identifier">enabled</span> <span class="identifier">w</span><span class="special">.</span> <span class="identifier">precondition</span> 291 <span class="identifier">s23</span><span class="special">*</span> 292 <span class="identifier">test1</span> 293 <span class="identifier">test2</span> 294 <span class="identifier">test3</span><span class="special">*</span> 295</pre> 296 </td></tr></tbody> 297</table></div> 298<p> 299 <span class="inlinemediaobject"><img src="../../../images/boost_runtime_list_content.png" width="70%"></span> 300 </p> 301</div> 302<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 303<td align="left"></td> 304<td align="right"><div class="copyright-footer">Copyright © 2001-2020 Boost.Test contributors<p> 305 Distributed under the Boost Software License, Version 1.0. (See accompanying 306 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>) 307 </p> 308</div></td> 309</tr></table> 310<hr> 311<div class="spirit-nav"> 312<a accesskey="p" href="help.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rt_param_reference.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="list_labels.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 313</div> 314</body> 315</html> 316
