Test::Specio(3) User Contributed Perl Documentation Test::Specio(3)

# [SYNOPSIS](#SYNOPSIS)

```
  use Test::Specio qw( test_constraint :vars );
  test_constraint(
      t('Foo'), {
          accept => [ 'foo', 'bar' ],
          reject => [ 42,    {}, $EMPTY_STRING, $HASH_REF ],
      }
  );
```

# [DESCRIPTION](#DESCRIPTION)

This package provides some helper functions and variables for testing Specio types.

# [EXPORTS](#EXPORTS)

This module provides the following exports:

## [test\_constraint( $type, $tests, \[ $describer \] )](#test_constraint%28_$type,_$tests,___$describer___%29)

This subroutine accepts two arguments. The first should be a Specio type object. The second is hashref which can contain the keys "accept" and "reject". Each key should contain an arrayref of values which the type accepts or rejects.

The third argument is optional. This is a sub reference which will be called to generate a description of the value being tested. This defaults to calling this package's "describe" sub, but you can provide your own.

## [describe($value)](#describe%28$value%29)

Given a value, this subroutine returns a string describing that value in a useful way for test output. It know about the various classes used for the variables exported by this package and will do something intelligent when such a variable.

## [builtins\_tests( $GLOB, $GLOB\_OVERLOAD, $GLOB\_OVERLOAD\_FH )](#builtins_tests%28_$GLOB,_$GLOB_OVERLOAD,_$GLOB_OVERLOAD_FH_%29)

This subroutine returns a hashref containing test variables for all builtin types. The hashref has a form 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 which overloads globification, and an object which overloads globification to return an open filehandle. See below for more details on how to create these things.

## **create\_BAR\_handle\_code()**

Returns a string you can "eval" to create a bar filehandle named "BAR". This should be used like this:

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

## [Variables](#Variables)

This module also exports many variables containing values which are useful for testing constraints. Note that references are always empty unless stated otherwise. You can import these variables individually or import all of them with the ":vars" import tag.

- $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.

## [Globs and the \_T::GlobOverload package](#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 is defined when you load "Test::Specio" so you can create your own glob overloading objects. Such objects cannot be exported because the glob they return does not transfer across packages properly.

You can create such a variable like this:

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

If you want to create 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 );
```

2026-07-17 perl v5.44.0

---

Document: Test::Specio(3pm) from perl-specio 0.53-r5 (Chainguard OS)
Source: https://github.com/houseabsolute/Specio