[DFAJumpThreading] Remove incoming StartBlock from all phis when unfolding select...
[llvm-project.git] / libcxx / docs / TestingLibcxx.rst
blob44f3904f4e426a0f5853c3611ee8445f811382a6
1 ==============
2 Testing libc++
3 ==============
5 .. contents::
6   :local:
8 .. _testing:
10 Getting Started
11 ===============
13 libc++ uses LIT to configure and run its tests.
15 The primary way to run the libc++ tests is by using ``make check-cxx``.
17 However since libc++ can be used in any number of possible
18 configurations it is important to customize the way LIT builds and runs
19 the tests. This guide provides information on how to use LIT directly to
20 test libc++.
22 Please see the `Lit Command Guide`_ for more information about LIT.
24 .. _LIT Command Guide: https://llvm.org/docs/CommandGuide/lit.html
26 Usage
27 -----
29 After building libc++, you can run parts of the libc++ test suite by simply
30 running ``llvm-lit`` on a specified test or directory. If you're unsure
31 whether the required libraries have been built, you can use the
32 ``cxx-test-depends`` target. For example:
34 .. code-block:: bash
36   $ cd <monorepo-root>
37   $ make -C <build> cxx-test-depends # If you want to make sure the targets get rebuilt
38   $ <build>/bin/llvm-lit -sv libcxx/test/std/re # Run all of the std::regex tests
39   $ <build>/bin/llvm-lit -sv libcxx/test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test
40   $ <build>/bin/llvm-lit -sv libcxx/test/std/atomics libcxx/test/std/threads # Test std::thread and std::atomic
42 If you used **ninja** as your build system, running ``ninja -C <build> check-cxx`` will run
43 all the tests in the libc++ testsuite.
45 .. note::
46   If you used the Bootstrapping build instead of the default runtimes build, the
47   ``cxx-test-depends`` target is instead named ``runtimes-test-depends``, and
48   you will need to prefix ``<build>/runtimes/runtimes-<target>-bins/`` to the
49   paths of all tests. For example, to run all the libcxx tests you can do
50   ``<build>/bin/llvm-lit -sv <build>/runtimes/runtimes-bins/libcxx/test``.
52 In the default configuration, the tests are built against headers that form a
53 fake installation root of libc++. This installation root has to be updated when
54 changes are made to the headers, so you should re-run the ``cxx-test-depends``
55 target before running the tests manually with ``lit`` when you make any sort of
56 change, including to the headers. We recommend using the provided ``libcxx/utils/libcxx-lit``
57 script to automate this so you don't have to think about building test dependencies
58 every time:
60 .. code-block:: bash
62   $ cd <monorepo-root>
63   $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/re # Build testing dependencies and run all of the std::regex tests
65 Sometimes you'll want to change the way LIT is running the tests. Custom options
66 can be specified using the ``--param <name>=<val>`` flag. The most common option
67 you'll want to change is the standard dialect (ie ``-std=c++XX``). By default the
68 test suite will select the newest C++ dialect supported by the compiler and use
69 that. However, you can manually specify the option like so if you want:
71 .. code-block:: bash
73   $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers # Run the tests with the newest -std
74   $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers --param std=c++03 # Run the tests in C++03
76 Other parameters are supported by the test suite. Those are defined in ``libcxx/utils/libcxx/test/params.py``.
77 If you want to customize how to run the libc++ test suite beyond what is available
78 in ``params.py``, you most likely want to use a custom site configuration instead.
80 The libc++ test suite works by loading a site configuration that defines various
81 "base" parameters (via Lit substitutions). These base parameters represent things
82 like the compiler to use for running the tests, which default compiler and linker
83 flags to use, and how to run an executable. This system is meant to be easily
84 extended for custom needs, in particular when porting the libc++ test suite to
85 new platforms.
87 Using a Custom Site Configuration
88 ---------------------------------
90 By default, the libc++ test suite will use a site configuration that matches
91 the current CMake configuration. It does so by generating a ``lit.site.cfg``
92 file in the build directory from one of the configuration file templates in
93 ``libcxx/test/configs/``, and pointing ``llvm-lit`` (which is a wrapper around
94 ``llvm/utils/lit/lit.py``) to that file. So when you're running
95 ``<build>/bin/llvm-lit`` either directly or indirectly, the generated ``lit.site.cfg``
96 file is always loaded instead of ``libcxx/test/lit.cfg.py``. If you want to use a
97 custom site configuration, simply point the CMake build to it using
98 ``-DLIBCXX_TEST_CONFIG=<path-to-site-config>``, and that site configuration
99 will be used instead. That file can use CMake variables inside it to make
100 configuration easier.
102    .. code-block:: bash
104      $ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
105      $ libcxx/utils/libcxx-lit <build> -sv libcxx/test # will use your custom config file
107 Additional tools
108 ----------------
110 The libc++ test suite uses a few optional tools to improve the code quality.
112 These tools are:
113 - clang-tidy (you might need additional dev packages to compile libc++-specific clang-tidy checks)
115 Reproducing CI issues locally
116 -----------------------------
118 Libc++ has extensive CI that tests various configurations of the library. The testing for
119 all these configurations is located in ``libcxx/utils/ci/run-buildbot``. Most of our
120 CI jobs are being run on a Docker image for reproducibility. The definition of this Docker
121 image is located in ``libcxx/utils/ci/Dockerfile``. If you are looking to reproduce the
122 failure of a specific CI job locally, you should first drop into a Docker container that
123 matches our CI images by running ``libcxx/utils/ci/run-buildbot-container``, and then run
124 the specific CI job that you're interested in (from within the container) using the ``run-buildbot``
125 script above. If you want to control which compiler is used, you can set the ``CC`` and the
126 ``CXX`` environment variables before calling ``run-buildbot`` to select the right compiler.
127 Take note that some CI jobs are testing the library on specific platforms and are *not* run
128 in our Docker image. In the general case, it is not possible to reproduce these failures
129 locally, unless they aren't specific to the platform.
131 Also note that the Docker container shares the same filesystem as your local machine, so
132 modifying files on your local machine will also modify what the Docker container sees.
133 This is useful for editing source files as you're testing your code in the Docker container.
135 Writing Tests
136 =============
138 When writing tests for the libc++ test suite, you should follow a few guidelines.
139 This will ensure that your tests can run on a wide variety of hardware and under
140 a wide variety of configurations. We have several unusual configurations such as
141 building the tests on one host but running them on a different host, which add a
142 few requirements to the test suite. Here's some stuff you should know:
144 - All tests are run in a temporary directory that is unique to that test and
145   cleaned up after the test is done.
146 - When a test needs data files as inputs, these data files can be saved in the
147   repository (when reasonable) and referenced by the test as
148   ``// FILE_DEPENDENCIES: <path-to-dependencies>``. Copies of these files or
149   directories will be made available to the test in the temporary directory
150   where it is run.
151 - You should never hardcode a path from the build-host in a test, because that
152   path will not necessarily be available on the host where the tests are run.
153 - You should try to reduce the runtime dependencies of each test to the minimum.
154   For example, requiring Python to run a test is bad, since Python is not
155   necessarily available on all devices we may want to run the tests on (even
156   though supporting Python is probably trivial for the build-host).
158 Structure of the testing related directories
159 --------------------------------------------
161 The tests of libc++ are stored in libc++'s testing related subdirectories:
163 - ``libcxx/test/support`` This directory contains several helper headers with
164   generic parts for the tests. The most important header is ``test_macros.h``.
165   This file contains configuration information regarding the platform used.
166   This is similar to the ``__config`` file in libc++'s ``include`` directory.
167   Since libc++'s tests are used by other Standard libraries, tests should use
168   the ``TEST_FOO`` macros instead of the ``_LIBCPP_FOO`` macros, which are
169   specific to libc++.
170 - ``libcxx/test/std`` This directory contains the tests that validate the library under
171   test conforms to the C++ Standard. The paths and the names of the test match
172   the section names in the C++ Standard. Note that the C++ Standard sometimes
173   reorganises its structure, therefore some tests are at a location based on
174   where they appeared historically in the standard. We try to strike a balance
175   between keeping things at up-to-date locations and unnecessary churn.
176 - ``libcxx/test/libcxx`` This directory contains the tests that validate libc++
177   specific behavior and implementation details. For example, libc++ has
178   "wrapped iterators" that perform bounds checks. Since those are specific to
179   libc++ and not mandated by the Standard, tests for those are located under
180   ``libcxx/test/libcxx``. The structure of this directories follows the
181   structure of ``libcxx/test/std``.
183 Structure of a test
184 -------------------
186 Some platforms where libc++ is tested have requirement on the signature of
187 ``main`` and require ``main`` to explicitly return a value. Therefore the
188 typical ``main`` function should look like:
190 .. code-block:: cpp
192   int main(int, char**) {
193     ...
194     return 0;
195   }
198 The C++ Standard has ``constexpr`` requirements. The typical way to test that,
199 is to create a helper ``test`` function that returns a ``bool`` and use the
200 following ``main`` function:
202 .. code-block:: cpp
204   constexpr bool test() {
205     ...
206     return true;
207   }
209   int main(int, char**) {
210     test()
211     static_assert(test());
213     return 0;
214   }
216 Tests in libc++ mainly use ``assert`` and ``static_assert`` for testing. There
217 are a few helper macros and function that can be used to make it easier to
218 write common tests.
220 libcxx/test/support/assert_macros.h
221 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223 The header contains several macros with user specified log messages. This is
224 useful when a normal assertion failure lacks the information to easily
225 understand why the test has failed. This usually happens when the test is in a
226 helper function. For example the ``std::format`` tests use a helper function
227 for its validation. When the test fails it will give the line in the helper
228 function with the condition ``out == expected`` failed. Without knowing what
229 the value of ``format string``, ``out`` and ``expected`` are it is not easy to
230 understand why the test has failed. By logging these three values the point of
231 failure can be found without resorting to a debugger.
233 Several of these macros are documented to take an ``ARG``. This ``ARG``:
235  - if it is a ``const char*`` or ``std::string`` its contents are written to
236    the ``stderr``,
237  - otherwise it must be a callable that is invoked without any additional
238    arguments and is expected to produce useful output to e.g. ``stderr``.
240 This makes it possible to write additional information when a test fails,
241 either by supplying a hard-coded string or generate it at runtime.
243 TEST_FAIL(ARG)
244 ^^^^^^^^^^^^^^
246 This macro is an unconditional failure with a log message ``ARG``. The main
247 use-case is to fail when code is reached that should be unreachable.
250 TEST_REQUIRE(CONDITION, ARG)
251 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
253 This macro requires its ``CONDITION`` to evaluate to ``true``. If that fails it
254 will fail the test with a log message ``ARG``.
257 TEST_LIBCPP_REQUIRE((CONDITION, ARG)
258 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
260 If the library under test is libc++ it behaves like ``TEST_REQUIRE``, else it
261 is a no-op. This makes it possible to test libc++ specific behaviour. For
262 example testing whether the ``what()`` of an exception thrown matches libc++'s
263 expectations. (Usually the Standard requires certain exceptions to be thrown,
264 but not the contents of its ``what()`` message.)
267 TEST_DOES_NOT_THROW(EXPR)
268 ^^^^^^^^^^^^^^^^^^^^^^^^^
270 Validates execution of ``EXPR`` does not throw an exception.
272 TEST_THROWS_TYPE(TYPE, EXPR)
273 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275 Validates the execution of ``EXPR`` throws an exception of the type ``TYPE``.
278 TEST_VALIDATE_EXCEPTION(TYPE, PRED, EXPR)
279 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
281 Validates the execution of ``EXPR`` throws an exception of the type ``TYPE``
282 which passes validation of ``PRED``. Using this macro makes it easier to write
283 tests using exceptions. The code to write a test manually would be:
286 .. code-block:: cpp
288   void test_excption([[maybe_unused]] int arg) {
289   #ifndef TEST_HAS_NO_EXCEPTIONS // do nothing when tests are disabled
290     try {
291       foo(arg);
292       assert(false); // validates foo really throws
293     } catch ([[maybe_unused]] const bar& e) {
294       LIBCPP_ASSERT(e.what() == what);
295       return;
296     }
297     assert(false); // validates bar was thrown
298   #endif
299     }
301 The same test using a macro:
303 .. code-block:: cpp
305   void test_excption([[maybe_unused]] int arg) {
306     TEST_VALIDATE_EXCEPTION(bar,
307                             [](const bar& e) {
308                               LIBCPP_ASSERT(e.what() == what);
309                             },
310                             foo(arg));
311     }
314 libcxx/test/support/concat_macros.h
315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317 This file contains a helper macro ``TEST_WRITE_CONCATENATED`` to lazily
318 concatenate its arguments to a ``std::string`` and write it to ``stderr``. When
319 the output can't be concatenated a default message will be written to
320 ``stderr``. This is useful for tests where the arguments use different
321 character types like ``char`` and ``wchar_t``, the latter can't simply be
322 written to ``stderr``.
324 This macro is in a different header as ``assert_macros.h`` since it pulls in
325 additional headers.
327  .. note: This macro can only be used in test using C++20 or newer. The macro
328           was added at a time where most of lib++'s C++17 support was complete.
329           Since it is not expected to add this to existing tests no effort was
330           taken to make it work in earlier language versions.
333 Additional reading
334 ------------------
336 The function ``CxxStandardLibraryTest`` in the file
337 ``libcxx/utils/libcxx/test/format.py`` has documentation about writing test. It
338 explains the difference between the test named  ``foo.pass.cpp`` and named
339 ``foo.verify.cpp`` are.
341 Benchmarks
342 ==========
344 Libc++ contains benchmark tests separately from the test of the test suite.
345 The benchmarks are written using the `Google Benchmark`_ library, a copy of which
346 is stored in the libc++ repository.
348 For more information about using the Google Benchmark library see the
349 `official documentation <https://github.com/google/benchmark>`_.
351 .. _`Google Benchmark`: https://github.com/google/benchmark
353 Building Benchmarks
354 -------------------
356 The benchmark tests are not built by default. The benchmarks can be built using
357 the ``cxx-benchmarks`` target.
359 An example build would look like:
361 .. code-block:: bash
363   $ cd build
364   $ ninja cxx-benchmarks
366 This will build all of the benchmarks under ``<libcxx-src>/benchmarks`` to be
367 built against the just-built libc++. The compiled tests are output into
368 ``build/projects/libcxx/benchmarks``.
370 The benchmarks can also be built against the platforms native standard library
371 using the ``-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON`` CMake option. This
372 is useful for comparing the performance of libc++ to other standard libraries.
373 The compiled benchmarks are named ``<test>.libcxx.out`` if they test libc++ and
374 ``<test>.native.out`` otherwise.
376 Also See:
378   * :ref:`Building Libc++ <build instructions>`
379   * :ref:`CMake Options`
381 Running Benchmarks
382 ------------------
384 The benchmarks must be run manually by the user. Currently there is no way
385 to run them as part of the build.
387 For example:
389 .. code-block:: bash
391   $ cd build/projects/libcxx/benchmarks
392   $ ./algorithms.libcxx.out # Runs all the benchmarks
393   $ ./algorithms.libcxx.out --benchmark_filter=BM_Sort.* # Only runs the sort benchmarks
395 For more information about running benchmarks see `Google Benchmark`_.