ext/Test-Simple/lib/Test/Builder/Module.pm

   1 package Test::Builder::Module;
   2
   3 use strict;
   4
   5 use Test::Builder;
   6
   7 require Exporter;
   8 our @ISA = qw(Exporter);
   9
  10 our $VERSION = '0.92';
  11 $VERSION = eval $VERSION;      ## no critic (BuiltinFunctions::ProhibitStringyEval)
  12
  13 # 5.004's Exporter doesn't have export_to_level.
  14 my $_export_to_level = sub {
  15     my $pkg   = shift;
  16     my $level = shift;
  17     (undef) = shift;    # redundant arg
  18     my $callpkg = caller($level);
  19     $pkg->export( $callpkg, @_ );
  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     # Don't run all this when loading ourself.
  88     return 1 if $class eq 'Test::Builder::Module';
  89
  90     my $test = $class->builder;
  91
  92     my $caller = caller;
  93
  94     $test->exported_to($caller);
  95
  96     $class->import_extra( \@_ );
  97     my(@imports) = $class->_strip_imports( \@_ );
  98
  99     $test->plan(@_);
 100
 101     $class->$_export_to_level( 1, $class, @imports );
 102 }
 103
 104 sub _strip_imports {
 105     my $class = shift;
 106     my $list  = shift;
 107
 108     my @imports = ();
 109     my @other   = ();
 110     my $idx     = 0;
 111     while( $idx <= $#{$list} ) {
 112         my $item = $list->[$idx];
 113
 114         if( defined $item and $item eq 'import' ) {
 115             push @imports, @{ $list->[ $idx + 1 ] };
 116             $idx++;
 117         }
 118         else {
 119             push @other, $item;
 120         }
 121
 122         $idx++;
 123     }
 124
 125     @$list = @other;
 126
 127     return @imports;
 128 }
 129
 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
 147 sub import_extra { }
 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 1;