NAME

App::Test::Generator::BenchmarkGenerator - Generate Benchmark harnesses from ATG schemas

VERSION

Version 0.46

SYNOPSIS

use App::Test::Generator::BenchmarkGenerator;
use YAML::XS qw(LoadFile);

my $schema = LoadFile('schemas/my_func.yml');
my $bg     = App::Test::Generator::BenchmarkGenerator->new(schema => $schema);
print $bg->generate();

DESCRIPTION

Given an ATG YAML schema (as produced by extract-schemas or written by hand), generates a self-contained Perl benchmark script using "cmpthese" in Benchmark.

Each transform defined in the schema becomes one variant in the cmpthese call, with representative input values derived from the transform's type and range constraints. When no transforms are defined, a single 'default' variant is emitted using the base input specification.

The generated script is a plain .pl file suitable for running directly with perl. It is not a test file and has no dependency on any test framework.

METHODS

new

Construct a new BenchmarkGenerator for a given ATG schema.

my $bg = App::Test::Generator::BenchmarkGenerator->new(schema => $schema);

Arguments

• schema

  A hashref representing the parsed YAML schema for the target function, as produced by extract-schemas or written by hand. Must contain at minimum module and function keys. Required.

Returns

A blessed App::Test::Generator::BenchmarkGenerator object. Croaks if schema is missing or not a hashref.

EXAMPLE

use YAML::XS qw(LoadFile);
use App::Test::Generator::BenchmarkGenerator;

my $schema = LoadFile('schemas/greet.yml');
my $bg     = App::Test::Generator::BenchmarkGenerator->new(schema => $schema);
print $bg->generate();

MESSAGES

schema is required

schema was not supplied or was undef.

schema must be a hashref

schema was supplied but is not a plain hashref (e.g. an arrayref or string was passed instead).

API SPECIFICATION

input

schema   => HashRef   (required) - ATG schema hashref as loaded from YAML

output

An App::Test::Generator::BenchmarkGenerator object.

FORMAL SPECIFICATION

Pre: defined schema ∧ ref(schema) eq 'HASH'

Post: ref(result) eq 'App::Test::Generator::BenchmarkGenerator' ∧ result->{schema} eq schema

generate

Generate the complete benchmark script as a string.

my $script = $bg->generate();
write_file('benchmarks/greet.pl', $script);

Arguments

None beyond $self.

Returns

A string containing the complete, self-contained Perl benchmark script using Benchmark::cmpthese. The string is ready to write directly to a .pl file and run with perl.

Croaks if the schema is missing a module or function key.

EXAMPLE

my $script = $bg->generate();
# Write to file
open my $fh, '>', 'benchmarks/my_func.pl' or die $!;
print $fh $script;
close $fh;

# Or run immediately:
require File::Temp;
my $tmp = File::Temp->new(SUFFIX => '.pl');
print $tmp $script;
system($^X, "$tmp");

MESSAGES

schema missing module

The schema hashref has no module key.

schema missing function

The schema hashref has no function key.

API SPECIFICATION

input

None (reads from the schema passed to new).

output

A string containing the complete benchmark script, ready to write to a file.

FORMAL SPECIFICATION

Pre: defined schema->{module} ∧ defined schema->{function}

Post: result is a syntactically valid Perl script ∧ result contains exactly one cmpthese(...) call ∧ |variants| == max(1, |schema->{transforms}|)

PSEUDOCODE

read module, function, input, transforms from schema
emit shebang, use strict/warnings, use Benchmark
unless module eq 'builtin': emit use $module
if schema has 'new' key and not builtin:
    emit my $obj = Module->new(...)
if transforms defined and non-empty:
    for each transform: build a named variant call
else:
    build a single 'default' variant call
emit cmpthese($COUNT, { variant => sub { ... }, ... })

COMMON PITFALLS

Schema missing module or function

generate croaks immediately if either key is absent. Always ensure the schema has been loaded from a valid ATG YAML file before calling generate.

Expecting test-framework output

The generated script uses Benchmark::cmpthese and prints timing results to STDOUT. It is not a test file and produces no TAP output. Do not run it with prove.

OOP schemas need a new: key

If the function under benchmark is an instance method, the schema must have a new: key (even if its value is an empty hashref {}) so generate emits a my $obj = Module-new(...)> constructor call before the cmpthese block. Without it, the variant calls use Module::function(...) form.

Transforms that omit the input key

If a transform's hashref has no input key, generate falls back to the base schema input spec for that variant. This is intentional but may produce identical argument lists across variants if you forgot to add per- transform input overrides.

LIMITATIONS

Representative values are heuristic

_representative_value picks a single value based on type and min/max constraints. It does not guarantee the chosen value exercises any particular code path, and it does not use the schema's enum or matches keys.

No round-trip with extract-schemas

The generator reads any conforming ATG YAML schema, but it does not verify that the schema accurately describes the actual function's signature. If the schema is stale, the generated benchmark may pass wrong argument types.

SEE ALSO

Benchmark

bin/benchmark-generator

App::Test::Generator

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.

cpanm App::Test::Generator

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