NAME
DBIO::MySQL::EV::TestHarness - Reusable live-MySQL harness for EV async on_connect-replay tests
VERSION
version 0.900007
SYNOPSIS
use Test::More;
use DBIO::MySQL::EV::TestHarness;
# Skip the whole file cleanly unless a live MySQL DSN + EV::MariaDB are available.
DBIO::MySQL::EV::TestHarness->skip_all_unless_live;
my $h = DBIO::MySQL::EV::TestHarness->new(
# each fresh pool connection replays these against the owning sync storage
connect_attrs => {
on_connect_do => [ q{SET @dbio_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 @dbio_replay_tag});
});
is $_->[0][0], 'live', 'connect action replayed on this pooled connection'
for @tags;
$h->disconnect;
# A schema class without a driver gets the MySQL driver ...
my $shared = DBIO::MySQL::EV::TestHarness->new(
schema_class => 'DBIO::Test::Schema',
);
# ... or the storage_type passed here.
my $mariadb = DBIO::MySQL::EV::TestHarness->new(
schema_class => 'DBIO::Test::Schema',
storage_type => 'DBIO::MySQL::Storage::MariaDB',
);
done_testing;
DESCRIPTION
An installable test harness for the native ev async transport (DBIO::MySQL::EV::Storage). It removes the boilerplate every live EV test repeats -- parse DBIO_TEST_MYSQL_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.
None of that is MySQL-specific, so it is not implemented here: the whole surface -- "live_available" in DBIO::Test::AsyncHarness, "skip_all_unless_live" in DBIO::Test::AsyncHarness, "new" in DBIO::Test::AsyncHarness, schema, sync_storage, async, pool, timeout, await, query_on, warm_pool, run_on_each_pooled_connection and disconnect -- is inherited from DBIO::Test::AsyncHarness, which grew out of the two copies dbio-postgresql-ev and this distribution had each written by hand. What is left here is what core cannot know: four declarations, the seam that turns the EV loop, a default schema class, and the driver ("new").
The harness declares the MySQL driver itself (core ADR 0067 section 4: a driver's test helper declares its own driver by default). A schema class that declares no driver -- the shared DBIO::Test::Schema -- is connected as a clone with storage_type DBIO::MySQL::Storage, and the class itself stays undeclared. A storage_type passed to "new" wins over that default.
It ships under lib/ (not t/) on purpose: it is consumed both by this distribution's own live tests and by downstream extension distributions, which cannot see another dist's t/lib. An extension that carries a develop/recommends dependency on DBIO::MySQL::EV reaches this class from its own t/; see "REUSE BY AN EXTENSION" in DBIO::Test::AsyncHarness.
METHODS
new
my $h = DBIO::MySQL::EV::TestHarness->new(%opts);
"new" in DBIO::Test::AsyncHarness, with the driver declared by default: when schema_class (or the default schema class) declares no driver -- its storage_type is the generic DBIO::Storage::DBI -- and no storage_type is passed, storage_type is DBIO::MySQL::Storage. A passed storage_type is handed on as it is. A schema class that declares its driver is left alone: its storage_type (a storage subclass, a shortcut) stands. A driver component such as DBIO::MySQL sets its own storage class at connect, over any storage_type the harness hands on -- also over a passed one.
A core from before ADR 0067 ignores storage_type; there the schema class is connected as before.
_tick_loop
Turns the EV loop for one iteration -- the single transport-specific seam "await" in DBIO::Test::AsyncHarness drives until a Future is ready. EV is guaranteed loaded by then: it is in "harness_required_modules" in DBIO::Test::AsyncHarness, and "new" in DBIO::Test::AsyncHarness croaks unless every one of those loads.
session_status
DBIO::MySQL::EV::TestHarness->count_session_status; # once, before the first borrow
my $status = $h->session_status($conn); # { Com_stmt_prepare => 12, ... }
The status counters of the one session behind a pooled connection, from its spawn on. The pool ends a borrow with COM_RESET_CONNECTION, which sets a session's counters back to zero (core ADR 0079), so a plain SHOW SESSION STATUS sees the current borrow only. "count_session_status" wraps the transport's _reset_pool_connection: it reads SHOW SESSION STATUS on the connection itself, right ahead of the reset on the same wire, and adds the reading up per thread_id. session_status answers that sum plus the session's current reading, for Com_begin, Com_commit, Com_rollback, Com_stmt_prepare and Com_stmt_close. Only the session's own statements are counted, so other clients of the server do not move the numbers.
It waits (10 seconds at most) until the connection is out of its reset and has nothing pending, then asks the handle past the pool. It returns undef when the session cannot be asked.
count_session_status
Installs the wrapper "session_status" relies on; idempotent, process wide. Call it before the first connection is released.
CAVEAT
This is a live harness: it opens real connections against DBIO_TEST_MYSQL_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.