NAME
Devel::XSCover::Test - the test run under Devel::Cover
SYNOPSIS
use Devel::XSCover::Test;
my $test = Devel::XSCover::Test->new(dir => '.', db => 'cover_db');
my $status = $test->run;DESCRIPTION
Runs a distribution's tests once, under Devel::Cover for the Perl side and on the instrumented objects for the C side, so both land in one coverage database from one run. The environment is the one cover -test sets: HARNESS_PERL_SWITCHES and PERL5OPT both carry -MDevel::Cover=-db,DIR, after anything in DEVEL_COVER_TEST_OPTS, plus an ignore of every absolute path: PERL5OPT covers every perl that runs, prove itself and the scripts a test writes under the temporary directory included, and none of those is the distribution's code, and an ignore of Install/Files.pm, the file ExtUtils::Depends generates at configure time for a distribution that exports a C API, which a test linking against that API loads and which has no POD of its own. RELEASE_TESTING and the rest of the environment pass through untouched.
A process that ends by POSIX::_exit or by a signal writes no C counters, since the compiler's runtime writes them at a normal exit. The Perl side of such a process is unaffected, as Devel::Cover writes from its own END block. A test that uses threads dies under Devel::Cover ("Devel::Cover does not yet work with threads", at compile time, so the file fails). Any test file that uses threads is found and run without Devel::Cover by itself, and the run says so, unless threads_covered asks for it to be left alone. The plain list adds other files. A suite that behaves differently under Devel::Cover altogether, as one whose module rewrites the op tree does, runs without it with no_perl, and then only the C side is in the report.
METHODS
new
my $test = Devel::XSCover::Test->new(%options);Options: dir, db, make, prove, test (an array reference of test files to run instead of the whole suite), plain (an array reference of test files to run without Devel::Cover), no_perl (run everything without it), no_deparse (leave custom ops to B::Deparse's own fallback), threads_covered (do not take thread tests out of the covered run), delete (remove the database first, on by default), timeout (seconds, none by default), dry and silent.
db_path
The absolute path of the database.
switches
The perl switches put in the environment of a covered run: Devel::XSCover::Deparse first, so a custom op without a deparse of its own does not make Devel::Cover warn, then Devel::Cover. With silent, Devel::Cover's own messages are turned off too.
deparse_switch
The switch that loads Devel::XSCover::Deparse, with -I for its directory when this module runs from a source tree, or nothing with no_deparse.
reset_db
Removes the database when delete is set and it exists. Returns true when it did.
thread_tests
my @files = $test->thread_tests(@files);The test files (those given, or every t/*.t) that load threads or Thread or call threads->create.
commands
The commands of the run, each a pair of the command words and whether it runs under Devel::Cover. With neither test nor plain that is make test alone. Otherwise the files (those given, or every t/*.t) less the plain ones run with prove -b -j1 under Devel::Cover, and the plain ones with the same command without it. With no_perl nothing runs under Devel::Cover.
run
Resets the database, runs the commands, and returns the first non-zero exit status, or zero. A run that passes timeout seconds has its process group ended and returns 124.