NAME

Test::HTTP::Scenario - Deterministic record/replay of HTTP interactions for test suites

VERSION

Version 0.01

SYNOPSIS

use Test::Most;
use Test::HTTP::Scenario qw(with_http_scenario);

with_http_scenario(
    name    => 'get_user_basic',
    file    => 't/fixtures/get_user_basic.yaml',
    mode    => 'replay',
    adapter => 'LWP',
    sub {
        my $user = $client->get_user(42);
        cmp_deeply($user, superhashof({ id => 42 }));
    },
);

DESCRIPTION

Test::HTTP::Scenario lets you test HTTP-based code without ever hitting the real network, by recording real interactions once and replaying them forever. It provides a deterministic record/replay mechanism for HTTP-based test suites. It allows you to capture real HTTP interactions once (record mode) and replay them later without network access (replay mode). This makes API client tests fast, hermetic, and fully deterministic.

Adapters provide the glue to specific HTTP client libraries such as LWP. Serializers control how fixtures are stored on disk.

MODES

record

Real HTTP requests are executed. Each request/response pair is normalized and appended to the fixture. The fixture file is written at the end of run().

replay

No real HTTP requests are made. Requests are matched against the fixture in order, and responses are reconstructed from stored data.

STRICT MODE

If strict => 1 is enabled, replay mode requires that all recorded interactions are consumed. If the callback returns early, run() croaks with a strict-mode error.

DIFFING

If diffing => 1 (default), mismatched requests produce a detailed diff showing expected and actual method, URI, and normalized request structures.

ADAPTERS

Adapters implement:

request/response normalization
response reconstruction
temporary monkey-patching of the HTTP client library

Available adapters:

You may also supply a custom adapter object.

SERIALIZERS

Serializers implement encoding and decoding of fixture files.

Available serializers:

YAML (default)
JSON

USING RECORD AND REPLAY IN REAL-WORLD APPLICATIONS

This section describes the recommended workflow for using Test::HTTP::Scenario in a real-world test suite. The goal is to capture real HTTP traffic once (record mode) and then replay it deterministically in all subsequent test runs (replay mode).

Overview

Record/replay is designed for API client libraries that normally make live HTTP requests. In record mode, the module performs real network calls and stores normalized request/response pairs in a fixture file. In replay mode, the module prevents all network access and returns synthetic responses reconstructed from the fixture.

This allows your test suite to:

run without network access
avoid flakiness caused by external services
run quickly and deterministically in CI
capture complex multi-step API flows once and reuse them

Typical Workflow

Step 1: Write your test using `with_http_scenario`

use Test::Most;
use Test::HTTP::Scenario qw(with_http_scenario);

with_http_scenario(
    name    => 'get_user_flow',
    file    => 't/fixtures/get_user_flow.yaml',
    mode    => $ENV{SCENARIO_MODE} || 'replay',
    adapter => 'LWP',
    sub {
        my $user = MyAPI->new->get_user(42);
        is $user->{id}, 42, 'user id matches';
    },
);

Step 2: Run the test suite in record mode

$ SCENARIO_MODE=record prove -l t/get_user_flow.t

This performs real HTTP requests and writes the fixture file:

t/fixtures/get_user_flow.yaml

Step 3: Commit the fixture file to version control

The fixture becomes part of your test assets. It should be treated like any other test data file.

Step 4: Run the test suite normally (replay mode)

$ prove -l t

Replay mode:

loads the fixture
intercepts all HTTP requests
matches them against the recorded interactions
returns synthetic responses

No network access is required.

Updating Fixtures

If the API changes or you need to refresh the recorded data, simply delete the fixture file and re-run the test in record mode:

$ rm t/fixtures/get_user_flow.yaml
$ SCENARIO_MODE=record prove -l t/get_user_flow.t

Example: Multi-Step API Flow

Record mode captures each request in order:

with_http_scenario(
    name    => 'create_and_fetch',
    file    => 't/fixtures/create_and_fetch.yaml',
    mode    => $ENV{SCENARIO_MODE} || 'replay',
    adapter => 'LWP',
    sub {
        my $api = MyAPI->new;

        my $id = $api->create_user({ name => 'Alice' });
        my $user = $api->get_user($id);

        is $user->{name}, 'Alice';
    },
);

Replay mode enforces the same sequence, ensuring your client behaves correctly across multiple calls.

Notes

