NAME

Test::Returns - Verify that a method's output agrees with its specification

SYNOPSIS

use Test::More;
use Test::Returns;

returns_ok(42, { type => 'integer' }, 'Returns valid integer');
returns_ok([], { type => 'arrayref' }, 'Returns valid arrayref');
returns_not_ok("bad", { type => 'arrayref' }, 'Fails (expected arrayref)');

VERSION

Version 0.03

DESCRIPTION

Exports the function returns_ok, which asserts that a value satisfies a schema as defined in Params::Validate::Strict. Integrates with Test::Builder for use alongside Test::Most and friends.

METHODS

returns_is($value, $schema, $test_name)

Passes if $value satisfies $schema using Return::Set. Fails otherwise.

$schema is passed directly to Return::Set and on to Params::Validate::Strict. As a convenience, type => 'array' is accepted as a synonym for type => 'arrayref': because a bare Perl array cannot be stored as a hash value, Params::Validate::Strict only defines the arrayref type, but callers may capture a list-returning function as an arrayref and validate it with type => 'array'.

Schema keys prefixed with _ (such as _error_return and _error_handling as emitted by App::Test::Generator) are passed through unchanged; Params::Validate::Strict ignores unknown keys in a rule hash.

returns_isnt($value, $schema, $test_name)

Opposite of returns_is: passes if $value does not satisfy $schema.

Accepts type => 'array' as a synonym for type => 'arrayref', for the same reasons as returns_is.

returns_ok($value, $schema, $test_name)

Alias for returns_is. Provided for naming symmetry and clarity.

returns_not_ok

Synonym of returns_isnt

AUTHOR

Nigel Horne <njh at nigelhorne.com>

SEE ALSO

Test::Builder, Return::Set, Params::Validate::Strict

SUPPORT

This module is provided as-is without any warranty.

LICENCE AND COPYRIGHT

Copyright 2025-2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.