Commit | Line | Data |
b1ddf169 |
1 | package Test::Builder::Module; |
2 | |
705e6672 |
3 | use strict; |
4 | |
b1ddf169 |
5 | use Test::Builder; |
6 | |
7 | require Exporter; |
705e6672 |
8 | our @ISA = qw(Exporter); |
b1ddf169 |
9 | |
3e887aae |
10 | our $VERSION = '0.92'; |
11 | $VERSION = eval $VERSION; ## no critic (BuiltinFunctions::ProhibitStringyEval) |
b1ddf169 |
12 | |
13 | # 5.004's Exporter doesn't have export_to_level. |
14 | my $_export_to_level = sub { |
ccbd73a4 |
15 | my $pkg = shift; |
16 | my $level = shift; |
17 | (undef) = shift; # redundant arg |
18 | my $callpkg = caller($level); |
19 | $pkg->export( $callpkg, @_ ); |
b1ddf169 |
20 | }; |
21 | |
b1ddf169 |
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 | my($class) = shift; |
ccbd73a4 |
86 | |
04955c14 |
87 | # Don't run all this when loading ourself. |
88 | return 1 if $class eq 'Test::Builder::Module'; |
b1ddf169 |
89 | |
90 | my $test = $class->builder; |
91 | |
92 | my $caller = caller; |
93 | |
94 | $test->exported_to($caller); |
95 | |
ccbd73a4 |
96 | $class->import_extra( \@_ ); |
97 | my(@imports) = $class->_strip_imports( \@_ ); |
b1ddf169 |
98 | |
99 | $test->plan(@_); |
100 | |
ccbd73a4 |
101 | $class->$_export_to_level( 1, $class, @imports ); |
b1ddf169 |
102 | } |
103 | |
b1ddf169 |
104 | sub _strip_imports { |
105 | my $class = shift; |
106 | my $list = shift; |
107 | |
108 | my @imports = (); |
109 | my @other = (); |
ccbd73a4 |
110 | my $idx = 0; |
b1ddf169 |
111 | while( $idx <= $#{$list} ) { |
112 | my $item = $list->[$idx]; |
113 | |
114 | if( defined $item and $item eq 'import' ) { |
ccbd73a4 |
115 | push @imports, @{ $list->[ $idx + 1 ] }; |
b1ddf169 |
116 | $idx++; |
117 | } |
118 | else { |
119 | push @other, $item; |
120 | } |
121 | |
122 | $idx++; |
123 | } |
124 | |
125 | @$list = @other; |
126 | |
127 | return @imports; |
128 | } |
129 | |
b1ddf169 |
130 | =head3 import_extra |
131 | |
132 | Your::Module->import_extra(\@import_args); |
133 | |
134 | import_extra() is called by import(). It provides an opportunity for you |
135 | to add behaviors to your module based on its import list. |
136 | |
137 | Any extra arguments which shouldn't be passed on to plan() should be |
138 | stripped off by this method. |
139 | |
140 | See Test::More for an example of its use. |
141 | |
142 | B<NOTE> This mechanism is I<VERY ALPHA AND LIKELY TO CHANGE> as it |
143 | feels like a bit of an ugly hack in its current form. |
144 | |
145 | =cut |
146 | |
ccbd73a4 |
147 | sub import_extra { } |
b1ddf169 |
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 | return Test::Builder->new; |
179 | } |
180 | |
b1ddf169 |
181 | 1; |