libs/test/doc/test_organization/test_naming.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8
   9 [section:test_naming Tests naming]
  10
  11 [h2 Acceptable characters for names]
  12 The __UTF__ is flexible on the naming the test units (test cases/suites) and
  13 it is possible to use a wide variety of characters. However there are scenarios
  14 where the name of a test unit may collide with other features
  15 of the __UTF__. For instance:
  16
  17 * a character may collide with specific command line filters for selecting a
  18   subset of the test tree. Among those characters: `'@'`, `'+'` or `'/'`
  19   (see [link boost_test.runtime_config.test_unit_filtering this section] for
  20   more details)
  21 * a name containing a character that is reserved for the shell/terminal, such as
  22   '!', '\*' ..., may prevent the test name to be passed on the command line *as is*.
  23
  24 To prevent any conflicting declaration, the __UTF__ *sanitizes* the name given to
  25 a test unit (case or suite), prior to adding the test to the test tree. Any
  26 conflicting character is replaced by an underscore `'_'`.
  27
  28 [note [*Spaces] are not considered as /special chars/ and are preserved, except for the
  29  leading and trailing spaces which are removed.]
  30
  31 [note The sanitization of the test unit names has been introduced in [link ref_CHANGE_LOG_3_7 Boost 1.67].
  32  ]
  33
  34 [h2 Constraints on test names]
  35 The __UTF__ considers an error if two sibling test cases have the same name. This consistency check is performed
  36 at runtime and is not sensitive to test filtering.
  37
  38 For test-cases registered automatically, and within the same compilation unit, a compilation error should be raised by
  39 the compiler in case of name conflict.
  40 For manual registration of test cases and in case of conflicts, the too __BOOST_TEST_CASE_NAME__ may be used.
  41
  42 The data driven tests are automatically created in an isolated test-suite and with a name that is indexed on the
  43 sample.
  44
  45
  46 [note This constraints does not apply to test-suites: Opening/closing a test-suite declaration
  47  adds the test-cases to an existing or newly created test-suite of that name.]
  48
  49 [endsect] [/ test test_naming]