/ 
App-Test-Generator-0.40
/ Devel::App::Test::Generator::LCSAJ::Runtime

NAME

Devel::App::Test::Generator::LCSAJ::Runtime - Debugger backend for LCSAJ coverage

VERSION

Version 0.40

SYNOPSIS

PERL5OPT='-d:App::Test::Generator::LCSAJ::Runtime -Mblib' prove -l t

DESCRIPTION

This module is loaded as a Perl debugger backend using the -d:Module flag.

When Perl sees -d:App::Test::Generator::LCSAJ::Runtime it prepends Devel:: and loads Devel/App/Test/Generator/LCSAJ/Runtime.pm from @INC. The file must therefore live at that path - typically lib/Devel/App/Test/Generator/LCSAJ/Runtime.pm.

Perl automatically calls DB::DB before executing each statement while the debugger is active. We record (file, line) pairs to build runtime hit data for later LCSAJ analysis.

Results are written to cover_html/lcsaj_hits/hits_PID.json at process exit, one file per process so that parallel test runs do not overwrite each other.

ENVIRONMENT

LCSAJ_TARGETS

Optional colon-separated list of absolute paths (as produced by realpath) to restrict recording to specific source files. When empty or unset every non-internal file is recorded.

DB::DB

Perl debugger hook, automatically invoked by the interpreter before every statement while this module is active as a -d: debugger backend. Records a per-(file, line) hit count used later for LCSAJ coverage analysis.

Arguments

None. Perl calls this sub directly; the current execution location is obtained internally via caller(0).

Returns

Nothing meaningful — this is a void debugger callback.

Side effects

Increments %HITS{$norm}{$line} for the normalised path and line number of the statement about to execute. Resolves each distinct raw filename via Cwd::abs_path once, memoising the result in %NORM_CACHE.

Usage example

Not called directly — activated via the Perl debugger flag:

PERL5OPT='-d:App::Test::Generator::LCSAJ::Runtime -Mblib' prove -l t

API specification

input

{ }

output

{ type => UNDEF }

Formal specification

Let H be the hits relation (file x line) → ℕ, T be the target-file set, and I be the internal-file predicate (true only for this module's own source path).

┌ DB_DB ──────────────────────────────────────────
│ ΔH
│ file? : FilePath
│ line? : ℕ
├─────────────────────────────────────────────────
│ norm == normalize(file?)
│ ¬I(norm) ∧ (T = ∅ ∨ norm ∈ T)
│   ⟹ H′(norm, line?) = H(norm, line?) + 1
│ I(norm) ∨ (T ≠ ∅ ∧ norm ¬in; T)
│   ⟹ H′ = H
└─────────────────────────────────────────────────

OUTPUT FORMAT

cover_html/lcsaj_hits/hits_PID.json is a JSON object of the form:

{
  "lib/Foo/Bar.pm": { "12": 3, "15": 1, ... },
  ...
}

Keys are lib-relative paths (lib/...); values are objects mapping line numbers (as strings) to hit counts. One file is written per process so parallel test runs produce separate files.

NOTES ON FILE PLACEMENT

The -d:App::Test::Generator::LCSAJ::Runtime flag causes Perl to load Devel::App::Test::Generator::LCSAJ::Runtime, which it finds at:

lib/Devel/App/Test/Generator/LCSAJ/Runtime.pm

Ensure this path is on @INC (-Mblib or -Ilib in PERL5OPT).

SEE ALSO

Devel::Cover, App::Test::Generator

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.