Replay mode never performs real HTTP requests.
Strict mode can be enabled to ensure all interactions are consumed.
Diffing mode provides detailed diagnostics when a request does not match.
Fixtures are stable across platforms and Perl versions.

METHODS

new

Construct a new scenario object.

Purpose

Initializes a scenario with a name, fixture file, mode, adapter, and serializer. Loads adapter and serializer classes and binds the adapter to the scenario.

Arguments

name (Str, required)

Scenario name.
file (Str, required)

Path to the fixture file.
mode (Str, required)

Either record or replay.
adapter (Str|Object, required)

Adapter name such as LWP or an adapter object.
serializer (Str, optional)

Serializer name, default YAML.
diffing (Bool, optional)

Enable or disable diffing, default true.
strict (Bool, optional)

Enable or disable strict behaviour, default false.

Returns

A new Test::HTTP::Scenario object.

Side Effects

Loads adapter and serializer classes dynamically. Binds the adapter to the scenario.

Notes

The adapter object persists across calls to run().

run

Execute a coderef under scenario control.

Purpose

Installs adapter hooks, loads fixtures in replay mode, executes the callback, and saves fixtures in record mode. Ensures uninstall and save always occur.

Arguments

CODE (Coderef, required)

The code to execute while the adapter hooks are active.

Returns

Whatever the coderef returns, preserving list, scalar, or void context.

Side Effects

Installs adapter hooks.
Loads fixtures in replay mode.
Saves fixtures in record mode.
Uninstalls adapter hooks at scope exit.

Notes

Exceptions propagate naturally. Strict mode enforces full consumption of recorded interactions.

with_http_scenario

Convenience wrapper for constructing and running a scenario.

Purpose

Creates a scenario object from key/value arguments and immediately executes run() with the supplied coderef.

Arguments

Key/value pairs identical to new, followed by a coderef.

Returns

Whatever the coderef returns.

Side Effects

Constructs a scenario and installs adapter hooks during execution.

Notes

The final argument must be a coderef.

handle_request

Handle a single HTTP request in record or replay mode.

Purpose

In record mode, performs the real HTTP request and stores the normalized request and response. In replay mode, matches the incoming request against stored interactions and returns a synthetic response.

Arguments

req (Object)

Adapter-specific request object.
do_real (Coderef)

Coderef that performs the real HTTP request.

Returns

In record mode: the real HTTP::Response.
In replay mode: a reconstructed HTTP::Response.

Side Effects

Appends interactions in record mode.
Advances the internal cursor in replay mode.

Notes

Matching is currently based on method and URI only. Diffing mode produces detailed mismatch diagnostics.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

BUGS

REPOSITORY

https://github.com/nigelhorne/Test-HTTP-Scenario

SUPPORT

This module is provided as-is without any warranty.

Please report any bugs or feature requests to bug-test-http-scenario at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-HTTP-Scenario. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

perldoc Test::HTTP::Scenario

You can also look for information at:

MetaCPAN

https://metacpan.org/dist/Test-HTTP-Scenario
RT: CPAN's request tracker

https://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-HTTP-Scenario
CPAN Testers' Matrix

http://matrix.cpantesters.org/?dist=Test-HTTP-Scenario
CPAN Testers Dependencies

http://deps.cpantesters.org/?module=Test::HTTP::Scenario

LICENCE AND COPYRIGHT

Usage is subject to licence terms.

The licence terms of this software are as follows:

Personal single user, single computer use: GPL2
All other users (including Commercial, Charity, Educational, Government) must apply in writing for a licence for use from Nigel Horne at the above e-mail.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

MODES

record

replay

STRICT MODE

DIFFING

ADAPTERS

SERIALIZERS

USING RECORD AND REPLAY IN REAL-WORLD APPLICATIONS

Overview

Typical Workflow

Step 1: Write your test using with_http_scenario

Step 2: Run the test suite in record mode

Step 3: Commit the fixture file to version control

Step 4: Run the test suite normally (replay mode)

Updating Fixtures

Example: Multi-Step API Flow

Notes

METHODS

new

Purpose

Arguments

Returns

Side Effects

Notes

run

Purpose

Arguments

Returns

Side Effects

Notes

with_http_scenario

Purpose

Arguments

Returns

Side Effects

Notes

handle_request

Purpose

Arguments

Returns

Side Effects

Notes

AUTHOR

BUGS

SEE ALSO

REPOSITORY

SUPPORT

LICENCE AND COPYRIGHT

Step 1: Write your test using `with_http_scenario`