gcc/doc/gccint/testsuites/support-for-testing-gcov.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _gcov-testing:
   7
   8 Support for testing gcov
   9 ************************
  10
  11 Language-independent support for testing :command:`gcov`, and for checking
  12 that branch profiling produces expected values, is provided by the
  13 expect file :samp:`lib/gcov.exp`.  :command:`gcov` tests also rely on procedures
  14 in :samp:`lib/gcc-dg.exp` to compile and run the test program.  A typical
  15 :command:`gcov` test contains the following DejaGnu commands within comments:
  16
  17 .. code-block:: c++
  18
  19   { dg-options "--coverage" }
  20   { dg-do run { target native } }
  21   { dg-final { run-gcov sourcefile } }
  22
  23 Checks of :command:`gcov` output can include line counts, branch percentages,
  24 and call return percentages.  All of these checks are requested via
  25 commands that appear in comments in the test's source file.
  26 Commands to check line counts are processed by default.
  27 Commands to check branch percentages and call return percentages are
  28 processed if the :command:`run-gcov` command has arguments ``branches``
  29 or ``calls``, respectively.  For example, the following specifies
  30 checking both, as well as passing :option:`-b` to :command:`gcov`:
  31
  32 .. code-block:: c++
  33
  34   { dg-final { run-gcov branches calls { -b sourcefile } } }
  35
  36 A line count command appears within a comment on the source line
  37 that is expected to get the specified count and has the form
  38 ``count(cnt)``.  A test should only check line counts for
  39 lines that will get the same count for any architecture.
  40
  41 Commands to check branch percentages (``branch``) and call
  42 return percentages (``returns``) are very similar to each other.
  43 A beginning command appears on or before the first of a range of
  44 lines that will report the percentage, and the ending command
  45 follows that range of lines.  The beginning command can include a
  46 list of percentages, all of which are expected to be found within
  47 the range.  A range is terminated by the next command of the same
  48 kind.  A command ``branch(end)`` or ``returns(end)`` marks
  49 the end of a range without starting a new one.  For example:
  50
  51 .. code-block:: c++
  52
  53   if (i > 10 && j > i && j < 20)  /* branch(27 50 75) */
  54                                   /* branch(end) */
  55     foo (i, j);
  56
  57 For a call return percentage, the value specified is the
  58 percentage of calls reported to return.  For a branch percentage,
  59 the value is either the expected percentage or 100 minus that
  60 value, since the direction of a branch can differ depending on the
  61 target or the optimization level.
  62
  63 Not all branches and calls need to be checked.  A test should not
  64 check for branches that might be optimized away or replaced with
  65 predicated instructions.  Don't check for calls inserted by the
  66 compiler or ones that might be inlined or optimized away.
  67
  68 A single test can check for combinations of line counts, branch
  69 percentages, and call return percentages.  The command to check a
  70 line count must appear on the line that will report that count, but
  71 commands to check branch percentages and call return percentages can
  72 bracket the lines that report them.