VERSION

Version 0.34

DESCRIPTION

Represents a single mutant - a specific transformation of a source file that a test suite should be able to detect. Each mutant carries the metadata needed to identify it, locate it in the source, and apply the transformation to a fresh PPI::Document copy at test time.

new

Construct a new mutant object.

my $mutant = App::Test::Generator::Mutant->new(
    id          => 'NUM_BOUNDARY_10_5_!=',
    description => 'Numeric boundary flip == to !=',
    original    => '==',
    line        => 10,
    type        => 'comparison',
    group       => 'NUM_BOUNDARY:10',
    transform   => sub {
        my ($doc) = @_;
        # ... modify $doc in place ...
    },
);

Arguments

• id

  A unique string identifying this mutant. Required.

• description

  A human-readable description of the mutation. Required.

• original

  The original source token or expression being mutated. Required.

• line

  The line number in the source file where the mutation occurs. Required.

• transform

  A CODE reference that accepts a PPI::Document and applies the mutation to it in place. Required.

• type

  An optional string classifying the mutation kind e.g. comparison, boolean.

• group

  An optional string grouping related mutants together e.g. all mutations on the same source line.

Returns

A blessed hashref representing the mutant. Croaks if any required attribute is missing or if transform is not a CODE reference.

API specification

input

{
    id          => { type => SCALAR },
    description => { type => SCALAR },
    original    => { type => SCALAR },
    line        => { type => SCALAR },
    transform   => { type => CODEREF },
    type        => { type => SCALAR, optional => 1 },
    group       => { type => SCALAR, optional => 1 },
}

output

{
    type => OBJECT,
    isa  => 'App::Test::Generator::Mutant',
}

id

Return the unique identifier for this mutant.

my $id = $mutant->id;

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => SCALAR }

description

Return the human-readable description of the mutation.

my $desc = $mutant->description;

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => SCALAR }

original

Return the original source token or expression that is being mutated.

my $orig = $mutant->original;

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => SCALAR }

line

Return the line number in the source file where the mutation occurs.

my $line = $mutant->line;

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => SCALAR }

transform

Return the CODE reference that applies the mutation to a PPI::Document copy.

my $xform = $mutant->transform;
$xform->($doc_copy);

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => CODEREF }

type

Return the optional mutation type classification string, e.g. comparison or boolean.

my $type = $mutant->type;

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => SCALAR, optional => 1 }

group

Return the optional group string that clusters related mutants, e.g. all mutations targeting the same source line.

my $group = $mutant->group;

API specification

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }

output

{ type => SCALAR, optional => 1 }

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

Portions of this module's initial design and documentation were created with the assistance of AI.

LICENCE AND COPYRIGHT

Copyright 2025-2026 Nigel Horne.

Usage is subject to the terms of GPL2. If you use it, please let me know.

cpanm App::Test::Generator

perl -MCPAN -e shell
install App::Test::Generator