File: prove.html

package info (click to toggle)
perl-doc-html 5.26.0-4
  • links: PTS, VCS
  • area: main
  • in suites: sid
  • size: 39,400 kB
  • sloc: xml: 36; makefile: 7
file content (720 lines) | stat: -rw-r--r-- 45,499 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>prove - perldoc.perl.org</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="Content-Language" content="en-gb">
  <link rel="search" type="application/opensearchdescription+xml" title="Search perldoc.perl.org" href="/static/search.xml"/>
  <link href="static/css-20100830.css" rel="stylesheet" rev="stylesheet" type="text/css" media="screen">
  <link href="static/exploreperl.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>

<body onLoad="perldoc.startup();" onPageShow="if (event.persisted) perldoc.startup();">
    <div id="page">
      
      <div id="header">
	<div id="homepage_link">
	  <a href="index.html"></a>
	</div>
	<div id="strapline">
	  Perl Programming Documentation
	</div>
	<div id="download_link" class="download">
	  <a href="http://www.perl.org/get.html">Download Perl</a>
	</div>
	<div id="explore_link" class="download">
	  <a id="explore_anchor" href="#">Explore</a>
	</div>
      </div>
      
      <div id="body">
        <div id="left_column">
          <div class="side_group">
            
	    <div class="side_panel doc_panel">
              <p>Manual</p>
              <ul>
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">History / Changes</a>
                <li><a href="index-licence.html">License</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Reference</p>
              <ul>
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Special Variables</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
                <li><a href="index-internals.html">Internals</a>
                <li><a href="index-platforms.html">Platform Specific</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Modules</p>
              <ul>
		<li>
		
                
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		
                  
		
		
                    <a href="index-modules-A.html">A</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-B.html">B</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-C.html">C</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-D.html">D</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-E.html">E</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-F.html">F</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-G.html">G</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-H.html">H</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-I.html">I</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-L.html">L</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-M.html">M</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-N.html">N</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-O.html">O</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-P.html">P</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-S.html">S</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-T.html">T</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-U.html">U</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-X.html">X</a>
                    
                
              </ul>
            </div>
            
	      <div class="side_panel doc_panel">
		<p>Tools</p>
		<ul>
		  <li><a href="preferences.html">Preferences</a>
		</ul>
	      </div>
            
          </div>
        </div>
        <div id="centre_column">
          <div id="content_header">
            <div id="title_bar">
              <div id="page_name">
                <h1>prove</h1>
              </div>
              <div id="perl_version">
                Perl 5 version 26.0 documentation
              </div>
              <div class="page_links" id="page_links_top">
                <a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
		
              </div>
	      <div class="page_links" id="page_links_bottom">
		
                  <a href="#" id="page_index_toggle">Show page index</a> &bull;
		
                <a href="#" id="recent_pages_toggle">Show recent pages</a>		
	      </div>
	      <div id="search_form">
		<form action="search.html" method="GET" id="search">
		  <input type="text" name="q" id="search_box" alt="Search">
		</form>
	      </div>
            </div>
            <div id="breadcrumbs">
                
    <a href="index.html">Home</a> &gt;
    
      
        <a href="index-utilities.html">Utilities</a> &gt;
      
    
    prove
  

            </div>
          </div>
          <div id="content_body">
	    <!--[if lt IE 7]>
 <div class="noscript">
   <p>
     <strong>It looks like you're using Internet Explorer 6. This is a very old
     browser which does not offer full support for modern websites.</strong>
   </p>
   <p>
     Unfortunately this means that this website will not work on
     your computer.
   </p>
   <p>
     Don't miss out though! To view the site (and get a better experience from
     many other websites), simply upgrade to
     <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet
Explorer 8</a>
     or download an alternative browser such as
     <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>,
     <a href="http://www.apple.com/safari/download/">Safari</a>, or
     <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
   </p>
   <p>
     All of these browsers are free. If you're using a PC at work, you may
     need to contact your IT administrator.
   </p>
 </div>
<![endif]-->
	    <noscript>
	      <div class="noscript">
	      <p>
                <strong>Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled,
	        or are running a non-JavaScript capable web browser.</strong>
	      </p>
	      <p>
		To get the best experience, please enable JavaScript or download a modern web browser such as <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet Explorer 8</a>, <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>, <a href="http://www.apple.com/safari/download/">Safari</a>, or <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
              </p>
	      </div>
	    </noscript>

	    <div id="recent_pages" class="hud_container">
	      <div id="recent_pages_header" class="hud_header">
		<div id="recent_pages_close" class="hud_close"><a href="#" onClick="recentPages.hide();return false;"></a></div>
		<div id="recent_pages_title" class="hud_title"><span class="hud_span_top">Recently read</span></div>
		<div id="recent_pages_topright" class="hud_topright"></div>
	      </div>
	      <div id="recent_pages_content" class="hud_content">
	      </div>
	      <div id="recent_pages_footer" class="hud_footer">
		<div id="recent_pages_bottomleft" class="hud_bottomleft"></div>
		<div id="recent_pages_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
		<div id="recent_pages_resize" class="hud_resize"></div>
	      </div>
	    </div>
  
	    <div id="from_search"></div>
            <h1>prove</h1>


  <!--    -->
