commit 4043f2c95f4a47e69edc4d451673b7ffda066768 Author: Nick Mathewson nickm@torproject.org Date: Tue Apr 12 21:12:10 2016 -0400

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 --- changes/lcov_excl | 7 +++++++ doc/HACKING/WritingTests.md | 13 +++++++++++++ scripts/test/cov-diff | 4 ++-- scripts/test/cov-exclude | 28 ++++++++++++++++++++++++++++ 4 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/changes/lcov_excl b/changes/lcov_excl new file mode 100644 index 0000000..474181c --- /dev/null +++ b/changes/lcov_excl @@ -0,0 +1,7 @@ + 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. + + diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index bd2ee0e..7bcadc6 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -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? ---------------------------------- diff --git a/scripts/test/cov-diff b/scripts/test/cov-diff index 48dbec9..7da7f0b 100755 --- a/scripts/test/cov-diff +++ b/scripts/test/cov-diff @@ -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 diff --git a/scripts/test/cov-exclude b/scripts/test/cov-exclude new file mode 100755 index 0000000..5117f11 --- /dev/null +++ b/scripts/test/cov-exclude @@ -0,0 +1,28 @@ +#!/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:}; +}