docs/testing.md

   1 Testing policy
   2 ===
   3
   4 Aims
   5 ---
   6
   7  * Maintainers should be able to make a release of GLib at any time, confident
   8    that it will not contain regressions or obvious bugs with new functionality
   9  * Speed up review of submitted changes by deferring some of the review effort
  10    to automated testing
  11  * Allow fast detection of bugs in new or changed code, particularly if they are
  12    only present on platforms not regularly used by the maintainers
  13  * Allow easy dynamic and static analysis of a significant proportion of the
  14    GLib code
  15  * Statistics on tests (such as pass/failure) should be easily and mechanically
  16    collectable to allow analysis and highlight problems
  17  * Code for tests and code for production should be easily separable so that
  18    statistics on them can be grouped separately
  19  * Performance measurement tools for GLib should be reusable over time to allow
  20    comparable measurements to be collected and to discourage use of lower
  21    quality and throwaway tests when prototyping improvements to GLib
  22
  23 Policy
  24 ---
  25
  26  * Tests must be written for all new code, and any existing code which is being
  27    non-trivially modified (for example to fix a bug), to give confidence to the
  28    author and reviewer of the changes that they are correct for all platforms
  29    that GLib runs CI on.
  30  * Tests live in the `{glib,gobject,gio}/tests` directories. This allows their
  31    code to be counted separately when analysing statistics such as code
  32    coverage.
  33    - Performance tests live in `{glib,gobject,gio}/tests/performance`, as they
  34      are executed and results interpreted differently due to giving a result on
  35      a continuous scale rather than a pass/fail result.
  36  * All tests must use the GTest framework, as it supports
  37    [structured output](https://testanything.org/) which exposes test results to
  38    the test runner for analysis.
  39    - Use `g_test_bug()` and `g_test_summary()` in unit tests to link them to
  40      contextual information in bug reports, and to provide a summary of what
  41      each test checks and how it goes about doing those checks. Sometimes a
  42      test’s behaviour can be quite complex, and needs to be explained so that
  43      future developers can understand and build on such tests in future.
  44    - Use the `g_assert_*()` functions inside unit tests, and do not use
  45      `g_assert()`. The latter is compiled out when GLib is built with
  46      `G_DISABLE_ASSERT`, and the former are not. The `g_assert_*()` functions
  47      also give more helpful error messages on test failure.
  48  * Performance tests must be able to be run unattended. In this mode they must
  49    choose default argument values which check that the performance test
  50    functions (i.e. without crashing) and doesn’t take too long to complete. This
  51    is used to automatically verify that performance tests still work, as they
  52    are typically used infrequently and are subject to bitrot.
  53  * Code coverage reports must be used to demonstrate that unit tests reach all
  54    newly submitted or significantly modified code, reaching all lines of code
  55    and a significant majority of branches. If this is not enforced, code ends up
  56    never being tested.
  57  * Code should be structured to be testable, which is typically only possible by
  58    writing tests at the same time as the code. Otherwise it is easy to design
  59    APIs which cannot easily be unit tested, and once those APIs are stable it is
  60    hard to retrofit tests to them.
  61  * Parsers, network-facing code or code which handles untrusted user input must
  62    have fuzz tests added, in the `fuzzing` directory. These are run by
  63    [oss-fuzz](https://github.com/google/oss-fuzz/) and are very effective at
  64    catching exploitable security issues. See the
  65    [fuzzing README](../fuzzing/README.md) for more details.
  66  * When fixing bugs in existing code, regression tests must be added when it is
  67    straightforward to do so. If it’s difficult to do so (such as if the code
  68    needs to be significantly restructured or APIs need to be changed), adding
  69    the regression tests can be deferred to a follow-up issue so as not to slow
  70    down bug fixing. In that case, the bug fix must be carefully manually tested
  71    before being merged.