Commit | Line | Data |
b1ddf169 |
1 | package Test::Builder::Module; |
2 | |
3 | use Test::Builder; |
4 | |
5 | require Exporter; |
6 | @ISA = qw(Exporter); |
7 | |
452a7a81 |
8 | $VERSION = '0.06'; |
b1ddf169 |
9 | |
10 | use strict; |
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 | my($class) = shift; |
86 | |
87 | my $test = $class->builder; |
88 | |
89 | my $caller = caller; |
90 | |
91 | $test->exported_to($caller); |
92 | |
93 | $class->import_extra(\@_); |
94 | my(@imports) = $class->_strip_imports(\@_); |
95 | |
96 | $test->plan(@_); |
97 | |
98 | $class->$_export_to_level(1, $class, @imports); |
99 | } |
100 | |
101 | |
102 | sub _strip_imports { |
103 | my $class = shift; |
104 | my $list = shift; |
105 | |
106 | my @imports = (); |
107 | my @other = (); |
108 | my $idx = 0; |
109 | while( $idx <= $#{$list} ) { |
110 | my $item = $list->[$idx]; |
111 | |
112 | if( defined $item and $item eq 'import' ) { |
113 | push @imports, @{$list->[$idx+1]}; |
114 | $idx++; |
115 | } |
116 | else { |
117 | push @other, $item; |
118 | } |
119 | |
120 | $idx++; |
121 | } |
122 | |
123 | @$list = @other; |
124 | |
125 | 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 | 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 | return Test::Builder->new; |
179 | } |
180 | |
181 | |
182 | 1; |