/ 
App-Test-Generator-0.42
/ App::Test::Generator::Mutation::ReturnUndef

NAME

App::Test::Generator::Mutation::ReturnUndef - Replace return expressions with undef to expose missing undef-return checks in the test suite

VERSION

Version 0.42

METHODS

applies_to

Return true if the given document contains at least one return statement this mutation strategy could mutate. Used by App::Test::Generator::Mutator to pre-filter strategies before calling mutate, so a document with nothing to mutate skips the walk entirely.

my $applies = $mutation->applies_to($doc);

Arguments

Returns

True if the document contains a return statement (PPI::Statement::Break whose first token is return), false otherwise.

API specification

input

{
    self => { type => OBJECT, isa => 'App::Test::Generator::Mutation::ReturnUndef' },
    doc  => { type => OBJECT, isa => 'PPI::Document' },
}

output

{ type => SCALAR }

mutate

Walk a PPI document and generate one mutant for each non-bare return statement, replacing its expression with undef. For example, return $result becomes return undef.

Bare return; statements are skipped because they already return undef - mutating them would produce a redundant mutant that can never be killed.

my $mutation = App::Test::Generator::Mutation::ReturnUndef->new;
my $doc      = PPI::Document->new(\$source);
my @mutants  = $mutation->mutate($doc);

for my $m (@mutants) {
    print $m->id, ': ', $m->description, "\n";
}

Arguments

  • $self

    An instance of App::Test::Generator::Mutation::ReturnUndef.

  • $doc

    A PPI::Document object representing the parsed source to mutate. The document is not modified by this method.

Returns

A list of App::Test::Generator::Mutant objects, one per qualifying return statement found in the document. Returns an empty list if no non-bare return statements are found.

Each mutant carries a transform closure that when called with a fresh PPI::Document copy will replace the targeted return expression with the literal undef.

Notes

Mutant IDs include both line and column number to ensure uniqueness when multiple return statements appear in the same source file.

Only return statements with an expression child are mutated - bare return; statements are skipped as they already return undef.

Each mutant's optional context field is set to conditional if the return statement sits inside (or is itself the keyword of) an if/unless/while/until compound statement, or statement otherwise; its line_content field holds the raw source text of the mutated line. Both are consumed by App::Test::Generator::Mutator's fast-mode dedup.

API specification

input

{
    self => {
        type => OBJECT,
        isa  => 'App::Test::Generator::Mutation::ReturnUndef',
    },
    doc => {
        type => OBJECT,
        isa  => 'PPI::Document',
    },
}

output

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

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

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