Commit 4043f2c9 authored by Nick Mathewson's avatar Nick Mathewson 🤹
Browse files

Adopt the LCOV convention for marking lines as unreachable by tests. 

Document this convention.

Add a script to post-process .gcov files in order to stop nagging us
about excluded lines.

Teach cov-diff to handle these post-processed files.

Closes ticket 16792
parent bd34edc1

changes/lcov_excl

0 → 100644
+7 −0
Original line number Diff line number Diff line 
  o Minor features (testing):

    - Use the lcov convention for marking lines as unreachable, so that

      we don't count them when we're generating test coverage data.

      Update our coverage tools to understand this convention.

      Closes ticket #16792.

doc/HACKING/WritingTests.md

+13 −0
Original line number Diff line number Diff line
@@ -109,6 +109,19 @@ To count new or modified uncovered lines in D2, you can run: 


    ./scripts/test/cov-diff ${D1} ${D2}" | grep '^+ *\#' | wc -l



### Marking lines as unreachable by tests



You can mark a specific line as unreachable by using the special

string LCOV_EXCL_LINE.  You can mark a range of lines as unreachable

with LCOV_EXCL_START... LCOV_EXCL_STOP.  Note that older versions of

lcov don't understand these lines.



You can post-process .gcov files to make these lines 'unreached' by

running ./scripts/test/cov-exclude on them.



Note: you should never do this unless the line is meant to 100%

unreachable by actual code.





What kinds of test should I write?

----------------------------------

scripts/test/cov-diff

+2 −2
Original line number Diff line number Diff line
@@ -9,8 +9,8 @@ DIRB="$2" 


for A in $DIRA/*; do

  B=$DIRB/`basename $A`

  perl -pe 's/^\s*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$A" > "$A.tmp"

  perl -pe 's/^\s*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$B" > "$B.tmp"

  perl -pe 's/^\s*\!*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$A" > "$A.tmp"

  perl -pe 's/^\s*\!*\d+:/        1:/; s/^([^:]+:)[\d\s]+:/$1/; s/^ *-:(Runs|Programs):.*//;' "$B" > "$B.tmp"

  diff -u "$A.tmp" "$B.tmp"

  rm "$A.tmp" "$B.tmp"

done

scripts/test/cov-exclude

0 → 100755
+28 −0
Original line number Diff line number Diff line 
#!/usr/bin/perl -p -i



use warnings;

use strict;

our $excluding;



# This script is meant to post-process a .gcov file for an input source

# that was annotated with LCOV_EXCL_START, LCOV_EXCL_STOP, and LCOV_EXCL_LINE

# entries.  It doesn't understand the LCOV_EXCL_BR* variations.

#

# It replaces unreached reached lines with x:, and reached excluded lines

# with !!!num:.



BEGIN { our $excluding = 0; }



if (m/LCOV_EXCL_START/) {

  $excluding = 1;

}

if ($excluding and m/LCOV_EXCL_STOP/) {

  $excluding = 0;

}



my $exclude_this = (m/LCOV_EXCL_LINE/);



if ($excluding or $exclude_this) {

  s{^\s*\#\#+:}{        x:};

  s{^   (\s*)(\d+):}{$1!!!$2:};

}