.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Lintian 3"
.TH Test::Lintian 3 "2019-05-26" "Lintian v2.15.0" "Debian Package Checker"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Lintian \-\- Check Lintian files for issues
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& # file 1
\& use Test::Lintian;
\& use Test::More import => [\*(Aqdone_testing\*(Aq];
\& test_load_profiles(\*(Aqsome/path\*(Aq);
\& 
\& done_testing;
\& 
\& # file 2
\& use Test::Lintian;
\& use Test::More import => [\*(Aqdone_testing\*(Aq];
\& load_profile_for_test(\*(Aqvendor/profile\*(Aq, \*(Aqsome/path\*(Aq, \*(Aq/usr/share/lintian\*(Aq);
\& test_check_desc(\*(Aqsome/path/checks\*(Aq);
\& test_load_checks(\*(Aqsome/path/checks\*(Aq);
\& test_tags_implemented(\*(Aqsome/path/checks\*(Aq);
\& 
\& done_testing;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A testing framework for testing various Lintian files for common
errors.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "test_check_desc([\s-1OPTS,\s0 ]CHECKS...)" 4
.IX Item "test_check_desc([OPTS, ]CHECKS...)"
Test check desc files (and the tags in them) for common errors.
.Sp
\&\s-1OPTS\s0 is an optional \s-1HASHREF\s0 containing key/value pairs, which are
described below.
.Sp
\&\s-1CHECKS\s0 is a list of paths in which to check desc files.  Any given
element in \s-1CHECKS\s0 can be either a file or a dir.  Files are assumed to
be check desc file.  Directories are searched and all \fI.desc\fR files
in those dirs are processed.
.Sp
As the number of tests depends on the number of tags in desc, it is
difficult to \*(L"plan ahead\*(R" when using this test.  It is therefore
recommended to not specify a plan and use \fBdone_testing()\fR.
.Sp
This sub uses a Data file (see \*(L"load_profile_for_test ([PROFNAME[, \s-1INC...\s0]])\*(R").
.Sp
\&\s-1OPTS\s0 may contain the following key/value pairs:
.RS 4
.IP "coll-dir" 4
.IX Item "coll-dir"
Path to the collection directory (defaults to:
/usr/share/lintian/collection).  This is mostly useful for testing
Lintian itself.
.Sp
If set to \f(CW\*(C`undef\*(C'\fR, the test of Needs-Info containing only existing
collections will be skipped.
.IP "filter" 4
.IX Item "filter"
If defined, it is a filter function that examines \f(CW$_\fR (or its first
argument) and returns a truth value if \f(CW$_\fR should be considered or
false otherwise.  \f(CW$_\fR will be the path to the current file (or dir)
in question; it may be relative or absolute.
.Sp
\&\s-1NB:\s0 \fIall\fR elements in \s-1CHECKS\s0 are subject to the filter.
.Sp
\&\s-1CAVEAT:\s0 If the filter rejects a directory, none of the files in it will be
considered either.  Even if the filter accepts a file, that file will
only be processed if it has the proper extension (i.e. with \fI.desc\fR).
.IP "translation" 4
.IX Item "translation"
If defined and a truth value, the desc files are expected to contain
translations.  Otherwise, they must be regular checks.
.RE
.RS 4
.RE
.IP "test_load_profiles(\s-1ROOT, INC...\s0)" 4
.IX Item "test_load_profiles(ROOT, INC...)"
Test that all profiles in \fIROOT/profiles\fR are loadable.  \s-1INC\s0 will be
the \s-1INC\s0 path used as include path for the profile.
.Sp
If \s-1INC\s0 is omitted, then the include path will consist of (\s-1ROOT,\s0
\&'/usr/share/lintian').  Otherwise, \s-1INC\s0 will be used as is (and should
include \s-1ROOT\s0).
.Sp
This sub will do one test per profile loaded.
.IP "test_load_checks([\s-1OPTS,\s0 ]DIR[, \s-1CHECKNAMES...\s0])" 4
.IX Item "test_load_checks([OPTS, ]DIR[, CHECKNAMES...])"
Test that the Perl module implementation of the checks can be loaded
and has a run sub.
.Sp
\&\s-1OPTS\s0 is an optional \s-1HASHREF\s0 containing key/value pairs, which are
described below.
.Sp
\&\s-1DIR\s0 is the directory where the checks can be found.
.Sp
\&\s-1CHECKNAMES\s0 is a list of check names.  If \s-1CHECKNAMES\s0 is given, only the
checks in this list will be processed.  Otherwise, all the checks in
\&\s-1DIR\s0 will be processed.
.Sp
For planning purposes, every check processed counts for 2 tests and
the call itself does on additional check.  So if \s-1CHECKNAMES\s0 contains
10 elements, then 21 tests will be done (2 * 10 + 1).  Filtered out
checks will \fInot\fR be counted.
.Sp
All data files created at compile time or in the file scope will be
loaded immediately (instead of lazily as done during the regular
runs).  This is done to spot missing data files or typos in their
names.  Therefore, this sub will load a profile if one hasn't been
loaded already.  (see \*(L"load_profile_for_test ([PROFNAME[,
\&\s-1INC...\s0]])\*(R")
.Sp
\&\s-1OPTS\s0 may contain the following key/value pairs:
.RS 4
.IP "filter" 4
.IX Item "filter"
If defined, it is a filter function that examines \f(CW$_\fR (or its first
argument) and returns a truth value if \f(CW$_\fR should be considered or
false otherwise.  \f(CW$_\fR will be the path to the current file (or dir)
in question; it may be relative or absolute.
.Sp
\&\s-1NB:\s0 filter is \fInot\fR used if \s-1CHECKNAMES\s0 is given.
.Sp
\&\s-1CAVEAT:\s0 If the filter rejects a directory, none of the files in it will be
considered either.  Even if the filter accepts a file, that file will
only be processed if it has the proper extension (i.e. with \fI.desc\fR).
.RE
.RS 4
.RE
.IP "test_tags_implemented ([\s-1OPTS,\s0 ]DIR[, \s-1CHECKNAMES...\s0])" 4
.IX Item "test_tags_implemented ([OPTS, ]DIR[, CHECKNAMES...])"
Test a given check implements all the tags listed in its desc file.
For planning purposes, each check counts as one test and the call
itself do one additional check.  So if 10 checks are tested, the plan
should account for 11 tests.
.Sp
This is a simple scan of the source code looking asserting that the
tag names \fIappear\fR (in the actual code part).  For a vast majority of
Lintian's tags it is reliable enough to be useful.  However it has
false-positives and false-negatives \- the former can be handled via
\&\*(L"exclude-pattern\*(R" (see below).
.Sp
The \s-1DIR\s0 argument is the directory in which to find the checks.
.Sp
\&\s-1CHECKNAMES\s0 is a list of the check names.  If \s-1CHECKNAMES\s0 is given, only
the checks in this list will be processed.  Otherwise, all the checks
in \s-1DIR\s0 will be processed.
.Sp
The optional parameter \s-1OPTS\s0 is a hashref.  If passed it must be the
first argument.  The following key/value pairs are defined:
.RS 4
.IP "exclude-pattern" 4
.IX Item "exclude-pattern"
The value is assumed to be a regex (or a string describing a regex).
Any tag matching this regex will be excluded from this test and is
assumed to be implemented (regardless of whether that is true or not).
.Sp
This is useful for avoiding false-positives with cases like:
.Sp
.Vb 4
\&  foreach my $x (@y) {
\&    tag "some\-tag\-for\-$x", "blah blah $x"
\&        unless f($x);
\&  }
.Ve
.IP "filter" 4
.IX Item "filter"
If defined, it is a filter function that examines \f(CW$_\fR (or its first
argument) and returns a truth value if \f(CW$_\fR should be considered or
false otherwise.  \f(CW$_\fR will be the path to the current file (or dir)
in question; it may be relative or absolute.
.Sp
\&\s-1NB:\s0 filter is \fInot\fR used if \s-1CHECKNAMES\s0 is given.
.Sp
\&\s-1CAVEAT:\s0 If the filter rejects a directory, none of the files in it will be
considered either.  Even if the filter accepts a file, that file will
only be processed if it has the proper extension (i.e. with \fI.desc\fR).
.RE
.RS 4
.Sp
As mentioned, this test assert that the tag name appears in the code.
Consider the following example:
.Sp
.Vb 2
\& my $tagname = \*(Aqmy\-tag\*(Aq;
\& $tagname = \*(Aqmy\-other\-tag\*(Aq if $condition;
.Ve
.Sp
In this example, this test would conclude that 'my\-tag' and
\&'my\-other\-tag' are both implemented.  Which is good when \f(CW$tagname\fR is
eventually passed to tag, and a false-negative
otherwise.
.Sp
Comment lines are \fInot\fR ignored, so comments can be used as an
alternative to the exclude-pattern (above).
.RE
.IP "load_profile_for_test ([PROFNAME[, \s-1INC...\s0]])" 4
.IX Item "load_profile_for_test ([PROFNAME[, INC...]])"
Load a Lintian::Profile and ensure Data files can be used.  This is
needed if the test needs to access a data file or if a special profile
is needed for the test.  It does \fInot\fR test the profile for issues.
.Sp
\&\s-1PROFNAME\s0 is the name of the profile to load.  It can be omitted, in
which case the sub ensures that a profile has been loaded.  If no
profile has been loaded, 'debian/main' will be loaded.
.Sp
\&\s-1INC\s0 is a list of extra \*(L"include dirs\*(R" (or Lintian \*(L"roots\*(R") to be used
for finding the profile.  If not specified, it defaults to
\&\fI\f(CI$ENV\fI{'\s-1LINTIAN_TEST_ROOT\s0'}\fR and \fI/usr/share/lintian\fR (in order).
\&\s-1INC\s0 is ignored if a profile has already been loaded.
.Sp
\&\s-1CAVEAT:\s0 Only one profile can be loaded in a given test.  Once a
profile has been loaded, it is not possible to replace it with another
one.  So if this is invoked multiple times, \s-1PROFNAME\s0 must be omitted
or must match the name of the loaded profile.
.IP "program_name_to_perl_paths(\s-1PROGNAME\s0)" 4
.IX Item "program_name_to_perl_paths(PROGNAME)"
Map the program name (e.g. \f(CW$0\fR) to a list of directories or/and
files that should be processed.
.Sp
This helper sub is mostly useful for splitting up slow tests run over
all Perl scripts/modules in Lintian.  This allows better use of
multiple cores.  Example:
.Sp
.Vb 5
\&  t/scripts/my\-test/
\&   runner.pl
\&   checks.t \-> runner.pl
\&   collection.t \-> runner.pl
\&   ...
.Ve
.Sp
And then in runner.pl:
.Sp
.Vb 1
\&  use Test::Lintian;
\&  
\&  my @paths = program_name_to_perl_paths($0);
\&  # test all files/dirs listed in @paths
.Ve
.Sp
For a more concrete example, see t/scripts/01\-critic/ and the
files/symlinks beneath it.