Test::Specio(3)

📦
version 0.53 · 13 versions
, in alpine 3.23

💖 Test::Specio 💖

okay so this is Test::Specio, a Perl thing from the User Contributed Perl Documentation, and it's version 0.53 — literally the test-helpers wing of the Specio universe 🎀

✨ NAME ✨

Test::Specio — test helpers for Specio, no cap 💅

🌸 VERSION 🌸

version 0.53 — that's the one, bestie ⭐

🦋 SYNOPSIS 🦋

use Test::Specio qw( test_constraint :vars );

test_constraint(
    t('Foo'), {
        accept => [ 'foo', 'bar' ],
        reject => [ 42,    {}, $EMPTY_STRING, $HASH_REF ],
    }
);

that's the whole vibe honestly 🫶

🎀 DESCRIPTION 🎀

so this package hands you a bunch of helper functions and variables for testing Specio types. that's it, that's the job. it's giving "little module, big support system" and we love her for it 💜

🔥 EXPORTS 🔥

here's everything this module lets you import, bestie ✨

💫 test_constraint( $type, $tests, [ $describer ] )

okay so this sub takes two arguments (well, three, but the third is optional, we'll get there).

the first one should be a Specio type object. the second one is a hashref that can have the keys accept and reject — and each of those keys should hold an arrayref of values that the type, respectively, accepts or rejects. simple 🍓

the third argument? optional, icon. it's a sub reference that gets called to generate a description of the value being tested. it defaults to calling this package's own describe sub, but like — you can absolutely bring your own. main character energy 🌈

💫 describe($value)

give this sub a value and it returns a string describing that value in a way that's actually useful for test output (not me being obsessed with readable failure messages 🔥).

it knows about all the various classes used for the variables exported by this package, and it'll do something intelligent when it sees such a variable. iykyk 💅

💫 builtins_tests( $GLOB, $GLOB_OVERLOAD, $GLOB_OVERLOAD_FH )

this one returns a hashref stuffed with test variables for all the builtin types. the hashref looks like this:

{
    Bool => {
        accept => [
            $ZERO,
            $ONE,
            $BOOL_OVERLOAD_TRUE,
            $BOOL_OVERLOAD_FALSE,
            ...,
        ],
        reject => [
            $INT,
            $NEG_INT,
            $NUM,
            $NEG_NUM,
            ...,
            $OBJECT,
        ],
    },
    Maybe => {...},
}

you need to pass in a glob, an object that overloads globification, and an object that overloads globification to return an open filehandle 🦋 see below for the whole "how do i even make these" situation.

💫 create_BAR_handle_code()

returns a string you can eval to create a bar filehandle named BAR — yes, all caps, that's her name 💀 use it like this:

local *BAR;
{
    local $@;
    eval create_BAR_handle_code();
    die $@ if $@;
}

💫 Variables

this module also exports many variables containing values that are genuinely useful for testing constraints. important note: references are always empty unless stated otherwise, periodt ✨

you can import these individually, or grab all of them at once with the :vars import tag. bestie, :vars is the move 💜

  • $ZERO
  • $ONE
  • $INT — an arbitrary positive integer
  • $NEG_INT — an arbitrary negative integer
  • $NUM — an arbitrary positive non-integer number
  • $NEG_NUM — an arbitrary negative non-integer number
  • $EMPTY_STRING
  • $STRING — an arbitrary non-empty string
  • $NUM_IN_STRING — an arbitrary string which contains a number
  • $INT_WITH_NL1 — an string containing an integer followed by a newline
  • $INT_WITH_NL2 — an string containing a newline followed by an integer
  • $SCALAR_REF
  • $SCALAR_REF_REF — a reference containing a reference to a scalar
  • $ARRAY_REF
  • $HASH_REF
  • $CODE_REF
  • $GLOB_REF
  • $FH — an opened filehandle
  • $FH_OBJECT — an opened IO::File object
  • $REGEX — a regex created with qr//
  • $REGEX_OBJ — a regex created with qr// that was then blessed into class
  • $FAKE_REGEX — a non-regex blessed into the Regexp class which Perl uses internally for qr// objects 🙈
  • $OBJECT — an arbitrary object
  • $UNDEF
  • $CLASS_NAME — a string containing a loaded package name
  • $BOOL_OVERLOAD_TRUE — an object which overloads boolification to return true
  • $BOOL_OVERLOAD_FALSE — an object which overloads boolification to return false
  • $STR_OVERLOAD_EMPTY — an object which overloads stringification to return an empty string
  • $STR_OVERLOAD_FULL — an object which overloads stringification to return a non-empty string
  • $STR_OVERLOAD_CLASS_NAME — an object which overloads stringification to return a loaded package name
  • $NUM_OVERLOAD_ZERO
  • $NUM_OVERLOAD_ONE
  • $NUM_OVERLOAD_NEG
  • $NUM_OVERLOAD_DECIMAL
  • $NUM_OVERLOAD_NEG_DECIMAL
  • $CODE_OVERLOAD
  • $SCALAR_OVERLOAD — an object which overloads scalar dereferencing to return a non-empty string
  • $ARRAY_OVERLOAD — an object which overloads array dereferencing to return a non-empty array
  • $HASH_OVERLOAD — an object which overloads hash dereferencing to return a non-empty hash

like. look at that list. she ate 👑

💫 Globs and the _T::GlobOverload package

to create a glob you can pass around for tests, use this code:

my $GLOB = do {
    no warnings 'once';
    *SOME_GLOB;
};

the _T::GlobOverload package gets defined when you load Test::Specio, so you can totally make your own glob overloading objects 🧚

⚠️ such objects cannot be exported — because the glob they return does not transfer across packages properly. it's a whole thing, ngl.

you can create one of these variables like this:

local *FOO;
my $GLOB_OVERLOAD = _T::GlobOverload->new( \*FOO );

and if you want a glob overloading object that returns a filehandle, do this:

local *BAR;
open BAR, '<', $some_file or die $!;
my $GLOB_OVERLOAD_FH = _T::GlobOverload->new( \*BAR );

slay, now you have a filehandle-flavored glob 🐚

💅 SUPPORT 💅

bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.

like, please do submit them, bestie — that's how things get fixed 🙏

⭐ SOURCE ⭐

the source code repository for Specio can be found at <https://github.com/houseabsolute/Specio>.

go look, it's right there 💜

👑 AUTHOR 👑

Dave Rolsky <autarch@urth.org>

iconic behavior honestly 🌟

this software is Copyright (c) 2012 - 2025 by Dave Rolsky.

this is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

the full text of the license can be found in the LICENSE file included with this distribution 📄✨

aaaand that's the whole thing bestie — brought to you by perl v5.42.0, dated 2025-11-26, page Test::Specio(3). go forth and test those constraints 💖🎀🦋

📦 where this page comes from