File Coverage

support/Test/Builder/Module.pm
Criterion Covered Total %
statement 29 32 90.6
branch 1 2 50.0
condition 1 3 33.3
subroutine 6 6 100.0
pod 2 2 100.0
total 39 45 86.7


line stmt bran cond sub pod time code
1             package Test::Builder::Module;
2              
3 10     10   1215 use Test::Builder;
  10         120  
  10         185  
4              
5             require Exporter;
6             @ISA = qw(Exporter);
7              
8             $VERSION = '0.03';
9              
10 10     10   261 use strict;
  10         88  
  10         171  
11              
12             # 5.004's Exporter doesn't have export_to_level.
13             my $_export_to_level = sub {
14                   my $pkg = shift;
15                   my $level = shift;
16                   (undef) = shift; # redundant arg
17                   my $callpkg = caller($level);
18                   $pkg->export($callpkg, @_);
19             };
20              
21              
22             =head1 NAME
23            
24             Test::Builder::Module - Base class for test modules
25            
26             =head1 SYNOPSIS
27            
28             # Emulates Test::Simple
29             package Your::Module;
30            
31             my $CLASS = __PACKAGE__;
32            
33             use base 'Test::Builder::Module';
34             @EXPORT = qw(ok);
35            
36             sub ok ($;$) {
37             my $tb = $CLASS->builder;
38             return $tb->ok(@_);
39             }
40            
41             1;
42            
43            
44             =head1 DESCRIPTION
45            
46             This is a superclass for Test::Builder-based modules. It provides a
47             handful of common functionality and a method of getting at the underlying
48             Test::Builder object.
49            
50            
51             =head2 Importing
52            
53             Test::Builder::Module is a subclass of Exporter which means your
54             module is also a subclass of Exporter. @EXPORT, @EXPORT_OK, etc...
55             all act normally.
56            
57             A few methods are provided to do the C<use Your::Module tests => 23> part
58             for you.
59            
60             =head3 import
61            
62             Test::Builder::Module provides an import() method which acts in the
63             same basic way as Test::More's, setting the plan and controling
64             exporting of functions and variables. This allows your module to set
65             the plan independent of Test::More.
66            
67             All arguments passed to import() are passed onto
68             C<< Your::Module->builder->plan() >> with the exception of
69             C<import =>[qw(things to import)]>.
70            
71             use Your::Module import => [qw(this that)], tests => 23;
72            
73             says to import the functions this() and that() as well as set the plan
74             to be 23 tests.
75            
76             import() also sets the exported_to() attribute of your builder to be
77             the caller of the import() function.
78            
79             Additional behaviors can be added to your import() method by overriding
80             import_extra().
81            
82             =cut
83              
84             sub import {
85 20     20   216     my($class) = shift;
86              
87 20         1997     my $test = $class->builder;
88              
89 20         228     my $caller = caller;
90              
91 20         235     $test->exported_to($caller);
92              
93 20         293     $class->import_extra(\@_);
94 20         295     my(@imports) = $class->_strip_imports(\@_);
95              
96 20         337     $test->plan(@_);
97              
98 20         3241     $class->$_export_to_level(1, $class, @imports);
99             }
100              
101              
102             sub _strip_imports {
103 20     20   191     my $class = shift;
104 20         173     my $list = shift;
105              
106 20         300     my @imports = ();
107 20         188     my @other = ();
108 20         173     my $idx = 0;
109 20         234     while( $idx <= $#{$list} ) {
  38         445  
110 18         178         my $item = $list->[$idx];
111              
112 18 50 33     241         if( defined $item and $item eq 'import' ) {
113 0         0             push @imports, @{$list->[$idx+1]};
  0         0  
114 0         0             $idx++;
115                     }
116                     else {
117 18         1222             push @other, $item;
118                     }
119              
120 18         172         $idx++;
121                 }
122              
123 20         2860     @$list = @other;
124              
125 20         228     return @imports;
126             }
127              
128              
129             =head3 import_extra
130            
131             Your::Module->import_extra(\@import_args);
132            
133             import_extra() is called by import(). It provides an opportunity for you
134             to add behaviors to your module based on its import list.
135            
136             Any extra arguments which shouldn't be passed on to plan() should be
137             stripped off by this method.
138            
139             See Test::More for an example of its use.
140            
141             B<NOTE> This mechanism is I<VERY ALPHA AND LIKELY TO CHANGE> as it
142             feels like a bit of an ugly hack in its current form.
143            
144             =cut
145              
146 10     10 1 92 sub import_extra {}
147              
148              
149             =head2 Builder
150            
151             Test::Builder::Module provides some methods of getting at the underlying
152             Test::Builder object.
153            
154             =head3 builder
155            
156             my $builder = Your::Class->builder;
157            
158             This method returns the Test::Builder object associated with Your::Class.
159             It is not a constructor so you can call it as often as you like.
160            
161             This is the preferred way to get the Test::Builder object. You should
162             I<not> get it via C<< Test::Builder->new >> as was previously
163             recommended.
164            
165             The object returned by builder() may change at runtime so you should
166             call builder() inside each function rather than store it in a global.
167            
168             sub ok {
169             my $builder = Your::Class->builder;
170            
171             return $builder->ok(@_);
172             }
173            
174            
175             =cut
176              
177             sub builder {
178 14940     14940 1 213527     return Test::Builder->new;
179             }
180              
181              
182             1;
183