1Test2::Manual::Tooling:U:sTeerstCionngt(r3i)buted Perl DToecsutm2e:n:tMaatniuoanl::Tooling::Testing(3)
2
3
4

NAME

6       Test2::Manual::Tooling::Testing - Tutorial on how to test your testing
7       tools.
8

DESCRIPTION

10       Testing your test tools used to be a complex and difficult prospect.
11       The old tools such as Test::Tester and Test::Builder::Tester were
12       limited, and fragile. Test2 on the other hand was designed from the
13       very start to be easily tested! This tutorial shows you how.
14

THE HOLY GRAIL OF TESTING YOUR TOOLS

16       The key to making Test2 easily testable (specially when compared to
17       Test::Builder) is the "intercept" function.
18
19           use Test2::API qw/intercept/;
20
21           my $events = intercept {
22               ok(1, "pass");
23               ok(0, "fail");
24
25               diag("A diag");
26           };
27
28       The intercept function lets you use any test tools you want inside a
29       codeblock.  No events or contexts generated within the intercept
30       codeblock will have any effect on the outside testing state. The
31       "intercept" function completely isolates the tools called within.
32
33       Note: Plugins and things that effect global API state may not be fully
34       isolated. "intercept" is intended specifically for event isolation.
35
36       The "intercept" function will return an arrayref containing all the
37       events that were generated within the codeblock. You can now make any
38       assertions you want about the events you expected your tools to
39       generate.
40
41           [
42               bless({...}, 'Test2::Event::Ok'),   # pass
43               bless({...}, 'Test2::Event::Ok'),   # fail
44               bless({...}, 'Test2::Event::Diag'), # Failure diagnostics (not always a second event)
45               bless({...}, 'Test2::Event::Diag'), # custom 'A diag' message
46           ]
47
48       Most test tools eventually produce one or more events. To effectively
49       verify the events you get from intercept you really should read up on
50       how events work Test2::Manual::Anatomy::Event. Once you know about
51       events you can move on to the next section which points you at some
52       helpers.
53

ADDITIONAL HELPERS

55   Test2::Tools::Tester
56       This is the most recent set of tools to help you test your events. To
57       really understand these you should familiarize yourself with
58       Test2::Manual::Anatomy::Event. If you are going to be writing anything
59       more than the most simple of tools you should know how events work.
60
61       The Test2::Tools::Tester documentation is a good place for further
62       reading.
63
64   Test2::Tools::HarnessTester
65       The Test2::Tools::HarnessTester can export the "summarize_events()"
66       tool.  This tool lets you run your event arrayref through
67       Test2::Harness so that you can get a pass/fail summary.
68
69           my $summary = summarize_events($events);
70
71       The summary looks like this:
72
73           {
74               plan       => $plan_facet,         # the plan event facet
75               pass       => $bool,               # true if the events result in a pass
76               fail       => $bool,               # true if the events result in a fail
77               errors     => $error_count,        # Number of error facets seen
78               failures   => $failure_count,      # Number of failing assertions seen
79               assertions => $assertion_count,    # Total number of assertions seen
80           }
81
82   Test2::Tools::Compare
83       DEPRECATED These tools were written before the switch to faceted
84       events.  These will still work, but are no longer the recommended way
85       to test your tools.
86
87       The Test2::Tools::Compare library exports a handful of extras to help
88       test events.
89
90       event $TYPE => ...
91           Use in an array check against $events to check for a specific type
92           of event with the properties you specify.
93
94       fail_events $TYPE => ...
95           Use when you expect a failing assertion of $TYPE. This will
96           automatically check that the next event following it is a
97           diagnostics message with the default failure text.
98
99           Note: This is outdated as a single event may now possess both the
100           failing assertion AND the failing text, such events will fail this
101           test.
102

SEE ALSO

104       Test2::Manual - Primary index of the manual.
105

SOURCE

107       The source code repository for Test2-Manual can be found at
108       https://github.com/Test-More/Test2-Suite/.
109

MAINTAINERS

111       Chad Granum <exodist@cpan.org>
112

AUTHORS

114       Chad Granum <exodist@cpan.org>
115

117       Copyright 2018 Chad Granum <exodist@cpan.org>.
118
119       This program is free software; you can redistribute it and/or modify it
120       under the same terms as Perl itself.
121
122       See http://dev.perl.org/licenses/
123
124
125
126perl v5.36.0                      2022-07-22Test2::Manual::Tooling::Testing(3)
Impressum