/ 
DBIO-0.900004
/ DBIO::Test

NAME

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

VERSION

version 0.900004

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);

See t/test/06_init_schema.t for a runnable example.

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. Needs storage_type, the driver's storage class: DBIO::Test::Schema declares no driver, and a schema always has one (ADR 0067), so without it init_schema throws.

connect_info

Arrayref of the arguments for $schema->connect, used as given in place of dsn, user and pass. Also selects the real-database path.

no_deploy

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

deploy_args

Hashref handed to "deploy_schema" as its deploy arguments.

no_populate

Skip populating the test schema with sample data.

no_connect

Return the schema class without connecting.

storage_type

The storage class the schema declares as its driver.

When used together with dsn/connect_info, this behaves like "storage_type" in DBIO::Schema, and it is required there. With replicated, the master and the replicants are storages of it.

Without a real dsn the schema declares DBIO::Test::Storage, the fake driver of the mock suite, before it connects -- or, with this option, the hybrid below, which is a DBIO::Test::Storage too.

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 the connect options. Consumed only on the real-database path when it is given as dsn (a connect_info arrayref is used as given) and on the replicated fake-storage path; the default (non-replicated) fake-storage backend builds no connect options and ignores it.

quote_char, name_sep

Override the identifier quoting of the default (non-replicated) fake storage, which otherwise takes it from its storage class. An empty quote_char means no quoting. name_sep applies only while a quote character is in effect.

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/*, not in installed DBIO::Test::* namespaces. Four such fixtures are installed all the same: DBIO::Test::SyntaxErrorComponent1 to 3 and DBIO::Test::ErrorComponent, which t/90ensure_class_loaded.t loads to see the load fail.

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.