.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "Test::Lintian 3"
.TH Test::Lintian 3 2024-02-05 "Lintian v2.117.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(OPTS, CHECKS...)" 4
.IX Item "test_check_desc(OPTS, CHECKS...)"
Test check desc files (and the tags in them) for common errors.
.Sp
OPTS is a HASHREF containing key/value pairs, which are
described below.
.Sp
CHECKS is a list of paths in which to check desc files.  Any given
element in CHECKS 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 "plan ahead" 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 "load_profile_for_test ([PROFNAME[, INC...]])").
.Sp
OPTS 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
NB: \fIall\fR elements in CHECKS are subject to the filter.
.Sp
CAVEAT: 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(ROOT, INC...)" 4
.IX Item "test_load_profiles(ROOT, INC...)"
Test that all profiles in \fIROOT/profiles\fR are loadable.  INC will be
the INC path used as include path for the profile.
.Sp
If INC is omitted, then the include path will consist of (ROOT,
\&'/usr/share/lintian').  Otherwise, INC will be used as is (and should
include ROOT).
.Sp
This sub will do one test per profile loaded.
.IP "test_load_checks(OPTS, DIR[, CHECKNAMES...])" 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
OPTS is a HASHREF containing key/value pairs, which are
described below.
.Sp
DIR is the directory where the checks can be found.
.Sp
CHECKNAMES is a list of check names.  If CHECKNAMES is given, only the
checks in this list will be processed.  Otherwise, all the checks in
DIR will be processed.
.Sp
For planning purposes, every check processed counts for 2 tests and
the call itself does on additional check.  So if CHECKNAMES 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 "load_profile_for_test ([PROFNAME[,
INC...]])")
.Sp
OPTS 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
NB: filter is \fInot\fR used if CHECKNAMES is given.
.Sp
CAVEAT: 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 "load_profile_for_test ([PROFNAME[, INC...]])" 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
PROFNAME 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
INC is a list of extra "include dirs" (or Lintian "roots") to be used
for finding the profile.  If not specified, it defaults to
\&\fR\f(CI$ENV\fR\fI{'LINTIAN_BASE'}\fR and \fI/usr/share/lintian\fR (in order).
INC is ignored if a profile has already been loaded.
.Sp
CAVEAT: 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, PROFNAME must be omitted
or must match the name of the loaded profile.
.IP program_name_to_perl_paths(PROGNAME) 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.