1 | package Test::Builder::Module;
|
---|
2 |
|
---|
3 | use Test::Builder;
|
---|
4 |
|
---|
5 | require Exporter;
|
---|
6 | @ISA = qw(Exporter);
|
---|
7 |
|
---|
8 | $VERSION = '0.02';
|
---|
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;
|
---|