Commit | Line | Data |
---|---|---|
6281b77d PE |
1 | package Test2::Manual::Tooling::Testing; |
2 | use strict; | |
3 | use warnings; | |
4 | ||
dde38cd6 | 5 | our $VERSION = '0.000159'; |
6281b77d PE |
6 | |
7 | 1; | |
8 | ||
9 | __END__ | |
10 | ||
11 | =head1 NAME | |
12 | ||
13 | Test2::Manual::Tooling::Testing - Tutorial on how to test your testing tools. | |
14 | ||
15 | =head1 DESCRIPTION | |
16 | ||
17 | Testing your test tools used to be a complex and difficult prospect. The old | |
18 | tools such as L<Test::Tester> and L<Test::Builder::Tester> were limited, and | |
19 | fragile. Test2 on the other hand was designed from the very start to be easily | |
20 | tested! This tutorial shows you how. | |
21 | ||
22 | =head1 THE HOLY GRAIL OF TESTING YOUR TOOLS | |
23 | ||
24 | The key to making Test2 easily testable (specially when compared to | |
25 | Test::Builder) is the C<intercept> function. | |
26 | ||
27 | use Test2::API qw/intercept/; | |
28 | ||
29 | my $events = intercept { | |
30 | ok(1, "pass"); | |
31 | ok(0, "fail"); | |
32 | ||
33 | diag("A diag"); | |
34 | }; | |
35 | ||
36 | The intercept function lets you use any test tools you want inside a codeblock. | |
37 | No events or contexts generated within the intercept codeblock will have any | |
38 | effect on the outside testing state. The C<intercept> function completely | |
39 | isolates the tools called within. | |
40 | ||
41 | B<Note:> Plugins and things that effect global API state may not be fully | |
42 | isolated. C<intercept> is intended specifically for event isolation. | |
43 | ||
44 | The C<intercept> function will return an arrayref containing all the events | |
45 | that were generated within the codeblock. You can now make any assertions you | |
46 | want about the events you expected your tools to generate. | |
47 | ||
48 | [ | |
49 | bless({...}, 'Test2::Event::Ok'), # pass | |
50 | bless({...}, 'Test2::Event::Ok'), # fail | |
51 | bless({...}, 'Test2::Event::Diag'), # Failure diagnostics (not always a second event) | |
52 | bless({...}, 'Test2::Event::Diag'), # custom 'A diag' message | |
53 | ] | |
54 | ||
55 | Most test tools eventually produce one or more events. To effectively verify | |
56 | the events you get from intercept you really should read up on how events work | |
57 | L<Test2::Manual::Anatomy::Event>. Once you know about events you can move on to | |
58 | the next section which points you at some helpers. | |
59 | ||
60 | =head1 ADDITIONAL HELPERS | |
61 | ||
62 | =head2 Test2::Tools::Tester | |
63 | ||
64 | This is the most recent set of tools to help you test your events. To really | |
65 | understand these you should familiarize yourself with | |
66 | L<Test2::Manual::Anatomy::Event>. If you are going to be writing anything more | |
67 | than the most simple of tools you should know how events work. | |
68 | ||
69 | The L<Test2::Tools::Tester> documentation is a good place for further reading. | |
70 | ||
71 | =head2 Test2::Tools::HarnessTester | |
72 | ||
73 | The L<Test2::Tools::HarnessTester> can export the C<summarize_events()> tool. | |
74 | This tool lets you run your event arrayref through L<Test2::Harness> so that you | |
75 | can get a pass/fail summary. | |
76 | ||
77 | my $summary = summarize_events($events); | |
78 | ||
79 | The summary looks like this: | |
80 | ||
81 | { | |
82 | plan => $plan_facet, # the plan event facet | |
83 | pass => $bool, # true if the events result in a pass | |
84 | fail => $bool, # true if the events result in a fail | |
85 | errors => $error_count, # Number of error facets seen | |
86 | failures => $failure_count, # Number of failing assertions seen | |
87 | assertions => $assertion_count, # Total number of assertions seen | |
88 | } | |
89 | ||
90 | =head2 Test2::Tools::Compare | |
91 | ||
92 | B<DEPRECATED> These tools were written before the switch to faceted events. | |
93 | These will still work, but are no longer the recommended way to test your | |
94 | tools. | |
95 | ||
96 | The L<Test2::Tools::Compare> library exports a handful of extras to help test | |
97 | events. | |
98 | ||
99 | =over 4 | |
100 | ||
101 | =item event $TYPE => ... | |
102 | ||
103 | Use in an array check against $events to check for a specific type of event | |
104 | with the properties you specify. | |
105 | ||
106 | =item fail_events $TYPE => ... | |
107 | ||
108 | Use when you expect a failing assertion of $TYPE. This will automatically check | |
109 | that the next event following it is a diagnostics message with the default | |
110 | failure text. | |
111 | ||
112 | B<Note:> This is outdated as a single event may now possess both the failing | |
113 | assertion AND the failing text, such events will fail this test. | |
114 | ||
115 | =back | |
116 | ||
117 | =head1 SEE ALSO | |
118 | ||
119 | L<Test2::Manual> - Primary index of the manual. | |
120 | ||
121 | =head1 SOURCE | |
122 | ||
123 | The source code repository for Test2-Manual can be found at | |
124 | F<https://github.com/Test-More/Test2-Suite/>. | |
125 | ||
126 | =head1 MAINTAINERS | |
127 | ||
128 | =over 4 | |
129 | ||
130 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | |
131 | ||
132 | =back | |
133 | ||
134 | =head1 AUTHORS | |
135 | ||
136 | =over 4 | |
137 | ||
138 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | |
139 | ||
140 | =back | |
141 | ||
142 | =head1 COPYRIGHT | |
143 | ||
144 | Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>. | |
145 | ||
146 | This program is free software; you can redistribute it and/or | |
147 | modify it under the same terms as Perl itself. | |
148 | ||
149 | See F<http://dev.perl.org/licenses/> | |
150 | ||
151 | =cut |