1Test::Harness::Straps(3pPme)rl Programmers Reference GuiTdeest::Harness::Straps(3pm)
2
6 Test::Harness::Straps - detailed analysis of test results
7
9 use Test::Harness::Straps;
10 my $strap = Test::Harness::Straps->new;
12 # Various ways to interpret a test
14 my %results = $strap->analyze($name, \@test_output);
15 my %results = $strap->analyze_fh($name, $test_filehandle);
16 my %results = $strap->analyze_file($test_file);
17 # UNIMPLEMENTED
19 my %total = $strap->total_results;
20 # Altering the behavior of the strap UNIMPLEMENTED
22 my $verbose_output = $strap->dump_verbose();
23 $strap->dump_verbose_fh($output_filehandle);
24
26 THIS IS ALPHA SOFTWARE in that the interface is subject to change in
27 incompatible ways. It is otherwise stable.
28 Test::Harness is limited to printing out its results. This makes anal‐
30 ysis of the test results difficult for anything but a human. To make
31 it easier for programs to work with test results, we provide Test::Har‐
32 ness::Straps. Instead of printing the results, straps provide them as
33 raw data. You can also configure how the tests are to be run.
34 The interface is currently incomplete. Please contact the author if
36 you'd like a feature added or something change or just have comments.
37
39 new()
40 my $strap = Test::Harness::Straps->new;
42 Initialize a new strap.
44 $strap->_init
46 $strap->_init;
48 Initialize the internal state of a strap to make it ready for parsing.
50
52 $strap->analyze( $name, \@output_lines )
53 my %results = $strap->analyze($name, \@test_output);
55 Analyzes the output of a single test, assigning it the given $name for
57 use in the total report. Returns the %results of the test. See
58 Results.
59 @test_output should be the raw output from the test, including new‐
61 lines.
62 $strap->analyze_fh( $name, $test_filehandle )
64 my %results = $strap->analyze_fh($name, $test_filehandle);
66 Like "analyze", but it reads from the given filehandle.
68 $strap->analyze_file( $test_file )
70 my %results = $strap->analyze_file($test_file);
72 Like "analyze", but it runs the given $test_file and parses its
74 results. It will also use that name for the total report.
75 $strap->_command_line( $file )
77 Returns the full command line that will be run to test $file.
79 $strap->_command()
81 Returns the command that runs the test. Combine this with
83 "_switches()" to build a command line.
84 Typically this is $^X, but you can set $ENV{HARNESS_PERL} to use a dif‐
86 ferent Perl than what you're running the harness under. This might be
87 to run a threaded Perl, for example.
88 You can also overload this method if you've built your own strap sub‐
90 class, such as a PHP interpreter for a PHP-based strap.
91 $strap->_switches( $file )
93 Formats and returns the switches necessary to run the test.
95 $strap->_cleaned_switches( @switches_from_user )
97 Returns only defined, non-blank, trimmed switches from the parms
99 passed.
100 $strap->_INC2PERL5LIB
102 local $ENV{PERL5LIB} = $self->_INC2PERL5LIB;
104 Takes the current value of @INC and turns it into something suitable
106 for putting onto "PERL5LIB".
107 $strap->_filtered_INC()
109 my @filtered_inc = $self->_filtered_INC;
111 Shortens @INC by removing redundant and unnecessary entries. Necessary
113 for OSes with limited command line lengths, like VMS.
114 $strap->_restore_PERL5LIB()
116 $self->_restore_PERL5LIB;
118 This restores the original value of the "PERL5LIB" environment vari‐
120 able. Necessary on VMS, otherwise a no-op.
121
123 Methods for identifying what sort of line you're looking at.
124 "_is_diagnostic"
126 my $is_diagnostic = $strap->_is_diagnostic($line, \$comment);
128 Checks if the given line is a comment. If so, it will place it into
130 $comment (sans #).
131 "_is_header"
133 my $is_header = $strap->_is_header($line);
135 Checks if the given line is a header (1..M) line. If so, it places how
137 many tests there will be in "$strap->{max}", a list of which tests are
138 todo in "$strap->{todo}" and if the whole test was skipped
139 "$strap->{skip_all}" contains the reason.
140 "_is_bail_out"
142 my $is_bail_out = $strap->_is_bail_out($line, \$reason);
144 Checks if the line is a "Bail out!". Places the reason for bailing (if
146 any) in $reason.
147 "_reset_file_state"
149 $strap->_reset_file_state;
151 Resets things like "$strap->{max}" , "$strap->{skip_all}", etc. so it's
153 ready to parse the next file.
154
156 The %results returned from "analyze()" contain the following informa‐
157 tion:
158 passing true if the whole test is considered a pass
160 (or skipped), false if its a failure
161 exit the exit code of the test run, if from a file
163 wait the wait code of the test run, if from a file
164 max total tests which should have been run
166 seen total tests actually seen
167 skip_all if the whole test was skipped, this will
168 contain the reason.
169 ok number of tests which passed
171 (including todo and skips)
172 todo number of todo tests seen
174 bonus number of todo tests which
175 unexpectedly passed
176 skip number of tests skipped
178 So a successful test should have max == seen == ok.
180 There is one final item, the details.
182 details an array ref reporting the result of
184 each test looks like this:
185 $results{details}[$test_num - 1] =
187 { ok => is the test considered ok?
188 actual_ok => did it literally say 'ok'?
189 name => name of the test (if any)
190 diagnostics => test diagnostics (if any)
191 type => 'skip' or 'todo' (if any)
192 reason => reason for the above (if any)
193 };
194 Element 0 of the details is test #1. I tried it with element 1 being
196 #1 and 0 being empty, this is less awkward.
197
199 See examples/mini_harness.plx for an example of use.
200
202 Michael G Schwern "<schwern@pobox.com>", currently maintained by Andy
203 Lester "<andy@petdance.com>".
204
206 Test::Harness
207perl v5.8.8 2001-09-21 Test::Harness::Straps(3pm)