ADR-004: Test::Params::Util -- test predicates

Status

Proposed

Context

The original TODO list for Params::Util included a "Test:: version of this module, for use in testing." The idea is to provide test functions that produce TAP-compatible diagnostics:

instance_ok($obj, 'Foo', 'constructor returns a Foo');
can_ok_methods($obj, qw(connect disconnect));

Perl's testing ecosystem already offers "isa_ok" in Test::More and "can_ok" in Test::More, but these do not cover the full range of Params::Util predicates (_CODELIKE, _HASHLIKE, _HANDLE, _DRIVER, etc.).

Decision

Implement Test::Params::Util as a separate CPAN distribution.

Why not in the Params-Util dist?

Test modules depend on Test2 or Test::Builder. Params::Util is a zero-non-core-dependency module used deep in dependency chains. Pulling test infrastructure into its prerequisites would create circular or heavyweight dependencies for something that is only needed at test time.

Why not a bundled module excluded from runtime?

Even as an optional module, shipping it in the same dist means the .pm file is installed into @INC. Build systems that scan installed modules (e.g. for dependency resolution) would see the Test2 dependency regardless of whether the module is ever loaded.

Pollution concern

Unlike Params::Util::Assert (ADR-003), which shares implementation with the core predicates, Test::Params::Util only uses the predicates -- it has no privileged access to internals. A separate dist with Params::Util as a runtime prerequisite is the natural factoring.

Consequences

• Test::Params::Util depends on Params::Util and Test2::API (or Test::Builder).

• Its release cycle is independent; new Params::Util predicates can ship before matching test functions exist, and vice versa.

• The test module should mirror the Params::Util export list: for each _FOO predicate, provide a corresponding foo_ok (or similar) test function that produces useful diagnostics on failure.

• This ADR does not block any work in the Params-Util distribution itself.