NAME

DBIO::PostgreSQL::EV::TestHarness - Reusable live-PostgreSQL harness for EV async on_connect-replay tests

VERSION

version 0.900007

SYNOPSIS

use Test::More;
use DBIO::PostgreSQL::EV::TestHarness;

# Skip the whole file cleanly unless a live PG DSN + EV::Pg are available.
DBIO::PostgreSQL::EV::TestHarness->skip_all_unless_live;

my $h = DBIO::PostgreSQL::EV::TestHarness->new(
    # each fresh pool connection replays these against the owning sync storage
    connect_attrs => {
        on_connect_do => [ q{SET myapp.replay_tag = 'live'} ],
        pool_size     => 4,
    },
);

# Force 3 DISTINCT pool connections to spawn (each replays the connect
# actions at spawn) and run an async op on each -- the replay-verification seam.
my @tags = $h->run_on_each_pooled_connection(3, sub {
    my ($conn, $harness) = @_;
    return $harness->query_on($conn, q{SELECT current_setting('myapp.replay_tag')});
});
is $_->[0][0], 'live', 'connect action replayed on this pooled connection'
    for @tags;

$h->disconnect;
done_testing;

DESCRIPTION

An installable test harness for the native ev async transport (DBIO::PostgreSQL::EV::Storage). It removes the boilerplate every live EV test repeats -- parse DBIO_TEST_PG_DSN, connect an { async => 'ev' } schema, reach the embedded async backend + its pool, drive the EV loop -- and, crucially, provides the one thing an on_connect-replay test needs and cannot get from a directly-constructed storage: an EV async backend wired to an owning sync storage whose on_connect_do / on_connect_call actually replay on every freshly-spawned pool connection.

All of that machinery is inherited from DBIO::Test::AsyncHarness, the parametrised base core ships (ADR 0030 §4). This class supplies only what core cannot know: the four class declarations below, the EV-specific "_tick_loop", and the default schema class. live_available, skip_all_unless_live, new, schema, sync_storage, async, pool, timeout, await, query_on, warm_pool, run_on_each_pooled_connection and disconnect are all core's.

It ships under lib/ (not t/) on purpose: it is consumed both by this distribution's own live tests and by downstream extension distributions (e.g. dbio-postgresql-age), which cannot see another dist's t/lib. An extension that carries a develop/recommends dependency on DBIO::PostgreSQL::EV reaches this class from its own t/.

METHODS

_tick_loop

Drives one iteration of the EV event loop -- the single thing core's DBIO::Test::AsyncHarness cannot know, and the only method this class implements. await calls it until the Future is ready.

EV is loaded here rather than at compile time on purpose: this class must stay loadable without it, or "skip_all_unless_live" in DBIO::Test::AsyncHarness could not skip on the very machines it exists to skip on. live_available is what probes for EV and EV::Pg, and new refuses without it, so by the time this runs the module is present.

REUSE BY AN EXTENSION (e.g. AGE)

An async storage extension composes onto this transport via core's storage-layer composition; it does not ship its own transport. To live-test that its on_connect_call (e.g. connect_call_load_age) replays on pooled EV connections, an extension reuses this harness by supplying its own schema class (carrying the extension's storage layer + component) and its own per-connection assertion:

my $h = DBIO::PostgreSQL::EV::TestHarness->new(
    schema_class  => 'MyApp::Age::Schema',        # registers the Age layer
    connect_attrs => { on_connect_call => 'load_age', pool_size => 3 },
);

$h->run_on_each_pooled_connection(3, sub {
    my ($conn, $harness) = @_;
    # LOAD 'age' + search_path must have replayed on THIS pooled connection
    return $harness->query_on($conn, q{SELECT current_setting('search_path')});
});

The harness stays generic: it never mentions AGE, exposes the schema / sync storage / async backend / pool, and lets the caller add the layer (via schema_class) and assert whatever it needs on each pooled connection.

CAVEAT

This is a live harness: it opens real connections against DBIO_TEST_PG_DSN. It is for driver/extension test suites, not production code. It is excluded from the mock-only offline discipline by design -- gate every consumer with "skip_all_unless_live" in DBIO::Test::AsyncHarness.

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.