1Test::Specio(3)       User Contributed Perl Documentation      Test::Specio(3)
2
3
4

NAME

6       Test::Specio - Test helpers for Specio
7

VERSION

9       version 0.48
10

SYNOPSIS

12         use Test::Specio qw( test_constraint :vars );
13
14         test_constraint(
15             t('Foo'), {
16                 accept => [ 'foo', 'bar' ],
17                 reject => [ 42,    {}, $EMPTY_STRING, $HASH_REF ],
18             }
19         );
20

DESCRIPTION

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

EXPORTS

26       This module provides the following exports:
27
28   test_constraint( $type, $tests, [ $describer ] )
29       This subroutine accepts two arguments. The first should be a Specio
30       type object. The second is hashref which can contain the keys "accept"
31       and "reject". Each key should contain an arrayref of values which the
32       type accepts or rejects.
33
34       The third argument is optional. This is a sub reference which will be
35       called to generate a description of the value being tested. This
36       defaults to calling this package's "describe" sub, but you can provide
37       your own.
38
39   describe($value)
40       Given a value, this subroutine returns a string describing that value
41       in a useful way for test output. It know about the various classes used
42       for the variables exported by this package and will do something
43       intelligent when such a variable.
44
45   builtins_tests( $GLOB, $GLOB_OVERLOAD, $GLOB_OVERLOAD_FH )
46       This subroutine returns a hashref containing test variables for all
47       builtin types. The hashref has a form like this:
48
49         {
50             Bool => {
51                 accept => [
52                     $ZERO,
53                     $ONE,
54                     $BOOL_OVERLOAD_TRUE,
55                     $BOOL_OVERLOAD_FALSE,
56                     ...,
57                 ],
58                 reject => [
59                     $INT,
60                     $NEG_INT,
61                     $NUM,
62                     $NEG_NUM,
63                     ...,
64                     $OBJECT,
65                 ],
66             },
67             Maybe => {...},
68         }
69
70       You need to pass in a glob, an object which overloads globification,
71       and an object which overloads globification to return an open
72       filehandle. See below for more details on how to create these things.
73
74   Variables
75       This module also exports many variables containing values which are
76       useful for testing constraints. Note that references are always empty
77       unless stated otherwise. You can import these variables individually or
78       import all of them with the ":vars" import tag.
79
80       •   $ZERO
81
82       •   $ONE
83
84       •   $INT
85
86           An arbitrary positive integer.
87
88       •   $NEG_INT
89
90           An arbitrary negative integer.
91
92       •   $NUM
93
94           An arbitrary positive non-integer number.
95
96       •   $NEG_NUM
97
98           An arbitrary negative non-integer number.
99
100       •   $EMPTY_STRING
101
102       •   $STRING
103
104           An arbitrary non-empty string.
105
106       •   $NUM_IN_STRING
107
108           An arbitrary string which contains a number.
109
110       •   $INT_WITH_NL1
111
112           An string containing an integer followed by a newline.
113
114       •   $INT_WITH_NL2
115
116           An string containing a newline followed by an integer.
117
118       •   $SCALAR_REF
119
120       •   $SCALAR_REF_REF
121
122           A reference containing a reference to a scalar.
123
124       •   $ARRAY_REF
125
126       •   $HASH_REF
127
128       •   $CODE_REF
129
130       •   $GLOB_REF
131
132       •   $FH
133
134           An opened filehandle.
135
136       •   $FH_OBJECT
137
138           An opened IO::File object.
139
140       •   $REGEX
141
142           A regex created with "qr//".
143
144       •   $REGEX_OBJ
145
146           A regex created with "qr//" that was then blessed into class.
147
148       •   $FAKE_REGEX
149
150           A non-regex blessed into the "Regexp" class which Perl uses
151           internally for "qr//" objects.
152
153       •   $OBJECT
154
155           An arbitrary object.
156
157       •   $UNDEF
158
159       •   $CLASS_NAME
160
161           A string containing a loaded package name.
162
163       •   $BOOL_OVERLOAD_TRUE
164
165           An object which overloads boolification to return true.
166
167       •   $BOOL_OVERLOAD_FALSE
168
169           An object which overloads boolification to return false.
170
171       •   $STR_OVERLOAD_EMPTY
172
173           An object which overloads stringification to return an empty
174           string.
175
176       •   $STR_OVERLOAD_FULL
177
178           An object which overloads stringification to return a non-empty
179           string.
180
181       •   $STR_OVERLOAD_CLASS_NAME
182
183           An object which overloads stringification to return a loaded
184           package name.
185
186       •   $NUM_OVERLOAD_ZERO
187
188       •   $NUM_OVERLOAD_ONE
189
190       •   $NUM_OVERLOAD_NEG
191
192       •   $NUM_OVERLOAD_DECIMAL
193
194       •   $NUM_OVERLOAD_NEG_DECIMAL
195
196       •   $CODE_OVERLOAD
197
198       •   $SCALAR_OVERLOAD
199
200           An object which overloads scalar dereferencing to return a non-
201           empty string.
202
203       •   $ARRAY_OVERLOAD
204
205           An object which overloads array dereferencing to return a non-empty
206           array.
207
208       •   $HASH_OVERLOAD
209
210           An object which overloads hash dereferencing to return a non-empty
211           hash.
212
213   Globs and the _T::GlobOverload package
214       To create a glob you can pass around for tests, use this code:
215
216         my $GLOB = do {
217             no warnings 'once';
218             *SOME_GLOB;
219         };
220
221       The "_T::GlobOverload" package is defined when you load "Test::Specio"
222       so you can create your own glob overloading objects. Such objects
223       cannot be exported because the glob they return does not transfer
224       across packages properly.
225
226       You can create such a variable like this:
227
228         local *FOO;
229         my $GLOB_OVERLOAD = _T::GlobOverload->new( \*FOO );
230
231       If you want to create a glob overloading object that returns a
232       filehandle, do this:
233
234         local *BAR;
235         open BAR, '<', $^X or die "Could not open $^X for the test";
236         my $GLOB_OVERLOAD_FH = _T::GlobOverload->new( \*BAR );
237

SUPPORT

239       Bugs may be submitted at
240       <https://github.com/houseabsolute/Specio/issues>.
241

SOURCE

243       The source code repository for Specio can be found at
244       <https://github.com/houseabsolute/Specio>.
245

AUTHOR

247       Dave Rolsky <autarch@urth.org>
248

250       This software is Copyright (c) 2012 - 2022 by Dave Rolsky.
251
252       This is free software, licensed under:
253
254         The Artistic License 2.0 (GPL Compatible)
255
256       The full text of the license can be found in the LICENSE file included
257       with this distribution.
258
259
260
261perl v5.36.0                      2023-01-20                   Test::Specio(3)
Impressum