view release on metacpan or  search on metacpan

bin/test-generator-mutate  view on Meta::CPAN

This command-line tool performs mutation testing on a Perl codebase.

It scans one or more C<.pm> files, generates code mutations using
L<App::Test::Generator::Mutator>, and runs the project's test suite
against each mutated version inside an isolated workspace.

For each generated mutant:

=over 4

=item *

The mutant is applied in a temporary workspace.

=item *

The mutated file is syntax-checked.

=item *

The test suite is executed using C<prove>.

=item *

If the tests fail, the mutant is considered I<killed>.

=item *

If the tests pass, the mutant is considered I<survived>.

=back

A mutation score is then calculated:

    (killed / total) * 100

Mutation testing measures the effectiveness of a test suite. A higher
mutation score indicates that the tests are better at detecting behavioral
changes in the code.

=head1 OPTIONS

=head2 --lib <dir>

Directory containing Perl modules to mutate.

Defaults to C<lib>.

=head2 --file <file>

Mutate a single file instead of scanning the entire C<--lib> directory.

=head2 --tests <dir>

Directory containing test files.

Defaults to C<t>.

=head2 --min-score <int>

Minimum acceptable mutation score (percentage).

If the final score is below this value, the program exits with a
non-zero status.

=head2 --json <file>

Write mutation results to the specified JSON file.

The output structure:

    {
        score    => "85.32",
        total    => 120,
        killed   => 102,
        survived => [ ... mutant IDs ... ]
    }

=head2 --cover_json <file>

The location of the file generated by C<cover -report json>.
That file is used to generate an approximation for an LCSAJ table.

=head2 --fail-fast

(Reserved for future use.)

=head2 --mutation_level <full|fast>

Setting to C<fast> removes redundant mutations and dedups mutations before running.
The default is C<full>.

=head2 --timeout <seconds>

(Reserved for future use.)

=head2 --verbose

Print progress information.

=head2 --quiet

Suppress final summary output.

=head1 EXIT CODES

=over 4

=item = 0

Success and mutation score meets minimum threshold.

=item = 1

Mutation score below C<--min-score>.

=item = 2

Baseline test suite failed before mutation testing began.

=item = 3