3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
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">
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>
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>
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>
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
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
39 <div class="orderedlist"><ol class="orderedlist" type="1">
41 HRF (default), standing for <span class="emphasis"><em>Human Readable Format</em></span>,
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.
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>
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:
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>
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>.
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>
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.
88 The legend is as follow:
90 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
92 the master test suite is represented as an ellipse
95 a test unit (suite, case) is in a rounded rectangle
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>
103 <li class="listitem">
104 a green box indicates that the test unit that is enabled, otherwise
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),
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.
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
122 <a class="link" href="../rt_param_reference.html#enum_param_value">Enumeration</a> names:
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)
128 <li class="listitem">
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
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>
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
145 <pre class="programlisting"><span class="identifier">BOOST_TEST_LIST_CONTENT</span>
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>
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>.
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>
163 <div class="informaltable"><table class="table">
164 <colgroup><col></colgroup>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
273 <div class="informaltable"><table class="table">
274 <colgroup><col></colgroup>
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>
299 <span class="inlinemediaobject"><img src="../../../images/boost_runtime_list_content.png" width="70%"></span>
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-2019 Boost.Test
306 Distributed under the Boost Software License, Version 1.0. (See accompanying
307 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>)
312 <div class="spirit-nav">
313 <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>