1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
2 xml:id="manual.intro.setup.test" xreflabel="Testing">
3 <?dbhtml filename="test.html"?>
5 <info><title>Test</title>
7 <keyword>ISO C++</keyword>
8 <keyword>test</keyword>
9 <keyword>testsuite</keyword>
10 <keyword>performance</keyword>
11 <keyword>conformance</keyword>
12 <keyword>ABI</keyword>
13 <keyword>exception safety</keyword>
18 The libstdc++ testsuite includes testing for standard conformance,
19 regressions, ABI, and performance.
22 <section xml:id="test.organization" xreflabel="Test Organization"><info><title>Organization</title></info>
25 <section xml:id="test.organization.layout" xreflabel="Directory Layout"><info><title>Directory Layout</title></info>
29 The directory <emphasis>libsrcdir/testsuite</emphasis> contains the
30 individual test cases organized in sub-directories corresponding to
31 clauses of the C++ standard (detailed below), the dejagnu test
32 harness support files, and sources to various testsuite utilities
33 that are packaged in a separate testing library.
37 All test cases for functionality required by the runtime components
38 of the C++ standard (ISO 14882) are files within the following
59 In addition, the following directories include test files:
63 tr1 Tests for components as described by the Technical Report on Standard Library Extensions (TR1).
64 backward Tests for backwards compatibility and deprecated features.
65 demangle Tests for __cxa_demangle, the IA 64 C++ ABI demangler
66 ext Tests for extensions.
67 performance Tests for performance analysis, and performance regressions.
71 Some directories don't have test files, but instead contain
72 auxiliary information:
76 config Files for the dejagnu test harness.
77 lib Files for the dejagnu test harness.
78 libstdc++* Files for the dejagnu test harness.
79 data Sample text files for testing input and output.
80 util Files for libtestc++, utilities and testing routines.
84 Within a directory that includes test files, there may be
85 additional subdirectories, or files. Originally, test cases
86 were appended to one file that represented a particular section
87 of the chapter under test, and was named accordingly. For
88 instance, to test items related to <code> 21.3.6.1 -
89 basic_string::find [lib.string::find]</code> in the standard,
90 the following was used:
96 However, that practice soon became a liability as the test cases
97 became huge and unwieldy, and testing new or extended
98 functionality (like wide characters or named locales) became
99 frustrating, leading to aggressive pruning of test cases on some
100 platforms that covered up implementation errors. Now, the test
101 suite has a policy of one file, one test case, which solves the
102 above issues and gives finer grained results and more manageable
103 error debugging. As an example, the test case quoted above
107 21_strings/basic_string/find/char/1.cc
108 21_strings/basic_string/find/char/2.cc
109 21_strings/basic_string/find/char/3.cc
110 21_strings/basic_string/find/wchar_t/1.cc
111 21_strings/basic_string/find/wchar_t/2.cc
112 21_strings/basic_string/find/wchar_t/3.cc
116 All new tests should be written with the policy of one test
117 case, one file in mind.
122 <section xml:id="test.organization.naming" xreflabel="Naming Conventions"><info><title>Naming Conventions</title></info>
126 In addition, there are some special names and suffixes that are
127 used within the testsuite to designate particular kinds of
134 <emphasis>_xin.cc</emphasis>
137 This test case expects some kind of interactive input in order
138 to finish or pass. At the moment, the interactive tests are not
139 run by default. Instead, they are run by hand, like:
142 g++ 27_io/objects/char/3_xin.cc
143 cat 27_io/objects/char/3_xin.in | a.out
148 <emphasis>.in</emphasis>
151 This file contains the expected input for the corresponding <emphasis>
152 _xin.cc</emphasis> test case.
157 <emphasis>_neg.cc</emphasis>
160 This test case is expected to fail: it's a negative test. At the
161 moment, these are almost always compile time errors.
166 <emphasis>char</emphasis>
169 This can either be a directory name or part of a longer file
170 name, and indicates that this file, or the files within this
171 directory are testing the <code>char</code> instantiation of a
177 <emphasis>wchar_t</emphasis>
180 This can either be a directory name or part of a longer file
181 name, and indicates that this file, or the files within this
182 directory are testing the <code>wchar_t</code> instantiation of
183 a template. Some hosts do not support <code>wchar_t</code>
184 functionality, so for these targets, all of these tests will not
190 <emphasis>thread</emphasis>
193 This can either be a directory name or part of a longer file
194 name, and indicates that this file, or the files within this
195 directory are testing situations where multiple threads are
201 <emphasis>performance</emphasis>
204 This can either be an enclosing directory name or part of a
205 specific file name. This indicates a test that is used to
206 analyze runtime performance, for performance regression testing,
207 or for other optimization related analysis. At the moment, these
208 test cases are not run by default.
217 <section xml:id="test.run" xreflabel="Running the Testsuite"><info><title>Running the Testsuite</title></info>
220 <section xml:id="test.run.basic"><info><title>Basic</title></info>
224 You can check the status of the build without installing it
225 using the dejagnu harness, much like the rest of the gcc
227 <programlisting> make check</programlisting>
228 <para>in the <emphasis>libbuilddir</emphasis> directory.</para>
230 <programlisting> make check-target-libstdc++-v3</programlisting>
231 <para>in the <emphasis>gccbuilddir</emphasis> directory.
235 These commands are functionally equivalent and will create a
236 'testsuite' directory underneath
237 <emphasis>libbuilddir</emphasis> containing the results of the
238 tests. Two results files will be generated: <emphasis>
239 libstdc++.sum</emphasis>, which is a PASS/FAIL summary for each
240 test, and <emphasis>libstdc++.log</emphasis> which is a log of
241 the exact command line passed to the compiler, the compiler
242 output, and the executable output (if any).
246 Archives of test results for various versions and platforms are
247 available on the GCC website in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/gcc-4.3/buildstat.html">build
248 status</link> section of each individual release, and are also
249 archived on a daily basis on the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</link>
250 mailing list. Please check either of these places for a similar
251 combination of source version, operating system, and host CPU.
255 <section xml:id="test.run.variations"><info><title>Variations</title></info>
258 There are several options for running tests, including testing
259 the regression tests, testing a subset of the regression tests,
260 testing the performance tests, testing just compilation, testing
261 installed tools, etc. In addition, there is a special rule for
262 checking the exported symbols of the shared library.
265 To debug the dejagnu test harness during runs, try invoking with a
266 specific argument to the variable RUNTESTFLAGS, as below.
270 make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
278 make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
282 To run a subset of the library tests, you will need to generate
283 the <emphasis>testsuite_files</emphasis> file by running
284 <command>make testsuite_files</command> in the
285 <emphasis>libbuilddir/testsuite</emphasis> directory, described
286 below. Edit the file to remove the tests you don't want and
287 then run the testsuite as normal.
291 There are two ways to run on a simulator: set up DEJAGNU to point to a
292 specially crafted site.exp, or pass down --target_board flags.
296 Example flags to pass down for various embedded builds are as follows:
300 --target=powerpc-eabism (libgloss/sim)
301 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
303 --target=calmrisc32 (libgloss/sid)
304 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
306 --target=xscale-elf (newlib/sim)
307 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
311 Also, here is an example of how to run the libstdc++ testsuite
312 for a multilibed build directory with different ABI settings:
316 make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
320 You can run the tests with a compiler and library that have
321 already been installed. Make sure that the compiler (e.g.,
322 <code>g++</code>) is in your <code>PATH</code>. If you are
323 using shared libraries, then you must also ensure that the
324 directory containing the shared version of libstdc++ is in your
325 <code>LD_LIBRARY_PATH</code>, or equivalent. If your GCC source
326 tree is at <code>/path/to/gcc</code>, then you can run the tests
331 runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
335 The testsuite will create a number of files in the directory in
336 which you run this command,. Some of those files might use the
337 same name as files created by other testsuites (like the ones
338 for GCC and G++), so you should not try to run all the
339 testsuites in parallel from the same directory.
343 In addition, there are some testing options that are mostly of
344 interest to library maintainers and system integrators. As such,
345 these tests may not work on all cpu and host combinations, and
346 may need to be executed in the
347 <emphasis>libbuilddir/testsuite</emphasis> directory. These
348 options include, but are not necessarily limited to, the
357 Five files are generated that determine what test files
358 are run. These files are:
364 <emphasis>testsuite_files</emphasis>
367 This is a list of all the test cases that will be run. Each
368 test case is on a separate line, given with an absolute path
369 from the <emphasis>libsrcdir/testsuite</emphasis> directory.
375 <emphasis>testsuite_files_interactive</emphasis>
378 This is a list of all the interactive test cases, using the
379 same format as the file list above. These tests are not run
386 <emphasis>testsuite_files_performance</emphasis>
389 This is a list of all the performance test cases, using the
390 same format as the file list above. These tests are not run
397 <emphasis>testsuite_thread</emphasis>
400 This file indicates that the host system can run tests which
401 involved multiple threads.
407 <emphasis>testsuite_wchar_t</emphasis>
410 This file indicates that the host system can run the wchar_t
411 tests, and corresponds to the macro definition <code>
412 _GLIBCXX_USE_WCHAR_T</code> in the file c++config.h.
422 The library ABI can be tested. This involves testing the shared
423 library against an ABI-defining previous version of symbol
432 This rule compiles, but does not link or execute, the
433 <emphasis>testsuite_files</emphasis> test cases and displays the
438 make check-performance
442 This rule runs through the
443 <emphasis>testsuite_files_performance</emphasis> test cases and
444 collects information for performance analysis and can be used to
445 spot performance regressions. Various timing information is
446 collected, as well as number of hard page faults, and memory
447 used. This is not run by default, and the implementation is in
452 We are interested in any strange failures of the testsuite;
453 please email the main libstdc++ mailing list if you see
454 something odd or have questions.
458 <section xml:id="test.run.permutations"><info><title>Permutations</title></info>
461 To run the libstdc++ test suite under the <link linkend="manual.ext.debug_mode">debug mode</link>, edit
462 <filename>libstdc++-v3/scripts/testsuite_flags</filename> to add the
463 compile-time flag <constant>-D_GLIBCXX_DEBUG</constant> to the
464 result printed by the <literal>--build-cxx</literal>
465 option. Additionally, add the
466 <constant>-D_GLIBCXX_DEBUG_PEDANTIC</constant> flag to turn on
467 pedantic checking. The libstdc++ test suite should produce
468 precisely the same results under debug mode that it does under
469 release mode: any deviation indicates an error in either the
470 library or the test suite.
474 The <link linkend="manual.ext.parallel_mode">parallel
475 mode</link> can be tested in much the same manner, substituting
476 <constant>-D_GLIBCXX_PARALLEL</constant> for
477 <constant>-D_GLIBCXX_DEBUG</constant> in the previous paragraph.
481 Or, just run the testsuites with <constant>CXXFLAGS</constant>
482 set to <constant>-D_GLIBCXX_DEBUG</constant> or
483 <constant>-D_GLIBCXX_PARALLEL</constant>.
488 <section xml:id="test.new_tests"><info><title>Writing a new test case</title></info>
492 The first step in making a new test case is to choose the correct
493 directory and file name, given the organization as previously
498 All files are copyright the FSF, and GPL'd: this is very
499 important. The first copyright year should correspond to the date
500 the file was checked in to SVN.
504 As per the dejagnu instructions, always return 0 from main to
509 A bunch of utility functions and classes have already been
510 abstracted out into the testsuite utility library, <code>
511 libtestc++</code>. To use this functionality, just include the
512 appropriate header file: the library or specific object files will
513 automatically be linked in as part of the testsuite run.
517 For a test that needs to take advantage of the dejagnu test
518 harness, what follows below is a list of special keyword that
519 harness uses. Basically, a test case contains dg-keywords (see
520 dg.exp) indicating what to do and what kinds of behavior are to be
521 expected. New test cases should be written with the new style
522 DejaGnu framework in mind.
526 To ease transition, here is the list of dg-keyword documentation
531 # The currently supported options are:
536 # dg-options "options ..." [{ target selector }]
537 # specify special options to pass to the tool (eg: compiler)
539 # dg-do do-what-keyword [{ target/xfail selector }]
540 # `do-what-keyword' is tool specific and is passed unchanged to
541 # ${tool}-dg-test. An example is gcc where `keyword' can be any of:
542 # preprocess|compile|assemble|link|run
543 # and will do one of: produce a .i, produce a .s, produce a .o,
544 # produce an a.out, or produce an a.out and run it (the default is
547 # dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
548 # indicate an error message <regexp> is expected on this line
549 # (the test fails if it doesn't occur)
550 # Linenum=0 for general tool messages (eg: -V arg missing).
551 # "." means the current line.
553 # dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
554 # indicate a warning message <regexp> is expected on this line
555 # (the test fails if it doesn't occur)
557 # dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
558 # indicate a bogus error message <regexp> use to occur here
559 # (the test fails if it does occur)
561 # dg-build regexp comment [{ target/xfail selector }]
562 # indicate the build use to fail for some reason
563 # (errors covered here include bad assembler generated, tool crashes,
565 # (the test fails if it does occur)
567 # dg-excess-errors comment [{ target/xfail selector }]
568 # indicate excess errors are expected (any line)
569 # (this should only be used sparingly and temporarily)
571 # dg-output regexp [{ target selector }]
572 # indicate the expected output of the program is <regexp>
573 # (there may be multiple occurrences of this, they are concatenated)
575 # dg-final { tcl code }
576 # add some tcl code to be run at the end
577 # (there may be multiple occurrences of this, they are concatenated)
578 # (unbalanced braces must be \-escaped)
580 # "{ target selector }" is a list of expressions that determine whether the
581 # test succeeds or fails for a particular target, or in some cases whether the
582 # option applies for a particular target. If the case of `dg-do' it specifies
583 # whether the test case is even attempted on the specified target.
585 # The target selector is always optional. The format is one of:
587 # { xfail *-*-* ... } - the test is expected to fail for the given targets
588 # { target *-*-* ... } - the option only applies to the given targets
590 # At least one target must be specified, use *-*-* for "all targets".
591 # At present it is not possible to specify both `xfail' and `target'.
592 # "native" may be used in place of "*-*-*".
594 Example 1: Testing compilation only
597 Example 2: Testing for expected warnings on line 36, which all targets fail
598 // { dg-warning "string literals" "" { xfail *-*-* } 36 }
600 Example 3: Testing for expected warnings on line 36
601 // { dg-warning "string literals" "" { target *-*-* } 36 }
603 Example 4: Testing for compilation errors on line 41
605 // { dg-error "no match for" "" { target *-*-* } 41 }
607 Example 5: Testing with special command line settings, or without the
608 use of pre-compiled headers, in particular the stdc++.h.gch file. Any
609 options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set
610 up in the normal.exp file.
611 // { dg-options "-O0" { target *-*-* } }
615 More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
620 <section xml:id="test.harness" xreflabel="Test Harness and Utilities"><info><title>Test Harness and Utilities</title></info>
623 <section xml:id="test.harness.dejagnu"><info><title>Dejagnu Harness Details</title></info>
626 Underlying details of testing for conformance and regressions are
627 abstracted via the GNU Dejagnu package. This is similar to the
632 <para>This is information for those looking at making changes to the testsuite
633 structure, and/or needing to trace dejagnu's actions with --verbose. This
634 will not be useful to people who are "merely" adding new tests to the existing
638 <para>The first key point when working with dejagnu is the idea of a "tool".
639 Files, directories, and functions are all implicitly used when they are
640 named after the tool in use. Here, the tool will always be "libstdc++".
643 <para>The <code>lib</code> subdir contains support routines. The
644 <code>lib/libstdc++.exp</code> file ("support library") is loaded
645 automagically, and must explicitly load the others. For example, files can
646 be copied from the core compiler's support directory into <code>lib</code>.
649 <para>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are
650 our own. Callbacks must be prefixed with the name of the tool. To easily
651 distinguish the others, by convention our own routines are named "v3-*".
654 <para>The next key point when working with dejagnu is "test files". Any
655 directory whose name starts with the tool name will be searched for test files.
656 (We have only one.) In those directories, any <code>.exp</code> file is
657 considered a test file, and will be run in turn. Our main test file is called
658 <code>normal.exp</code>; it runs all the tests in testsuite_files using the
659 callbacks loaded from the support library.
662 <para>The <code>config</code> directory is searched for any particular "target
663 board" information unique to this library. This is currently unused and sets
664 only default variables.
669 <section xml:id="test.harness.utils"><info><title>Utilities</title></info>
674 The testsuite directory also contains some files that implement
675 functionality that is intended to make writing test cases easier,
676 or to avoid duplication, or to provide error checking in a way that
677 is consistent across platforms and test harnesses. A stand-alone
678 executable, called <emphasis>abi_check</emphasis>, and a static
679 library called <emphasis>libtestc++</emphasis> are
680 constructed. Both of these items are not installed, and only used
685 These files include the following functionality:
691 <emphasis>testsuite_abi.h</emphasis>,
692 <emphasis>testsuite_abi.cc</emphasis>,
693 <emphasis>testsuite_abi_check.cc</emphasis>
696 Creates the executable <emphasis>abi_check</emphasis>.
697 Used to check correctness of symbol versioning, visibility of
698 exported symbols, and compatibility on symbols in the shared
699 library, for hosts that support this feature. More information
700 can be found in the ABI documentation <link linkend="appendix.porting.abi">here</link>
705 <emphasis>testsuite_allocator.h</emphasis>,
706 <emphasis>testsuite_allocator.cc</emphasis>
709 Contains specialized allocators that keep track of construction
710 and destruction. Also, support for overriding global new and
711 delete operators, including verification that new and delete
712 are called during execution, and that allocation over max_size
718 <emphasis>testsuite_character.h</emphasis>
721 Contains <code>std::char_traits</code> and
722 <code>std::codecvt</code> specializations for a user-defined
728 <emphasis>testsuite_hooks.h</emphasis>,
729 <emphasis>testsuite_hooks.cc</emphasis>
732 A large number of utilities, including:
735 <listitem><para>VERIFY</para></listitem>
736 <listitem><para>set_memory_limits</para></listitem>
737 <listitem><para>verify_demangle</para></listitem>
738 <listitem><para>run_tests_wrapped_locale</para></listitem>
739 <listitem><para>run_tests_wrapped_env</para></listitem>
740 <listitem><para>try_named_locale</para></listitem>
741 <listitem><para>try_mkfifo</para></listitem>
742 <listitem><para>func_callback</para></listitem>
743 <listitem><para>counter</para></listitem>
744 <listitem><para>copy_tracker</para></listitem>
745 <listitem><para>copy_constructor</para></listitem>
746 <listitem><para>assignment_operator</para></listitem>
747 <listitem><para>destructor</para></listitem>
749 <para>pod_char, pod_int and associated char_traits specializations</para>
755 <emphasis>testsuite_io.h</emphasis>
758 Error, exception, and constraint checking for
759 <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>.
764 <emphasis>testsuite_iterators.h</emphasis>
767 Wrappers for various iterators.
772 <emphasis>testsuite_performance.h</emphasis>
775 A number of class abstractions for performance counters, and
776 reporting functions including:
779 <listitem><para>time_counter</para></listitem>
780 <listitem><para>resource_counter</para></listitem>
781 <listitem><para>report_performance</para></listitem>
789 <section xml:id="test.special"><info><title>Special Topics</title></info>
792 <section xml:id="test.exception.safety"><info><title>
793 Qualifying Exception Safety Guarantees
795 <primary>Test</primary>
796 <secondary>Exception Safety</secondary>
801 <section xml:id="test.exception.safety.overview"><info><title>Overview</title></info>
805 Testing is composed of running a particular test sequence,
806 and looking at what happens to the surrounding code when
807 exceptions are thrown. Each test is composed of measuring
808 initial state, executing a particular sequence of code under
809 some instrumented conditions, measuring a final state, and
810 then examining the differences between the two states.
814 Test sequences are composed of constructed code sequences
815 that exercise a particular function or member function, and
816 either confirm no exceptions were generated, or confirm the
817 consistency/coherency of the test subject in the event of a
822 Random code paths can be constructed using the basic test
823 sequences and instrumentation as above, only combined in a
824 random or pseudo-random way.
827 <para> To compute the code paths that throw, test instruments
828 are used that throw on allocation events
829 (<classname>__gnu_cxx::throw_allocator_random</classname>
830 and <classname>__gnu_cxx::throw_allocator_limit</classname>)
831 and copy, assignment, comparison, increment, swap, and
833 (<classname>__gnu_cxx::throw_type_random</classname>
834 and <classname>__gnu_cxx::throw_type_limit</classname>). Looping
835 through a given test sequence and conditionally throwing in
836 all instrumented places. Then, when the test sequence
837 completes without an exception being thrown, assume all
838 potential error paths have been exercised in a sequential
844 <section xml:id="test.exception.safety.status"><info><title>
856 <filename>testsuite/23_containers/list/modifiers/3.cc</filename>.
862 Policy Based Data Structures
865 For example, take the test
866 functor <classname>rand_reg_test</classname> in
867 in <filename>testsuite/ext/pb_ds/regression/tree_no_data_map_rand.cc</filename>. This uses <classname>container_rand_regression_test</classname> in
868 <filename>testsuite/util/regression/rand/assoc/container_rand_regression_test.h</filename>.
873 Which has several tests for container member functions,
874 Includes control and test container objects. Configuration includes
875 random seed, iterations, number of distinct values, and the
876 probability that an exception will be thrown. Assumes instantiating
877 container uses an extension
878 allocator, <classname>__gnu_cxx::throw_allocator_random</classname>,
879 as the allocator type.
885 C++11 Container Requirements.
889 Coverage is currently limited to testing container
890 requirements for exception safety,
891 although <classname>__gnu_cxx::throw_type</classname> meets
892 the additional type requirements for testing numeric data
893 structures and instantiating algorithms.
897 Of particular interest is extending testing to algorithms and
898 then to parallel algorithms. Also io and locales.
902 The test instrumentation should also be extended to add
903 instrumentation to <classname>iterator</classname>
904 and <classname>const_iterator</classname> types that throw
905 conditionally on iterator operations.
912 <section xml:id="test.exception.safety.containers"><info><title>
913 C++11 Requirements Test Sequence Descriptions
924 Basic consistency on exception propagation tests. For
925 each container, an object of that container is constructed,
926 a specific member function is exercised in
927 a <literal>try</literal> block, and then any thrown
928 exceptions lead to error checking in the appropriate
929 <literal>catch</literal> block. The container's use of
930 resources is compared to the container's use prior to the
931 test block. Resource monitoring is limited to allocations
932 made through the container's <type>allocator_type</type>,
933 which should be sufficient for container data
934 structures. Included in these tests are member functions
935 are <type>iterator</type> and <type>const_iterator</type>
936 operations, <function>pop_front</function>, <function>pop_back</function>, <function>push_front</function>, <function>push_back</function>, <function>insert</function>, <function>erase</function>, <function>swap</function>, <function>clear</function>,
937 and <function>rehash</function>. The container in question is
938 instantiated with two instrumented template arguments,
939 with <classname>__gnu_cxx::throw_allocator_limit</classname>
940 as the allocator type, and
941 with <classname>__gnu_cxx::throw_type_limit</classname> as
942 the value type. This allows the test to loop through
943 conditional throw points.
947 The general form is demonstrated in
948 <filename>testsuite/23_containers/list/requirements/exception/basic.cc
949 </filename>. The instantiating test object is <classname>__gnu_test::basic_safety</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
956 Generation Prohibited
960 Exception generation tests. For each container, an object of
961 that container is constructed and all member functions
962 required to not throw exceptions are exercised. Included in
963 these tests are member functions
964 are <type>iterator</type> and <type>const_iterator</type> operations, <function>erase</function>, <function>pop_front</function>, <function>pop_back</function>, <function>swap</function>,
965 and <function>clear</function>. The container in question is
966 instantiated with two instrumented template arguments,
967 with <classname>__gnu_cxx::throw_allocator_random</classname>
968 as the allocator type, and
969 with <classname>__gnu_cxx::throw_type_random</classname> as
970 the value type. This test does not loop, an instead is sudden
971 death: first error fails.
974 The general form is demonstrated in
975 <filename>testsuite/23_containers/list/requirements/exception/generation_prohibited.cc
976 </filename>. The instantiating test object is <classname>__gnu_test::generation_prohibited</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
983 Propagation Consistent
987 Container rollback on exception propagation tests. For
988 each container, an object of that container is constructed,
989 a specific member function that requires rollback to a previous
990 known good state is exercised in
991 a <literal>try</literal> block, and then any thrown
992 exceptions lead to error checking in the appropriate
993 <literal>catch</literal> block. The container is compared to
994 the container's last known good state using such parameters
995 as size, contents, and iterator references. Included in these
996 tests are member functions
997 are <function>push_front</function>, <function>push_back</function>, <function>insert</function>,
998 and <function>rehash</function>. The container in question is
999 instantiated with two instrumented template arguments,
1000 with <classname>__gnu_cxx::throw_allocator_limit</classname>
1001 as the allocator type, and
1002 with <classname>__gnu_cxx::throw_type_limit</classname> as
1003 the value type. This allows the test to loop through
1004 conditional throw points.
1008 The general form demonstrated in
1009 <filename>testsuite/23_containers/list/requirements/exception/propagation_coherent.cc
1010 </filename>. The instantiating test object is <classname>__gnu_test::propagation_coherent</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.