1TAP::SimpleOutput(3) User Contributed Perl Documentation TAP::SimpleOutput(3)
2
6 TAP::SimpleOutput - Simple closure-driven TAP generator
7
9 This document describes version 0.009 of TAP::SimpleOutput - released
10 February 14, 2017 as part of TAP-SimpleOutput.
11
13 use TAP::SimpleOutput 'counter';
14 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 # 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
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
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 my ($_ok, $_nok, $_skip, $_plan, $_todo, $_freeform) = counters();
57 $_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 Alternatively, when called in scalar context this function returns a
66 hashref of coderefs:
67 my $tap = counters();
69 $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 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 subtests
84 When "counter()" is passed an integer, the generated closures all
86 indent themselves appropriately to indicate to the test harness / TAP
87 parser that a subtest is being run. (Namely, each statement returned
88 is 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 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 # 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 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 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 This is not something you're likely to need.
127 subtest_header_needed()
129 Returns true if the level of Test::More available will output a subtest
130 header.
131 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 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 e.g.
143 my $out = counters_as_hashref();
145 say subtest_header $out->{freeform} => 'Our subtest name!';
147 # given a hashref, look for the coderef in the 'freeform' slot
149 say subtest_header $out => 'Our subtest name!';
150 # or with the reviled Test::Builder::Tester:
152 test_out subtest_header($out => 'Our subtest name!')
153 if subtest_header_needed;
154 Returns true if the level of Test::More available will output a subtest
156 header.
157 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
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 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 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
176 Subtest formatting can be done by passing an integer "level" parameter
177 to "counter()"; see the function's documentation for details.
178
180 Please see those modules/websites for more information related to this
181 module.
182 · Test::Builder::Tester
184 · TAP::Harness
186
188 Please report any bugs or feature requests on the bugtracker website
189 <https://github.com/RsrchBoy/tap-simpleoutput/issues>
190 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
195 Chris Weyl <cweyl@alumni.drew.edu>
196 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 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 This is free software, licensed under:
215 The GNU Lesser General Public License, Version 2.1, February 1999
217perl v5.28.0 2017-02-14 TAP::SimpleOutput(3)