1 package Test::Builder::Module;
12 # 5.004's Exporter doesn't have export_to_level.
13 my $_export_to_level = sub {
16 (undef) = shift; # redundant arg
17 my $callpkg = caller($level);
18 $pkg->export($callpkg, @_);
24 Test::Builder::Module - Base class for test modules
28 # Emulates Test::Simple
31 my $CLASS = __PACKAGE__;
33 use base 'Test::Builder::Module';
37 my $tb = $CLASS->builder;
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
53 Test::Builder::Module is a subclass of Exporter which means your
54 module is also a subclass of Exporter. @EXPORT, @EXPORT_OK, etc...
57 A few methods are provided to do the C<use Your::Module tests => 23> part
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.
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)]>.
71 use Your::Module import => [qw(this that)], tests => 23;
73 says to import the functions this() and that() as well as set the plan
76 import() also sets the exported_to() attribute of your builder to be
77 the caller of the import() function.
79 Additional behaviors can be added to your import() method by overriding
87 my $test = $class->builder;
91 $test->exported_to($caller);
93 $class->import_extra(\@_);
94 my(@imports) = $class->_strip_imports(\@_);
98 $class->$_export_to_level(1, $class, @imports);
109 while( $idx <= $#{$list} ) {
110 my $item = $list->[$idx];
112 if( defined $item and $item eq 'import' ) {
113 push @imports, @{$list->[$idx+1]};
131 Your::Module->import_extra(\@import_args);
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.
136 Any extra arguments which shouldn't be passed on to plan() should be
137 stripped off by this method.
139 See Test::More for an example of its use.
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.
151 Test::Builder::Module provides some methods of getting at the underlying
152 Test::Builder object.
156 my $builder = Your::Class->builder;
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.
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
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.
169 my $builder = Your::Class->builder;
171 return $builder->ok(@_);
178 return Test::Builder->new;