<ul><li><a href="#NAME">NAME</a><li><a href="#USAGE">USAGE</a><li><a href="#OPTIONS">OPTIONS</a><li><a href="#NOTES">NOTES</a><ul><li><a href="#.proverc">.proverc</a><li><a href="#Reading-from-STDIN">Reading from STDIN</a><li><a href="#Default-Test-Directory">Default Test Directory</a><li><a href="#Colored-Test-Output">Colored Test Output</a><li><a href="#Exit-Code">Exit Code</a><li><a href="#Arguments-to-Tests">Arguments to Tests</a><li><a href="#--exec">--exec</a><li><a href="#--merge">--merge</a><li><a href="#--trap">--trap</a><li><a href="#--state">--state</a><li><a href="#--rules">--rules</a><li><a href="#%40INC">@INC</a><li><a href="#Taint-Mode">Taint Mode</a></ul><li><a href="#FORMATTERS">FORMATTERS</a><li><a href="#SOURCE-HANDLERS">SOURCE HANDLERS</a><li><a href="#PLUGINS">PLUGINS</a><ul><li><a href="#Available-Plugins">Available Plugins</a><li><a href="#Writing-Plugins">Writing Plugins</a></ul></ul><a name="NAME"></a><h1>NAME</h1>
<p>prove - Run tests through a TAP harness.</p>
<a name="USAGE"></a><h1>USAGE</h1>
<pre class="verbatim"><ol><li> <span class="w">prove</span> <span class="s">[</span><span class="w">options</span><span class="s">]</span> <span class="s">[</span><span class="w">files</span> or <span class="w">directories</span><span class="s">]</span></li></ol></pre><a name="OPTIONS"></a><h1>OPTIONS</h1>
<p>Boolean options:</p>
<pre class="verbatim"><ol><li> -<span class="w">v</span><span class="cm">,</span>  --<span class="w">verbose</span>         <span class="w">Print</span> <span class="w">all</span> <span class="w">test</span> <span class="w">lines</span>.</li><li> -l<span class="cm">,</span>  --<span class="w">lib</span>             <span class="w">Add</span> <span class="q">&#39;lib&#39;</span> <span class="w">to</span> <span class="w">the</span> <span class="w">path</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">your</span> <span class="w">tests</span> <span class="s">(</span>-<span class="w">Ilib</span><span class="s">)</span>.</li><li> -b<span class="cm">,</span>  --<span class="w">blib</span>            <span class="w">Add</span> <span class="q">&#39;blib/lib&#39;</span> <a class="l_k" href="functions/and.html">and</a> <span class="q">&#39;blib/arch&#39;</span> <span class="w">to</span> <span class="w">the</span> <span class="w">path</span> <a class="l_k" href="functions/for.html">for</a></li><li>                        <span class="w">your</span> <span class="w">tests</span></li><li> -s<span class="cm">,</span>  --<span class="w">shuffle</span>         <span class="w">Run</span> <span class="w">the</span> <span class="w">tests</span> <span class="w">in</span> <span class="w">random</span> <span class="w">order</span>.</li><li> -c<span class="cm">,</span>  --<span class="w">color</span>           <span class="w">Colored</span> <span class="w">test</span> <span class="w">output</span> <span class="s">(</span><span class="w">default</span><span class="s">)</span>.</li><li>      --<span class="w">nocolor</span>         <span class="w">Do</span> <a class="l_k" href="functions/not.html">not</a> <span class="w">color</span> <span class="w">test</span> <span class="w">output</span>.</li><li>      --<span class="w">count</span>           <span class="w">Show</span> <span class="w">the</span> <span class="w">X</span>/<span class="w">Y</span> <span class="w">test</span> <span class="w">count</span> <a class="l_k" href="functions/when.html">when</a> <a class="l_k" href="functions/not.html">not</a> <span class="i">verbose</span></li><li>                        <span class="s">(</span><span class="w">default</span><span class="s">)</span></li><li>      --<span class="w">nocount</span>         <span class="w">Disable</span> <span class="w">the</span> <span class="w">X</span>/<span class="w">Y</span> <span class="w">test</span> <span class="w">count</span>.</li><li> -<span class="w">D</span>   --<span class="w">dry</span>             <span class="w">Dry</span> <span class="w">run</span>. <span class="w">Show</span> <span class="w">test</span> <span class="w">that</span> <span class="w">would</span> <span class="w">have</span> <span class="w">run</span>.</li><li> -f<span class="cm">,</span>  --<span class="w">failures</span>        <span class="w">Show</span> <span class="w">failed</span> <span class="w">tests</span>.</li><li> -o<span class="cm">,</span>  --<span class="w">comments</span>        <span class="w">Show</span> <span class="w">comments</span>.</li><li>      --<span class="w">ignore</span>-<a class="l_k" href="functions/exit.html">exit</a>     <span class="w">Ignore</span> <a class="l_k" href="functions/exit.html">exit</a> <span class="w">status</span> <span class="w">from</span> <span class="w">test</span> <span class="w">scripts</span>.</li><li> -<span class="q">m,  --merge           Merge test scripts&#39; STDERR with their STDOUT.</span></li><li> <span class="q"> -r,</span>  --<span class="w">recurse</span>         <span class="w">Recursively</span> <span class="w">descend</span> <span class="w">into</span> <span class="w">directories</span>.</li><li>      --<a class="l_k" href="functions/reverse.html">reverse</a>         <span class="w">Run</span> <span class="w">the</span> <span class="w">tests</span> <span class="w">in</span> <a class="l_k" href="functions/reverse.html">reverse</a> <span class="w">order</span>.</li><li> -<span class="q">q,  --quiet           Suppress some test output while running tests.</span></li><li> <span class="q"> -Q,</span>  --<span class="w">QUIET</span>           <span class="w">Only</span> <a class="l_k" href="functions/print.html">print</a> <span class="i">summary</span> <span class="w">results</span>.</li><li> -p<span class="cm">,</span>  --<span class="w">parse</span>           <span class="w">Show</span> <span class="w">full</span> <span class="w">list</span> <span class="w">of</span> <span class="w">TAP</span> <span class="w">parse</span> <span class="w">errors</span><span class="cm">,</span> <a class="l_k" href="functions/if.html">if</a> <span class="w">any</span>.</li><li>      --<span class="w">directives</span>      <span class="w">Only</span> <span class="w">show</span> <span class="w">results</span> <span class="w">with</span> <span class="w">TODO</span> <a class="l_k" href="functions/or.html">or</a> <span class="w">SKIP</span> <span class="w">directives</span>.</li><li>      --<span class="w">timer</span>           <span class="w">Print</span> <span class="w">elapsed</span> <a class="l_k" href="functions/time.html">time</a> <span class="w">after</span> <a class="l_k" href="functions/each.html">each</a> <span class="w">test</span>.</li><li>      --<span class="w">trap</span>            <span class="w">Trap</span> <span class="w">Ctrl</span>-C <a class="l_k" href="functions/and.html">and</a> <a class="l_k" href="functions/print.html">print</a> <span class="i">summary</span> <span class="w">on</span> <span class="w">interrupt</span>.</li><li>      --<span class="w">normalize</span>       <span class="w">Normalize</span> <span class="w">TAP</span> <span class="w">output</span> <span class="w">in</span> <span class="w">verbose</span> <span class="w">output</span></li><li> -T                     <span class="w">Enable</span> <span class="w">tainting</span> <span class="w">checks</span>.</li><li> -t                     <span class="w">Enable</span> <span class="w">tainting</span> <span class="w">warnings</span>.</li><li> -W                     <span class="w">Enable</span> <span class="w">fatal</span> <span class="w">warnings</span>.</li><li> -w                     <span class="w">Enable</span> <span class="w">warnings</span>.</li><li> -<span class="w">h</span><span class="cm">,</span>  --<span class="w">help</span>            <span class="w">Display</span> <span class="w">this</span> <span class="w">help</span></li><li> -<span class="q">?,                    Display this help</span></li><li> <span class="q"> -V,  --version         Display the version</span></li><li> <span class="q"> -H,  --man             Longer manpage for prove</span></li><li>      <span class="q">      --norc            Don&#39;t process default .proverc</span></li></ol></pre><p>Options that take arguments:</p>
<pre class="verbatim"><ol><li> -<span class="w">I</span>                     <span class="w">Library</span> <span class="w">paths</span> <span class="w">to</span> <span class="w">include</span>.</li><li> -<span class="w">P</span>                     <span class="w">Load</span> <span class="w">plugin</span> <span class="s">(</span><span class="w">searches</span> <span class="w">App::Prove::Plugin::</span>*.<span class="s">)</span></li><li> -<span class="w">M</span>                     <span class="w">Load</span> <span class="w">a</span> <span class="w">module</span>.</li><li> -e<span class="cm">,</span>  --<a class="l_k" href="functions/exec.html">exec</a>            <span class="i">Interpreter</span> <span class="w">to</span> <span class="w">run</span> <span class="w">the</span> <span class="w">tests</span> <span class="s">(</span><span class="q">&#39;&#39;</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">compiled</span></li><li>                        <span class="w">tests</span>.<span class="s">)</span></li><li>      --<span class="w">ext</span>             <span class="w">Set</span> <span class="w">the</span> <span class="w">extension</span> <a class="l_k" href="functions/for.html">for</a> <span class="w">tests</span> <span class="s">(</span><span class="w">default</span> <span class="q">&#39;.t&#39;</span><span class="s">)</span></li><li>      --<span class="w">harness</span>         <span class="w">Define</span> <span class="w">test</span> <span class="w">harness</span> <span class="w">to</span> <a class="l_k" href="functions/use.html">use</a>.  <span class="w">See</span> <span class="w">TAP::Harness</span>.</li><li>      --<span class="w">formatter</span>       <span class="w">Result</span> <span class="w">formatter</span> <span class="w">to</span> <a class="l_k" href="functions/use.html">use</a>. <span class="w">See</span> <span class="w">FORMATTERS</span>.</li><li>      --<span class="w">source</span>          <span class="w">Load</span> <a class="l_k" href="functions/and.html">and</a><span class="q">/or configure a SourceHandler. See</span></li><li>                        <span class="q">                        SOURCE HANDLERS.</span></li><li> <span class="q"> -a,  --archive out.tgz Store the resulting TAP in an archive file.</span></li><li> <span class="q"> -j,  --jobs N          Run N test jobs in parallel (try 9.)</span></li><li>      <span class="q">      --state=opts      Control prove&#39;s persistent state.</span></li><li>      <span class="q">      --rc=rcfile       Process options from rcfile</span></li><li>      <span class="q">      --rules           Rules for parallel vs sequential processing.</span></li></ol></pre><a name="NOTES"></a><h1>NOTES</h1>
<a name=".proverc"></a><h2>.proverc</h2>
<p>If <i>~/.proverc</i> or <i>./.proverc</i> exist they will be read and any
options they contain processed before the command line options. Options
in <i>.proverc</i> are specified in the same way as command line options:</p>
<pre class="verbatim"><ol><li>    <span class="c"># .proverc</span></li><li>    --<span class="w">state</span>=<span class="w">hot</span><span class="cm">,</span><span class="w">fast</span><span class="cm">,</span><span class="w">save</span></li><li>    -<span class="w">j9</span></li></ol></pre><p>Additional option files may be specified with the <code class="inline">--<span class="w">rc</span></code>
 option.
Default option file processing is disabled by the <code class="inline">--<span class="w">norc</span></code>
 option.</p>
<p>Under Windows and VMS the option file is named <i>_proverc</i> rather than
<i>.proverc</i> and is sought only in the current directory.</p>
<a name="Reading-from-STDIN"></a><h2>Reading from <code class="inline"><span class="w">STDIN</span></code>
</h2>
<p>If you have a list of tests (or URLs, or anything else you want to test) in a
file, you can add them to your tests by using a '-':</p>
<pre class="verbatim"><ol><li> <span class="w">prove</span> - &lt; <span class="w">my_list_of_things_to_test</span>.<span class="w">txt</span></li></ol></pre><p>See the <code class="inline"><span class="w">README</span></code>
 in the <code class="inline"><span class="w">examples</span></code>
 directory of this distribution.</p>
<a name="Default-Test-Directory"></a><h2>Default Test Directory</h2>
<p>If no files or directories are supplied, <code class="inline"><span class="w">prove</span></code>
 looks for all files
matching the pattern <code class="inline">t/*.t</code>.</p>
<a name="Colored-Test-Output"></a><h2>Colored Test Output</h2>
<p>Colored test output using <a href="TAP/Formatter/Color.html">TAP::Formatter::Color</a> is the default, but 
if output is not to a terminal, color is disabled. You can override this by 
adding the <code class="inline">--<span class="w">color</span></code>
 switch.</p>
<p>Color support requires <a href="Term/ANSIColor.html">Term::ANSIColor</a> on Unix-like platforms and
<a href="http://search.cpan.org/perldoc/Win32::Console">Win32::Console</a> on windows. If the necessary module is not installed
colored output will not be available.</p>
<a name="Exit-Code"></a><h2>Exit Code</h2>
<p>If the tests fail <code class="inline"><span class="w">prove</span></code>
 will exit with non-zero status.</p>
<a name="Arguments-to-Tests"></a><h2>Arguments to Tests</h2>
<p>It is possible to supply arguments to tests. To do so separate them from
prove's own arguments with the arisdottle, '::'. For example</p>
<pre class="verbatim"><ol><li> prove -v t/mytest.t :: --url http://example.com</li></ol></pre><p>would run <i>t/mytest.t</i> with the options '--url <a href="http://example.com">http://example.com</a>'.
When running multiple tests they will each receive the same arguments.</p>
<a name="--exec"></a><h2><code class="inline">--<a class="l_k" href="functions/exec.html">exec</a></code>
</h2>
<p>Normally you can just pass a list of Perl tests and the harness will know how
to execute them.  However, if your tests are not written in Perl or if you
want all tests invoked exactly the same way, use the <code class="inline">-e</code>
, or <code class="inline">--<a class="l_k" href="functions/exec.html">exec</a></code>

switch:</p>
<pre class="verbatim"><ol><li> prove --exec '/usr/bin/ruby -w' t/</li><li> prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/</li><li> prove --exec '/path/to/my/customer/exec'</li></ol></pre><a name="--merge"></a><h2><code class="inline">--<span class="w">merge</span></code>
</h2>
<p>If you need to make sure your diagnostics are displayed in the correct
order relative to test results you can use the <code class="inline">--<span class="w">merge</span></code>
 option to
merge the test scripts' STDERR into their STDOUT.</p>
<p>This guarantees that STDOUT (where the test results appear) and STDERR
(where the diagnostics appear) will stay in sync. The harness will
display any diagnostics your tests emit on STDERR.</p>
<p>Caveat: this is a bit of a kludge. In particular note that if anything
that appears on STDERR looks like a test result the test harness will
get confused. Use this option only if you understand the consequences
and can live with the risk.</p>
<a name="--trap"></a><h2><code class="inline">--<span class="w">trap</span></code>
</h2>
<p>The <code class="inline">--<span class="w">trap</span></code>
 option will attempt to trap SIGINT (Ctrl-C) during a test
run and display the test summary even if the run is interrupted</p>
<a name="--state"></a><h2><code class="inline">--<span class="w">state</span></code>
</h2>
<p>You can ask <code class="inline"><span class="w">prove</span></code>
 to remember the state of previous test runs and
select and/or order the tests to be run based on that saved state.</p>
<p>The <code class="inline">--<span class="w">state</span></code>
 switch requires an argument which must be a comma
separated list of one or more of the following options.</p>
<ul>
<li><a name="last"></a><b><code class="inline"><a class="l_k" href="functions/last.html">last</a></code></b>
<p>Run the same tests as the last time the state was saved. This makes it
possible, for example, to recreate the ordering of a shuffled test.</p>
<pre class="verbatim"><ol><li>    # Run all tests in random order</li><li>    $ prove -b --state=save --shuffle</li><li></li><li>    # Run them again in the same order</li><li>    $ prove -b --state=last</li></ol></pre></li>
<li><a name="failed"></a><b><code class="inline"><span class="w">failed</span></code>
</b>
<p>Run only the tests that failed on the last run.</p>
<pre class="verbatim"><ol><li>    <span class="c"># Run all tests</span></li><li>    <span class="i">$ prove</span> -<span class="w">b</span> --<span class="w">state</span>=<span class="w">save</span></li><li></li><li>    <span class="c"># Run failures</span></li><li>    <span class="i">$ prove</span> -b --<span class="w">state</span>=<span class="w">failed</span></li></ol></pre><p>If you also specify the <code class="inline"><span class="w">save</span></code>
 option newly passing tests will be
excluded from subsequent runs.</p>
<pre class="verbatim"><ol><li>    # Repeat until no more failures</li><li>    $ prove -b --state=failed,save</li></ol></pre></li>
<li><a name="passed"></a><b><code class="inline"><span class="w">passed</span></code>
</b>
<p>Run only the passed tests from last time. Useful to make sure that no
new problems have been introduced.</p>
</li>
<li><a name="all"></a><b><code class="inline"><span class="w">all</span></code>
</b>
<p>Run all tests in normal order. Multple options may be specified, so to
run all tests with the failures from last time first:</p>
<pre class="verbatim"><ol><li>    $ prove -b --state=failed,all,save</li></ol></pre></li>
<li><a name="hot"></a><b><code class="inline"><span class="w">hot</span></code>
</b>
<p>Run the tests that most recently failed first. The last failure time of
each test is stored. The <code class="inline"><span class="w">hot</span></code>
 option causes tests to be run in most-recent-
failure order.</p>
<pre class="verbatim"><ol><li>    $ prove -b --state=hot,save</li></ol></pre><p>Tests that have never failed will not be selected. To run all tests with
the most recently failed first use</p>
<pre class="verbatim"><ol><li>    $ prove -b --state=hot,all,save</li></ol></pre><p>This combination of options may also be specified thus</p>
<pre class="verbatim"><ol><li>    $ prove -b --state=adrian</li></ol></pre></li>
<li><a name="todo"></a><b><code class="inline"><span class="w">todo</span></code>
</b>
<p>Run any tests with todos.</p>
</li>
<li><a name="slow"></a><b><code class="inline"><span class="w">slow</span></code>
</b>
<p>Run the tests in slowest to fastest order. This is useful in conjunction
with the <code class="inline">-<span class="w">j</span></code>
 parallel testing switch to ensure that your slowest tests
start running first.</p>
<pre class="verbatim"><ol><li>    $ prove -b --state=slow -j9</li></ol></pre></li>
<li><a name="fast"></a><b><code class="inline"><span class="w">fast</span></code>
</b>
<p>Run test tests in fastest to slowest order.</p>
</li>
<li><a name="new"></a><b><code class="inline"><span class="w">new</span></code>
</b>
<p>Run the tests in newest to oldest order based on the modification times
of the test scripts.</p>
</li>
<li><a name="old"></a><b><code class="inline"><span class="w">old</span></code>
</b>
<p>Run the tests in oldest to newest order.</p>
</li>
<li><a name="fresh"></a><b><code class="inline"><span class="w">fresh</span></code>
</b>
<p>Run those test scripts that have been modified since the last test run.</p>
</li>
<li><a name="save"></a><b><code class="inline"><span class="w">save</span></code>
</b>
<p>Save the state on exit. The state is stored in a file called <i>.prove</i>
(<i>_prove</i> on Windows and VMS) in the current directory.</p>
</li>
</ul>
<p>The <code class="inline">--<span class="w">state</span></code>
 switch may be used more than once.</p>
<pre class="verbatim"><ol><li>    $ prove -b --state=hot --state=all,save</li></ol></pre><a name="--rules"></a><h2>--rules</h2>
<p>The <code class="inline">--<span class="w">rules</span></code>
 option is used to control which tests are run sequentially and
which are run in parallel, if the <code class="inline">--<span class="w">jobs</span></code>
 option is specified. The option may
be specified multiple times, and the order matters.</p>
<p>The most practical use is likely to specify that some tests are not
"parallel-ready".  Since mentioning a file with --rules doesn't cause it to
be selected to run as a test, you can "set and forget" some rules preferences in
your .proverc file. Then you'll be able to take maximum advantage of the
performance benefits of parallel testing, while some exceptions are still run
in parallel.</p>
<a name="--rules-examples"></a><h3>--rules examples</h3>
<pre class="verbatim"><ol><li>    <span class="c"># All tests are allowed to run in parallel, except those starting with &quot;p&quot;</span></li><li>    --<span class="w">rules</span>=<span class="q">&#39;seq=t/p*.t&#39;</span> --<span class="w">rules</span>=<span class="q">&#39;par=**&#39;</span></li><li></li><li>    <span class="c"># All tests must run in sequence except those starting with &quot;p&quot;, which should be run parallel</span></li><li>    --<span class="w">rules</span>=<span class="q">&#39;par=t/p*.t&#39;</span></li></ol></pre><a name="--rules-resolution"></a><h3>--rules resolution</h3>
<ul>
<li><a name="*-By-default%2c-all-tests-are-eligible-to-be-run-in-parallel.-Specifying-any-of-your-own-rules-removes-this-one."></a><b>By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one.</b>
</li>
<li><a name="*-%22First-match-wins%22.-The-first-rule-that-matches-a-test-will-be-the-one-that-applies."></a><b>"First match wins". The first rule that matches a test will be the one that applies.</b>
</li>
<li><a name="*-Any-test-which-does-not-match-a-rule-will-be-run-in-sequence-at-the-end-of-the-run."></a><b>Any test which does not match a rule will be run in sequence at the end of the run.</b>
</li>
<li><a name="*-The-existence-of-a-rule-does-not-imply-selecting-a-test.-You-must-still-specify-the-tests-to-run."></a><b>The existence of a rule does not imply selecting a test. You must still specify the tests to run.</b>
</li>
<li><a name="*-Specifying-a-rule-to-allow-tests-to-run-in-parallel-does-not-make-them-run-in-parallel.-You-still-need-specify-the-number-of-parallel-jobs-in-your-Harness-object."></a><b>Specifying a rule to allow tests to run in parallel does not make them run in parallel. You still need specify the number of parallel <code class="inline"><span class="w">jobs</span></code>
 in your Harness object.</b>
</li>
</ul>
<a name="--rules-Glob-style-pattern-matching"></a><h3>--rules Glob-style pattern matching</h3>
<p>We implement our own glob-style pattern matching for --rules. Here are the
supported patterns:</p>
<pre class="verbatim"><ol><li>    <span class="i">**</span> <span class="w">is</span> <span class="w">any</span> <span class="w">number</span> <span class="w">of</span> <span class="w">characters</span><span class="cm">,</span> <span class="w">including</span> <span class="q">/, within a pathname</span></li><li>    <span class="q">    * is zero or more characters within a filename/</span><span class="w">directory</span> <span class="w">name</span></li><li>    ? <span class="w">is</span> <span class="w">exactly</span> <span class="w">one</span> <span class="w">character</span> <span class="w">within</span> <span class="w">a</span> <span class="w">filename</span>/<span class="w">directory</span> <span class="w">name</span></li><li>    <span class="s">{</span><span class="w">foo</span><span class="cm">,</span><span class="w">bar</span><span class="cm">,</span><span class="w">baz</span><span class="s">}</span> <span class="w">is</span> <span class="w">any</span> <span class="w">of</span> <span class="w">foo</span><span class="cm">,</span> <span class="w">bar</span> <a class="l_k" href="functions/or.html">or</a> <span class="w">baz</span>.</li><li>    \ <span class="w">is</span> <span class="w">an</span> <span class="w">escape</span> <span class="w">character</span></li></ol></pre><a name="More-advanced-specifications-for-parallel-vs-sequence-run-rules"></a><h3>More advanced specifications for parallel vs sequence run rules</h3>
<p>If you need more advanced management of what runs in parallel vs in sequence, see
the associated 'rules' documentation in <a href="TAP/Harness.html">TAP::Harness</a> and <a href="TAP/Parser/Scheduler.html">TAP::Parser::Scheduler</a>.
If what's possible directly through <code class="inline"><span class="w">prove</span></code>
 is not sufficient, you can write your own
harness to access these features directly.</p>
<a name="%40INC"></a><h2>@INC</h2>
<p>prove introduces a separation between "options passed to the perl which
runs prove" and "options passed to the perl which runs tests"; this
distinction is by design. Thus the perl which is running a test starts
with the default <code class="inline"><span class="i">@INC</span></code>
. Additional library directories can be added
via the <code class="inline"><span class="w">PERL5LIB</span></code>
 environment variable, via -Ifoo in <code class="inline"><span class="w">PERL5OPT</span></code>
 or
via the <code class="inline">-<span class="w">Ilib</span></code>
 option to <i>prove</i>.</p>
<a name="Taint-Mode"></a><h2>Taint Mode</h2>
<p>Normally when a Perl program is run in taint mode the contents of the
<code class="inline"><span class="w">PERL5LIB</span></code>
 environment variable do not appear in <code class="inline"><span class="i">@INC</span></code>
.</p>
<p>Because <code class="inline"><span class="w">PERL5LIB</span></code>
 is often used during testing to add build
directories to <code class="inline"><span class="i">@INC</span></code>
 prove passes the names of any directories found
in <code class="inline"><span class="w">PERL5LIB</span></code>
 as -I switches. The net effect of this is that
<code class="inline"><span class="w">PERL5LIB</span></code>
 is honoured even when prove is run in taint mode.</p>
<a name="FORMATTERS"></a><h1>FORMATTERS</h1>
<p>You can load a custom <a href="http://search.cpan.org/perldoc/TAP::Parser::Formatter">TAP::Parser::Formatter</a>:</p>
<pre class="verbatim"><ol><li>  <span class="w">prove</span> --<span class="w">formatter</span> <span class="w">MyFormatter</span></li></ol></pre><a name="SOURCE-HANDLERS"></a><h1>SOURCE HANDLERS</h1>
<p>You can load custom <a href="TAP/Parser/SourceHandler.html">TAP::Parser::SourceHandler</a>s, to change the way the
parser interprets particular <i>sources</i> of TAP.</p>
<pre class="verbatim"><ol><li>  <span class="w">prove</span> --<span class="w">source</span> <span class="w">MyHandler</span> --<span class="w">source</span> <span class="w">YetAnother</span> <span class="w">t</span></li></ol></pre><p>If you want to provide config to the source you can use:</p>
<pre class="verbatim"><ol><li>  <span class="w">prove</span> --<span class="w">source</span> <span class="w">MyCustom</span> \</li><li>        --<span class="w">source</span> <span class="w">Perl</span> --<span class="w">perl</span>-<span class="w">option</span> <span class="q">&#39;foo=bar baz&#39;</span> --<span class="w">perl</span>-<span class="w">option</span> <span class="w">avg</span>=<span class="n">0.278</span> \</li><li>        --<span class="w">source</span> <span class="w">File</span> --<span class="w">file</span>-<span class="w">option</span> <span class="w">extensions</span>=.<span class="w">txt</span> --<span class="w">file</span>-<span class="w">option</span> <span class="w">extensions</span>=.<span class="w">tmp</span> <span class="w">t</span></li><li>        --<span class="w">source</span> <span class="w">pgTAP</span> --<span class="w">pgtap</span>-<span class="w">option</span> <span class="w">pset</span>=format=html --pgtap-option pset=border=2</li></ol></pre><p>Each <code class="inline">--<span class="i">$source</span>-<span class="w">option</span></code>
 option must specify a key/value pair separated by an
<code class="inline">=</code>
. If an option can take multiple values, just specify it multiple times,
as with the <code class="inline"><span class="w">extensions</span>=</code>
 examples above. If the option should be a hash
reference, specify the value as a second pair separated by a <code class="inline">=</code>
, as in the
<code class="inline"><span class="w">pset</span>=</code>
 examples above (escape <code class="inline">=</code>
 with a backslash).</p>
<p>All <code class="inline">--<span class="w">sources</span></code>
 are combined into a hash, and passed to <a href="TAP/Harness.html#new">new in TAP::Harness</a>'s
<code class="inline"><span class="w">sources</span></code>
 parameter.</p>
<p>See <a href="TAP/Parser/IteratorFactory.html">TAP::Parser::IteratorFactory</a> for more details on how configuration is
passed to <i>SourceHandlers</i>.</p>
<a name="PLUGINS"></a><h1>PLUGINS</h1>
<p>Plugins can be loaded using the <code class="inline">-P<i>plugin</i></code> syntax, eg:</p>
<pre class="verbatim"><ol><li>  <span class="w">prove</span> -<span class="w">PMyPlugin</span></li></ol></pre><p>This will search for a module named <code class="inline"><span class="w">App::Prove::Plugin::MyPlugin</span></code>
, or failing
that, <code class="inline"><span class="w">MyPlugin</span></code>
.  If the plugin can't be found, <code class="inline"><span class="w">prove</span></code>
 will complain &amp; exit.</p>
<p>You can pass arguments to your plugin by appending <code class="inline"><span class="pd">=arg1,arg2,etc</span></code>
 to the
plugin name:</p>
<pre class="verbatim"><ol><li>  <span class="w">prove</span> -<span class="w">PMyPlugin</span>=<span class="w">fou</span><span class="cm">,</span><span class="w">du</span><span class="cm">,</span><span class="w">fafa</span></li></ol></pre><p>Please check individual plugin documentation for more details.</p>
<a name="Available-Plugins"></a><h2>Available Plugins</h2>
<p>For an up-to-date list of plugins available, please check CPAN:</p>
<p><a href="http://search.cpan.org/search?query=App%3A%3AProve+Plugin">http://search.cpan.org/search?query=App%3A%3AProve+Plugin</a></p>
<a name="Writing-Plugins"></a><h2>Writing Plugins</h2>
<p>Please see <a href="App/Prove.html#PLUGINS">PLUGINS in App::Prove</a>.</p>




  <div id="page_index" class="hud_container">
    <div id="page_index_header" class="hud_header">
      <div id="page_index_close" class="hud_close"><a href="#" onClick="pageIndex.hide();return false;"></a></div>
      <div id="page_index_title" class="hud_title"><span class="hud_span_top">Page index</span></div>
      <div id="page_index_topright" class="hud_topright"></div>
    </div>
    <div id="page_index_content" class="hud_content">
      <ul><li><a href="#NAME">NAME</a><li><a href="#USAGE">USAGE</a><li><a href="#OPTIONS">OPTIONS</a><li><a href="#NOTES">NOTES</a><ul><li><a href="#.proverc">.proverc</a><li><a href="#Reading-from-STDIN">Reading from STDIN</a><li><a href="#Default-Test-Directory">Default Test Directory</a><li><a href="#Colored-Test-Output">Colored Test Output</a><li><a href="#Exit-Code">Exit Code</a><li><a href="#Arguments-to-Tests">Arguments to Tests</a><li><a href="#--exec">--exec</a><li><a href="#--merge">--merge</a><li><a href="#--trap">--trap</a><li><a href="#--state">--state</a><li><a href="#--rules">--rules</a><li><a href="#%40INC">@INC</a><li><a href="#Taint-Mode">Taint Mode</a></ul><li><a href="#FORMATTERS">FORMATTERS</a><li><a href="#SOURCE-HANDLERS">SOURCE HANDLERS</a><li><a href="#PLUGINS">PLUGINS</a><ul><li><a href="#Available-Plugins">Available Plugins</a><li><a href="#Writing-Plugins">Writing Plugins</a></ul></ul>
    </div>
    <div id="page_index_footer" class="hud_footer">
      <div id="page_index_bottomleft" class="hud_bottomleft"></div>
      <div id="page_index_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
      <div id="page_index_resize" class="hud_resize"></div>
    </div>
  </div>


	    &nbsp;
          </div>
          <div id="content_footer">
          </div>
        </div>
        <div class="clear"></div>
      </div>
      
    <div id="footer">
      <div id="footer_content">
        <div id="footer_strapline">
          perldoc.perl.org - Official documentation for the Perl programming language
        </div>
        <div id="footer_links">
          <div id="address">
            <p class="name">Contact details</p>
            <p class="address">
	      Site maintained by <a href="mailto:jj@jonallen.info">Jon Allen (JJ)</a><br>
	    </p>
            <p class="contact">
              Documentation maintained by the <a href="http://lists.cpan.org/showlist.cgi?name=perl5-porters">Perl 5 Porters</a>
            </p>
          </div>
          <ul class="f1">
            <li>Manual
              <ul class="f2">
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">Changes</a>
              </ul>
            <li>Reference
              <ul class="f2">
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Variables</a>
              </ul>
            <li>Modules
              <ul class="f2">
                <li><a href="index-modules-A.html">Modules</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
              </ul>
            <li>Misc
              <ul class="f2">
                <li><a href="index-licence.html">License</a>
                <li><a href="index-internals.html">Internals</a>
                <li><a href="index-platforms.html">Platforms</a>
              </ul>          </ul>
          <div class="clear"></div>
        </div>
      </div>
      <div id="footer_end">
      </div>
    </div>
      
    </div>
      <script language="JavaScript" type="text/javascript" src="static/exploreperl.js"></script>
      <script language="JavaScript" src="static/combined-20100403.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
  perldoc.setPath(0);
  perldoc.pageName    = 'prove';
  perldoc.pageAddress = 'prove.html';
  perldoc.contentPage = 1;
  explorePerl.render();
  explorePerl.addEvents('explore_anchor');
</script>
    
  </body>
</html>