/ 
DBIO-0.900000
/ DBIO::Test

NAME

DBIO::Test - Test utilities for DBIO and DBIO driver distributions

VERSION

version 0.900000

SYNOPSIS

use DBIO::Test;

# Quick schema with fake storage (no DB needed)
my $schema = DBIO::Test->init_schema;

# With a real database
my $schema = DBIO::Test->init_schema(
  dsn  => $ENV{DBIO_TEST_PG_DSN},
  user => $ENV{DBIO_TEST_PG_USER},
  pass => $ENV{DBIO_TEST_PG_PASS},
);

# Only SQL generation tests (no deploy/populate)
my $schema = DBIO::Test->init_schema(no_deploy => 1);

DESCRIPTION

Provides the shared test harness for the DBIO ecosystem. The main entry point is "init_schema", which gives you a ready-to-use test schema backed either by DBIO::Test::Storage for offline tests or by a real database connection that you supply.

External driver distributions (e.g. DBIO::PostgreSQL, DBIO::MySQL) should depend on this module for their test suites.

The same harness can also wrap a backend in DBIO::Replicated::Storage via replicated => 1.

METHODS

is_smoker

Returns true if running under an automated smoker environment.

is_plain

Returns true if this is a plain user install (not smoker, not release testing).

init_schema

my $schema = DBIO::Test->init_schema(%opts);

Creates and returns a DBIO::Test::Schema instance.

Options:

dsn, user, pass

Connect to a real database instead of using the fake storage.

no_deploy

Skip deploying the test schema tables (via $schema->deploy).

no_populate

Skip populating the test schema with sample data.

no_connect

Return the schema class without connecting.

storage_type

Override the storage class used by the schema.

When used together with dsn/connect_info, this behaves like "storage_type" in DBIO::Schema.

When used without a real dsn, init_schema() creates a hybrid storage class combining DBIO::Test::Storage (fake execution) and the requested driver storage class. This allows offline SQL-generation tests with driver-specific SQLMaker behavior, for example:

my $schema = DBIO::Test->init_schema(
  no_deploy    => 1,
  storage_type => 'DBIO::MySQL::Storage',
);
replicated

Wrap the requested storage in DBIO::Replicated::Storage.

This is primarily intended for shared driver tests that should also exercise the replicated storage path without rebuilding the whole setup. For example:

my $schema = DBIO::Test->init_schema(
  no_deploy    => 1,
  replicated   => 1,
  storage_type => 'DBIO::MySQL::Storage',
);

Without an explicit storage_type, the replicated backend defaults to DBIO::Test::Storage.

replicant_connect_info

Optional arrayref of additional connect-info arrayrefs passed to $schema->storage->connect_replicants when replicated is enabled.

connect_opts

Extra hashref merged into connect options.

deploy_schema

DBIO::Test->deploy_schema($schema, \%sqlt_args);

Deploys the test schema. With a real database this runs $schema->deploy(). With DBIO::Test::Storage this is a no-op (the fake storage doesn't need tables).

Driver-specific deploy behaviour (e.g. add_drop_table for MySQL, or pre-deploy sql_mode fixups) is declared by the storage class itself via "deploy_defaults" in DBIO::Storage::DBI and "deploy_setup" in DBIO::Storage::DBI. Caller-supplied %sqlt_args take precedence over the storage defaults.

populate_schema

DBIO::Test->populate_schema($schema);

Populates the test schema with standard test data (artists, CDs, tracks, etc.). Skipped when using DBIO::Test::Storage.

normalize_init_schema_args

my $args = DBIO::Test->normalize_init_schema_args(\%args);

Normalizes high-level "init_schema" options into the underlying storage configuration. Driver-specific test helpers can call this to inherit shared features such as replicated => 1.

API CONTRACT

Anything under DBIO::Test::* is reusable support code for driver distributions and plugins.

Intentionally broken fixtures used to trigger edge cases belong under t/lib/TestDBIO/Broken/* only, and must not live in installed DBIO::Test::* namespaces.

CORE VS EXTERNAL TESTS

Use DBIO::Test in the core distribution for:

  • SQL generation and query-shape assertions (offline/fake storage)

  • Generic schema/result class behavior that is backend-agnostic

  • Shared fixtures used by multiple DBIO ecosystem distributions

Put backend-specific integration tests in the corresponding driver distribution (for example DBIO-SQLite, DBIO-PostgreSQL, DBIO-MySQL).

Put admin/CLI-specific tests in dbio-admin.

Put replicated-storage-specific tests in the DBIO core distribution.

NOTE

This module replaces the old DBICTest from DBIx::Class. For reference, the mapping is:

DBICTest              -> DBIO::Test
DBICTest::Schema      -> DBIO::Test::Schema
DBICTest::Util::*     -> DBIO::Test::Util::*

:DiffSQL export support is preserved.

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

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