File Coverage

blib/lib/Test/Builder/Module.pm
Criterion Covered Total %
statement 34 34 100.0
branch 6 6 100.0
condition 2 3 66.6
subroutine 6 6 100.0
pod 2 2 100.0
total 50 51 98.0


line stmt bran cond sub pod time code
1             package Test::Builder::Module;
2              
3 135     135   1513 use strict;
  135         286  
  135         4113  
4              
5 135     135   63555 use Test::Builder;
  135         405  
  135         48627  
6              
7             require Exporter;
8             our @ISA = qw(Exporter);
9              
10             our $VERSION = '1.302182';
11              
12              
13             =head1 NAME
14              
15             Test::Builder::Module - Base class for test modules
16              
17             =head1 SYNOPSIS
18              
19             # Emulates Test::Simple
20             package Your::Module;
21              
22             my $CLASS = __PACKAGE__;
23              
24             use parent 'Test::Builder::Module';
25             @EXPORT = qw(ok);
26              
27             sub ok ($;$) {
28             my $tb = $CLASS->builder;
29             return $tb->ok(@_);
30             }
31            
32             1;
33              
34              
35             =head1 DESCRIPTION
36              
37             This is a superclass for L<Test::Builder>-based modules. It provides a
38             handful of common functionality and a method of getting at the underlying
39             L<Test::Builder> object.
40              
41              
42             =head2 Importing
43              
44             Test::Builder::Module is a subclass of L<Exporter> which means your
45             module is also a subclass of Exporter. @EXPORT, @EXPORT_OK, etc...
46             all act normally.
47              
48             A few methods are provided to do the C<< use Your::Module tests => 23 >> part
49             for you.
50              
51             =head3 import
52              
53             Test::Builder::Module provides an C<import()> method which acts in the
54             same basic way as L<Test::More>'s, setting the plan and controlling
55             exporting of functions and variables. This allows your module to set
56             the plan independent of L<Test::More>.
57              
58             All arguments passed to C<import()> are passed onto
59             C<< Your::Module->builder->plan() >> with the exception of
60             C<< import =>[qw(things to import)] >>.
61              
62             use Your::Module import => [qw(this that)], tests => 23;
63              
64             says to import the functions C<this()> and C<that()> as well as set the plan
65             to be 23 tests.
66              
67             C<import()> also sets the C<exported_to()> attribute of your builder to be
68             the caller of the C<import()> function.
69              
70             Additional behaviors can be added to your C<import()> method by overriding
71             C<import_extra()>.
72              
73             =cut
74              
75             sub import {
76 255     255   2400 my($class) = shift;
77              
78 255 100       1008 Test2::API::test2_load() unless Test2::API::test2_in_preload();
79              
80             # Don't run all this when loading ourself.
81 255 100       45355 return 1 if $class eq 'Test::Builder::Module';
82              
83 117         652 my $test = $class->builder;
84              
85 117         368 my $caller = caller;
86              
87 117         572 $test->exported_to($caller);
88              
89 117         544 $class->import_extra( \@_ );
90 117         625 my(@imports) = $class->_strip_imports( \@_ );
91              
92 117         642 $test->plan(@_);
93              
94 112         262 local $Exporter::ExportLevel = $Exporter::ExportLevel + 1;
95 112         111282 $class->Exporter::import(@imports);
96             }
97              
98             sub _strip_imports {
99 117     117   283 my $class = shift;
100 117         237 my $list = shift;
101              
102 117         245 my @imports = ();
103 117         250 my @other = ();
104 117         226 my $idx = 0;
105 117         231 while( $idx <= $#{$list} ) {
  335         890  
106 218         464 my $item = $list->[$idx];
107              
108 218 100 66     1003 if( defined $item and $item eq 'import' ) {
109 110         238 push @imports, @{ $list->[ $idx + 1 ] };
  110         802  
110 110         269 $idx++;
111             }
112             else {
113 108         251 push @other, $item;
114             }
115              
116 218         377 $idx++;
117             }
118              
119 117         448 @$list = @other;
120              
121 117         693 return @imports;
122             }
123              
124             =head3 import_extra
125              
126             Your::Module->import_extra(\@import_args);
127              
128             C<import_extra()> is called by C<import()>. It provides an opportunity for you
129             to add behaviors to your module based on its import list.
130              
131             Any extra arguments which shouldn't be passed on to C<plan()> should be
132             stripped off by this method.
133              
134             See L<Test::More> for an example of its use.
135              
136             B<NOTE> This mechanism is I<VERY ALPHA AND LIKELY TO CHANGE> as it
137             feels like a bit of an ugly hack in its current form.
138              
139             =cut
140              
141       7 1   sub import_extra { }
142              
143             =head2 Builder
144              
145             Test::Builder::Module provides some methods of getting at the underlying
146             Test::Builder object.
147              
148             =head3 builder
149              
150             my $builder = Your::Class->builder;
151              
152             This method returns the L<Test::Builder> object associated with Your::Class.
153             It is not a constructor so you can call it as often as you like.
154              
155             This is the preferred way to get the L<Test::Builder> object. You should
156             I<not> get it via C<< Test::Builder->new >> as was previously
157             recommended.
158              
159             The object returned by C<builder()> may change at runtime so you should
160             call C<builder()> inside each function rather than store it in a global.
161              
162             sub ok {
163             my $builder = Your::Class->builder;
164              
165             return $builder->ok(@_);
166             }
167              
168              
169             =cut
170              
171             sub builder {
172 1617     1617 1 5533 return Test::Builder->new;
173             }
174              
175             =head1 SEE ALSO
176              
177             L<< Test2::Manual::Tooling::TestBuilder >> describes the improved
178             options for writing testing modules provided by L<< Test2 >>.
179              
180             =cut
181              
182             1;