mingw/html/lib/Test/Builder/Module.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Test::Builder::Module - Base class for test modules</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Test::Builder::Module - Base class for test modules</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#importing">Importing</a></li>
  28                 <ul>
  29
  30                         <li><a href="#import">import</a></li>
  31                         <li><a href="#import_extra">import_extra</a></li>
  32                 </ul>
  33
  34                 <li><a href="#builder">Builder</a></li>
  35                 <ul>
  36
  37                         <li><a href="#builder">builder</a></li>
  38                 </ul>
  39
  40         </ul>
  41
  42 </ul>
  43 <!-- INDEX END -->
  44
  45 <hr />
  46 <p>
  47 </p>
  48 <h1><a name="name">NAME</a></h1>
  49 <p>Test::Builder::Module - Base class for test modules</p>
  50 <p>
  51 </p>
  52 <hr />
  53 <h1><a name="synopsis">SYNOPSIS</a></h1>
  54 <pre>
  55   # Emulates Test::Simple
  56   package Your::Module;</pre>
  57 <pre>
  58   my $CLASS = __PACKAGE__;</pre>
  59 <pre>
  60   use base 'Test::Builder::Module';
  61   @EXPORT = qw(ok);</pre>
  62 <pre>
  63   sub ok ($;$) {
  64       my $tb = $CLASS-&gt;builder;
  65       return $tb-&gt;ok(@_);
  66   }
  67
  68   1;</pre>
  69 <p>
  70 </p>
  71 <hr />
  72 <h1><a name="description">DESCRIPTION</a></h1>
  73 <p>This is a superclass for Test::Builder-based modules.  It provides a
  74 handful of common functionality and a method of getting at the underlying
  75 Test::Builder object.</p>
  76 <p>
  77 </p>
  78 <h2><a name="importing">Importing</a></h2>
  79 <p>Test::Builder::Module is a subclass of Exporter which means your
  80 module is also a subclass of Exporter.  @EXPORT, @EXPORT_OK, etc...
  81 all act normally.</p>
  82 <p>A few methods are provided to do the <code>use Your::Module tests =</code> 23&gt; part
  83 for you.</p>
  84 <p>
  85 </p>
  86 <h3><a name="import">import</a></h3>
  87 <p>Test::Builder::Module provides an <code>import()</code> method which acts in the
  88 same basic way as Test::More's, setting the plan and controling
  89 exporting of functions and variables.  This allows your module to set
  90 the plan independent of Test::More.</p>
  91 <p>All arguments passed to <code>import()</code> are passed onto
  92 <code>Your::Module-&gt;builder-&gt;plan()</code> with the exception of
  93 <code>import =</code>[qw(things to import)]&gt;.</p>
  94 <pre>
  95     use Your::Module import =&gt; [qw(this that)], tests =&gt; 23;</pre>
  96 <p>says to import the functions <code>this()</code> and <code>that()</code> as well as set the plan
  97 to be 23 tests.</p>
  98 <p><code>import()</code> also sets the <code>exported_to()</code> attribute of your builder to be
  99 the caller of the <code>import()</code> function.</p>
 100 <p>Additional behaviors can be added to your <code>import()</code> method by overriding
 101 import_extra().</p>
 102 <p>
 103 </p>
 104 <h3><a name="import_extra">import_extra</a></h3>
 105 <pre>
 106     Your::Module-&gt;import_extra(\@import_args);</pre>
 107 <p><code>import_extra()</code> is called by import().  It provides an opportunity for you
 108 to add behaviors to your module based on its import list.</p>
 109 <p>Any extra arguments which shouldn't be passed on to <code>plan()</code> should be
 110 stripped off by this method.</p>
 111 <p>See Test::More for an example of its use.</p>
 112 <p><strong>NOTE</strong> This mechanism is <em>VERY ALPHA AND LIKELY TO CHANGE</em> as it
 113 feels like a bit of an ugly hack in its current form.</p>
 114 <p>
 115 </p>
 116 <h2><a name="builder">Builder</a></h2>
 117 <p>Test::Builder::Module provides some methods of getting at the underlying
 118 Test::Builder object.</p>
 119 <p>
 120 </p>
 121 <h3><a name="builder">builder</a></h3>
 122 <pre>
 123   my $builder = Your::Class-&gt;builder;</pre>
 124 <p>This method returns the Test::Builder object associated with Your::Class.
 125 It is not a constructor so you can call it as often as you like.</p>
 126 <p>This is the preferred way to get the Test::Builder object.  You should
 127 <em>not</em> get it via <code>Test::Builder-&gt;new</code> as was previously
 128 recommended.</p>
 129 <p>The object returned by <code>builder()</code> may change at runtime so you should
 130 call <code>builder()</code> inside each function rather than store it in a global.</p>
 131 <pre>
 132   sub ok {
 133       my $builder = Your::Class-&gt;builder;</pre>
 134 <pre>
 135       return $builder-&gt;ok(@_);
 136   }</pre>
 137 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 138 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 139 <big><strong><span class="block">&nbsp;Test::Builder::Module - Base class for test modules</span></strong></big>
 140 </td></tr>
 141 </table>
 142
 143 </body>
 144
 145 </html>