lib/Test/Builder/Module.pm

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