vcs.maemo.org Git - pkg-perl/blob - deb-src/libtest-harness-perl/libtest-harness-perl-3.12/t/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.72';
   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 =head1 NAME
  22
  23 Test::Builder::Module - Base class for test modules
  24
  25 =head1 SYNOPSIS
  26
  27   # Emulates Test::Simple
  28   package Your::Module;
  29
  30   my $CLASS = __PACKAGE__;
  31
  32   use base 'Test::Builder::Module';
  33   @EXPORT = qw(ok);
  34
  35   sub ok ($;$) {
  36       my $tb = $CLASS->builder;
  37       return $tb->ok(@_);
  38   }
  39
  40   1;
  41
  42
  43 =head1 DESCRIPTION
  44
  45 This is a superclass for Test::Builder-based modules.  It provides a
  46 handful of common functionality and a method of getting at the underlying
  47 Test::Builder object.
  48
  49
  50 =head2 Importing
  51
  52 Test::Builder::Module is a subclass of Exporter which means your
  53 module is also a subclass of Exporter.  @EXPORT, @EXPORT_OK, etc...
  54 all act normally.
  55
  56 A few methods are provided to do the C<use Your::Module tests => 23> part
  57 for you.
  58
  59 =head3 import
  60
  61 Test::Builder::Module provides an import() method which acts in the
  62 same basic way as Test::More's, setting the plan and controling
  63 exporting of functions and variables.  This allows your module to set
  64 the plan independent of Test::More.
  65
  66 All arguments passed to import() are passed onto
  67 C<< Your::Module->builder->plan() >> with the exception of
  68 C<import =>[qw(things to import)]>.
  69
  70     use Your::Module import => [qw(this that)], tests => 23;
  71
  72 says to import the functions this() and that() as well as set the plan
  73 to be 23 tests.
  74
  75 import() also sets the exported_to() attribute of your builder to be
  76 the caller of the import() function.
  77
  78 Additional behaviors can be added to your import() method by overriding
  79 import_extra().
  80
  81 =cut
  82
  83 sub import {
  84     my ($class) = shift;
  85
  86     my $test = $class->builder;
  87
  88     my $caller = caller;
  89
  90     $test->exported_to($caller);
  91
  92     $class->import_extra( \@_ );
  93     my (@imports) = $class->_strip_imports( \@_ );
  94
  95     $test->plan(@_);
  96
  97     $class->$_export_to_level( 1, $class, @imports );
  98 }
  99
 100 sub _strip_imports {
 101     my $class = shift;
 102     my $list  = shift;
 103
 104     my @imports = ();
 105     my @other   = ();
 106     my $idx     = 0;
 107     while ( $idx <= $#{$list} ) {
 108         my $item = $list->[$idx];
 109
 110         if ( defined $item and $item eq 'import' ) {
 111             push @imports, @{ $list->[ $idx + 1 ] };
 112             $idx++;
 113         }
 114         else {
 115             push @other, $item;
 116         }
 117
 118         $idx++;
 119     }
 120
 121     @$list = @other;
 122
 123     return @imports;
 124 }
 125
 126 =head3 import_extra
 127
 128     Your::Module->import_extra(\@import_args);
 129
 130 import_extra() is called by import().  It provides an opportunity for you
 131 to add behaviors to your module based on its import list.
 132
 133 Any extra arguments which shouldn't be passed on to plan() should be
 134 stripped off by this method.
 135
 136 See Test::More for an example of its use.
 137
 138 B<NOTE> This mechanism is I<VERY ALPHA AND LIKELY TO CHANGE> as it
 139 feels like a bit of an ugly hack in its current form.
 140
 141 =cut
 142
 143 sub import_extra { }
 144
 145 =head2 Builder
 146
 147 Test::Builder::Module provides some methods of getting at the underlying
 148 Test::Builder object.
 149
 150 =head3 builder
 151
 152   my $builder = Your::Class->builder;
 153
 154 This method returns the Test::Builder object associated with Your::Class.
 155 It is not a constructor so you can call it as often as you like.
 156
 157 This is the preferred way to get the Test::Builder object.  You should
 158 I<not> get it via C<< Test::Builder->new >> as was previously
 159 recommended.
 160
 161 The object returned by builder() may change at runtime so you should
 162 call builder() inside each function rather than store it in a global.
 163
 164   sub ok {
 165       my $builder = Your::Class->builder;
 166
 167       return $builder->ok(@_);
 168   }
 169
 170
 171 =cut
 172
 173 sub builder {
 174     return Test::Builder->new;
 175 }
 176
 177 1;