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

NAME

6       Test2::Manual::Tooling::Subtest - How to implement a tool that makes
7       use of subtests.
8

DESCRIPTION

10       Subtests are a nice way of making related events visually, and
11       architecturally distinct.
12

WHICH TYPE OF SUBTEST DO I NEED?

14       There are 2 types of subtest. The first type is subtests with user-
15       supplied coderefs, such as the "subtest()" function itself. The second
16       type is subtest that do not have any user supplied coderefs.
17
18       So which type do you need? The answer to that is simple, if you are
19       going to let the user define the subtest with their own codeblock, you
20       have the first type, otherwise you have the second.
21
22       In either case, you will still need use the same API function:
23       "Test2::API::run_subtest".
24
25   SUBTEST WITH USER SUPPLIED CODEREF
26       This example will emulate the "subtest" function.
27
28           use Test2::API qw/context run_subtest/;
29
30           sub my_subtest {
31               my ($name, $code) = @_;
32
33               # Like any other tool, you need to acquire a context, if you do not then
34               # things will not report the correct file and line number.
35               my $ctx = context();
36
37               my $bool = run_subtest($name, $code);
38
39               $ctx->release;
40
41               return $bool;
42           }
43
44       This looks incredibly simple... and it is. "run_subtest()" does all the
45       hard work for you. This will issue an Test2::Event::Subtest event with
46       the results of the subtest. The subtest event itself will report to the
47       proper file and line number due to the context you acquired (even
48       though it does not look like you used the context.
49
50       "run_subtest()" can take additional arguments:
51
52           run_subtest($name, $code, \%params, @args);
53
54       @args
55           This allows you to pass arguments into the codeblock that gets run.
56
57       \%params
58           This is a hashref of parameters. Currently there are 3 possible
59           parameters:
60
61           buffered => $bool
62               This will turn the subtest into the new style buffered subtest.
63               This type of subtest is recommended, but not default.
64
65           inherit_trace => $bool
66               This is used for tool-side coderefs.
67
68           no_fork => $bool
69               react to forking/threading inside the subtest itself. In
70               general you are unlikely to need/want this parameter.
71
72   SUBTEST WITH TOOL-SIDE CODEREF
73       This is particularly useful if you want to turn a tool that wraps other
74       tools into a subtest. For this we will be using the tool we created in
75       Test2::Manual::Tooling::Nesting.
76
77           use Test2::API qw/context run_subtest/;
78
79           sub check_class {
80               my $class = shift;
81
82               my $ctx = context();
83
84               my $code = sub {
85                   my $obj = $class->new;
86                   is($obj->foo, 'foo', "got foo");
87                   is($obj->bar, 'bar', "got bar");
88               };
89
90               my $bool = run_subtest($class, $code, {buffered => 1, inherit_trace => 1});
91
92               $ctx->release;
93
94               return $bool;
95           }
96
97       The "run_subtest()" function does all the heavy lifting for us. All we
98       need to do is give the function a name, a coderef to run, and the
99       "inherit_trace => 1" parameter. The "buffered => 1" parameter is
100       optional, but recommended.
101
102       The "inherit_trace" parameter tells the subtest tool that the contexts
103       acquired inside the nested tools should use the same trace as the
104       subtest itself. For user-supplied codeblocks you do not use
105       inherit_trace because you want errors to report to the user-supplied
106       file+line.
107

SEE ALSO

109       Test2::Manual - Primary index of the manual.
110

SOURCE

112       The source code repository for Test2-Manual can be found at
113       https://github.com/Test-More/Test2-Suite/.
114

MAINTAINERS

116       Chad Granum <exodist@cpan.org>
117

AUTHORS

119       Chad Granum <exodist@cpan.org>
120

122       Copyright 2018 Chad Granum <exodist@cpan.org>.
123
124       This program is free software; you can redistribute it and/or modify it
125       under the same terms as Perl itself.
126
127       See http://dev.perl.org/licenses/
128
129
130
131perl v5.32.0                      2020-12-16Test2::Manual::Tooling::Subtest(3)
Impressum