1TAP::SimpleOutput(3)  User Contributed Perl Documentation TAP::SimpleOutput(3)
2
3
4

NAME

6       TAP::SimpleOutput - Simple closure-driven TAP generator
7

VERSION

9       This document describes version 0.009 of TAP::SimpleOutput - released
10       February 14, 2017 as part of TAP-SimpleOutput.
11

SYNOPSIS

13           use TAP::SimpleOutput 'counter';
14
15           my ($_ok, $_nok, $_skip, $_plan) = counters();
16           say $_ok->('TestClass has a metaclass');
17           say $_ok->('TestClass is a Moose class');
18           say $_ok->('TestClass has an attribute named bar');
19           say $_ok->('TestClass has an attribute named baz');
20           do {
21               my ($_ok, $_nok, $_skip, $_plan) = counters(1);
22               say $_ok->(q{TestClass's attribute baz does TestRole::Two});
23               say $_ok->(q{TestClass's attribute baz has a reader});
24               say $_ok->(q{TestClass's attribute baz option reader correct});
25               say $_plan->();
26           };
27           say $_ok->(q{[subtest] checking TestClass's attribute baz});
28           say $_ok->('TestClass has an attribute named foo');
29
30           # STDOUT looks like:
31           ok 1 - TestClass has a metaclass
32           ok 2 - TestClass is a Moose class
33           ok 3 - TestClass has an attribute named bar
34           ok 4 - TestClass has an attribute named baz
35               ok 1 - TestClass's attribute baz does TestRole::Two
36               ok 2 - TestClass's attribute baz has a reader
37               ok 3 - TestClass's attribute baz option reader correct
38               1..3
39           ok 5 - [subtest] checking TestClass's attribute baz
40           ok 6 - TestClass has an attribute named foo
41

DESCRIPTION

43       We provide one function, counters(), that returns a number of simple
44       closures designed to help output TAP easily and correctly, with a
45       minimum of fuss.
46

FUNCTIONS

48   counters($level)
49       When called in list context, this function returns a number of closures
50       that each generate a different type of TAP output.  It takes an
51       optional $level that determines the indentation level (e.g. for
52       subtests).  These coderefs are all closed over the same counter
53       variable that keeps track of how many test have been run so far; this
54       allows them to always output the correct test number.
55
56           my ($_ok, $_nok, $_skip, $_plan, $_todo, $_freeform) = counters();
57
58           $_ok->('whee');                    # returns "ok 1 - whee"
59           $_nok->('boo');                    # returns "not ok 2 - boo"
60           $_skip->('baz');                   # returns "ok 3 # skip baz"
61           $_todo->($_ok->('bip'), 'daleks'); # returns "ok 4 - bip # TODO daleks"
62           $_plan->();                        # returns "1..4"
63           $_freeform->('yay');               # returns "yay"
64
65       Alternatively, when called in scalar context this function returns a
66       hashref of coderefs:
67
68           my $tap = counters();
69
70           $tap->{ok}->('whee');                          # returns "ok 1 - whee"
71           $tap->{nok}->('boo');                          # returns "not ok 2 - boo"
72           $tap->{skip}->('baz');                         # returns "ok 3 # skip baz"
73           $tap->{todo}->($tap->{ok}->('bip'), 'daleks'); # returns "ok 4 - bip # TODO daleks"
74           $tap->{plan}->();                              # returns "1..4"
75           $tap->{freeform}->('yay');                     # returns "yay"
76
77       Note that calling the $_plan coderef only returns an intelligible
78       response when called after all the output has been generated; this is
79       analogous to using Test::More without a declared plan and
80       done_testing() at the end.  If you need or want to specify the plan
81       prior to running tests, you'll need to do that manually.
82
83       subtests
84
85       When counter() is passed an integer, the generated closures all indent
86       themselves appropriately to indicate to the test harness / TAP parser
87       that a subtest is being run.  (Namely, each statement returned is
88       prefaced with "$level * 4" spaces.)  It's recommended that you use
89       distinct lexical scopes for subtests to allow the usage of the same
90       variable names (why make things difficult?) without clobbering any
91       existing ones and to ensure that the subtest closures are not
92       inadvertently used at an upper level.
93
94           my ($_ok, $_nok) = counters();
95           $_ok->('yay!');
96           $_nok->('boo :(');
97           do {
98               my ($_ok, $_nok, $_skip, $_plan) = counters(1);
99               $_ok->('thing 1 good');
100               $_ok->('thing 2 good');
101               $_ok->('thing 3 good');
102               $_skip->('over there');
103               $_plan->();
104           };
105           $_ok->('subtest passed');
106
107           # returns
108           ok 1 - yay!
109           not ok 2 - boo :(
110               ok 1 - thing 1 good
111               ok 2 - thing 2 good
112               ok 3 - thing 3 good
113               ok 4 # skip over there
114               1..4
115           ok 3 - subtest passed
116
117   counters_as_hashref
118       Same as counters(), except that we return a hashref rather than a list,
119       where the keys are "ok", "nok", "skip", "plan", "todo", and "freeform",
120       and the values are the corresponding coderefs.
121
122   counters_and_levelset($level)
123       Acts as counters(), except returns an additional coderef that can be
124       used to adjust the level of the counters.
125
126       This is not something you're likely to need.
127
128   subtest_header_needed()
129       Returns true if the level of Test::More available will output a subtest
130       header.
131
132       Note that this function will attempt to load Test::More and
133       Perl::Version.  If either of these packages are unavailable, it will
134       "croak" in Carp.
135
136   subtest_header()
137       Given an output coderef (e.g. the 'freeform' from counters() or
138       counters_as_hashref()) and a subtest name (that is, a string), we
139       return a subtest header appropriately indented for the level of
140       Test::More available.
141
142       e.g.
143
144           my $out = counters_as_hashref();
145
146           say subtest_header $out->{freeform} => 'Our subtest name!';
147
148           # given a hashref, look for the coderef in the 'freeform' slot
149           say subtest_header $out => 'Our subtest name!';
150
151           # or with the reviled Test::Builder::Tester:
152           test_out subtest_header($out => 'Our subtest name!')
153               if subtest_header_needed;
154
155       Returns true if the level of Test::More available will output a subtest
156       header.
157
158       Note that this function will attempt to load Test::More and
159       Perl::Version.  If either of these packages are unavailable, it will
160       "croak" in Carp.
161

USAGE WITH Test::Builder::Tester

163       This package was created from code I was using to make it easier to
164       test my test packages with Test::Builder::Tester:
165
166           test_out $_ok->('TestClass has a metaclass');
167           test_out $_ok->('TestClass is a Moose class');
168           test_out $_ok->('TestClass has an attribute named bar');
169           test_out $_ok->('TestClass has an attribute named baz');
170
171       Once I realized I was using the exact same code (perhaps at different
172       points in time) in multiple packages, the decision to break it out
173       became pretty easy to make.
174

SUBTESTS

176       Subtest formatting can be done by passing an integer "level" parameter
177       to counter(); see the function's documentation for details.
178

SEE ALSO

180       Please see those modules/websites for more information related to this
181       module.
182
183       •   Test::Builder::Tester
184
185       •   TAP::Harness
186

BUGS

188       Please report any bugs or feature requests on the bugtracker website
189       <https://github.com/RsrchBoy/tap-simpleoutput/issues>
190
191       When submitting a bug or request, please include a test-file or a patch
192       to an existing test-file that illustrates the bug or desired feature.
193

AUTHOR

195       Chris Weyl <cweyl@alumni.drew.edu>
196
197   I'm a material boy in a material world
198       Please note I do not expect to be gittip'ed or flattr'ed for this work,
199       rather it is simply a very pleasant surprise. I largely create and
200       release works like this because I need them or I find it enjoyable;
201       however, don't let that stop you if you feel like it ;)
202
203       Flattr
204       <https://flattr.com/submit/auto?user_id=RsrchBoy&url=https%3A%2F%2Fgithub.com%2FRsrchBoy%2Ftap-
205       simpleoutput&title=RsrchBoy's%20CPAN%20TAP-
206       SimpleOutput&tags=%22RsrchBoy's%20TAP-
207       SimpleOutput%20in%20the%20CPAN%22>, Gratipay
208       <https://gratipay.com/RsrchBoy/>, or indulge my Amazon Wishlist
209       <http://bit.ly/rsrchboys-wishlist>...  If and *only* if you so desire.
210
212       This software is Copyright (c) 2012 by Chris Weyl.
213
214       This is free software, licensed under:
215
216         The GNU Lesser General Public License, Version 2.1, February 1999
217
218
219
220perl v5.36.0                      2023-01-20              TAP::SimpleOutput(3)
Impressum