1HTML::Mason::Tests(3) User Contributed Perl DocumentationHTML::Mason::Tests(3)
2
6 HTML::Mason::Tests - Test harness for testing Mason
7
9 use HTML::Mason::Tests;
10 my $group = HTML::Mason::Tests->new( name => 'name of group', description => 'tests something' );
12 $group->add_test( name => 'foo',
13 description => 'tests foo',
14 component => <<'EOF'
15 <%args>
16 $foo => 1
17 </%args>
18 <% $foo %>
19 EOF
20 expect => <<'EOF',
21 1
22 EOF
23 );
24 $group->run;
26
28 This module is designed to automate as much as possible of the Mason
29 test suite. It does tasks like write component files to disk, call
30 them, compare the actual results to the expected results, and more. In
31 addition, it also is capable of printing out useful information about
32 test failures when run in verbose mode. See the ADDITIONAL RUN MODES
33 section for more information.
34 It also makes sure that any given group of tests provides all the
36 information needed to run them (test names, components and results,
37 etc.).
38 Now you have no excuse for writing new tests (and that goes double for
40 me!).
41
43 new
44 Takes the following parameters:
46 * name (required)
48 The name of the entire group of tests.
49 * description (required)
51 What this group tests.
52 * pre_test_cleanup (optional, default=1)
54 If this is true (the default), the component root and data direc‐
55 tory will be deleted both before and after running tests.
56 add_support
58 Takes the following parameters:
60 * path (required)
62 The path that other components will expect this component to be
63 reachable at. All paths are prepended with the group name. So
64 '/bar' as a support component in the 'foo' group's ultimate path
65 would be '/foo/bar'.
66 * component
68 Text of the support component. This parameter must have a value
69 unless the skip_component parameter is true.
70 * skip_component
72 If true, then the test harness will not write a component to disk
73 for this test.
74 add_test
76 Takes the following parameters:
78 * name (required)
80 The name of this test.
81 * description (required)
83 What this test is testing.
84 * component (required)
86 Text of the component.
87 * path (optional)
89 The path that this component should written to. As with support
90 components, this path is prepended with the group's name. If no
91 path is given, it uses call_path, if given, otherwise it uses the
92 name parameter.
93 * call_path (optional)
95 The path that should be used to call the component. If none is
96 given, it will be /<group name>/<test name>. If a value is given,
97 it is still prepended by /<group name>/.
98 * call_args (optional)
100 The arguments that should be passed to the component, in list or
101 hash reference form. If none is given, no arguments are passed.
102 * compiler_params
104 This is a hash reference of parameters to be passed to the Com‐
105 piler->new method.
106 * interp_params
108 This is a hash reference of parameters to be passed to the
109 Interp->new method.
110 * interp
112 Provide an HTML::Mason::Interp object to be used for the test.
113 * todo
115 If this is given, the test will be treated as a todo test, so it
116 will be expected to fail. This should be a string.
117 One of the following three options is required:
119 * expect
121 The text expected as a result of calling the component. This
122 parameter is _not_ required when running in Create mode.
123 * expect_error
125 A regex that will be matched against the error returned from the
126 component execution.
127 * no_warnings
129 If true, this means that the test expects to run without generating
130 any warnings. If warnings are generated, the test fails.
131 * expect_warnings
133 A regex that will be matched against any warnings output when run‐
134 ning the component.
135 * skip_expect
137 This causes the component to be run but its output is ignored.
138 However, if the component execution causes an error this will cause
139 the test to fail. This is used in a few situations where it is
140 necessary to just run a component as part the preparation for
141 another test.
142 run
144 Run the tests in the group.
146 Class methods
148 These methods are provided since some tests may need to know these val‐
150 ues.
151 base_path
153 The base path under which the component root and data directory for the
155 tests are created.
156 comp_root
158 Returns the component root directory.
160 data_dir
162 Return the data directory
164 check_output ( actual => $actual_output, expect => $expected_output )
166 Given the parameters shown above, this method will check to see if the
168 two are equal. If they're not equal, it will print out an error mes‐
169 sage attempting to highlight the difference.
170
172 The following additional modes are available for running tests.
173 Verbose mode
175 To turn this on, set the environment variables MASON_VERBOSE or
177 MASON_DEBUG as true or run the tests as 'make test TEST_VERBOSE=1'. In
178 this mode, the "run" method will output information about tests as they
179 are run. If a test fails, then it will also show the cause of the
180 failure.
181 Debug mode
183 To turn this on, set the MASON_DEBUG environment variable to a true
185 value. In this mode, the "run" method will print detailed information
186 of its actions. This mode includes the output printed in VERBOSE mode.
187 No cleanup mode
189 Setting the MASON_NO_CLEANUP environment variable will tell the module
191 to not clean up generated data from running the tests. This includes
192 the components written to disk and the data directory used during test‐
193 ing. This can be useful when debugging.
194 Create mode
196 If the individual tests are run from the command line with the '--cre‐
198 ate' flag, then instead of checking the output of a component, the test
199 harness will simply output its results. This allows you to cut and
200 paste these results back into the test file (assuming they are cor‐
201 rect!).
202 Running and/or skipping selected tests
204 You can run just some of a test file with the '--tests-to-run' flag or
206 the MASON_TESTS_TO_RUN environment variable. Similarly you can skip
207 specific tests with the '--tests-to-skip' flag or the
208 MASON_TESTS_TO_SKIP environment variable.
209 The value of either flag is a comma-separated list of one or more of
211 [test_file_name:](test_number⎪test_name⎪*)
213 e.g.
215 perl ./01-syntax.t --tests-to-run=3,5
217 MASON_TESTS_TO_SKIP=fake_percent,empty_percents perl ./01-syntax.t
218 MASON_TESTS_TO_RUN="misc:autohandler, request:*, interp:private1" make test
219 Subclassing this module
221 You can run tests with your own Tests.pm subclass using the
223 '--tests-class' flag or the MASON_TESTS_CLASS environment variable.
224 The value is a fully qualified package name that will be loaded before
225 each test file is run. e.g.
226 perl ./01-syntax.t --tests-class=HTML::Mason::Tests::MyTests
228 MASON_TESTS_CLASS=HTML::Mason::Tests::MyTests make test
229 For example, if you have created your own lexer subclass and want to
231 make sure that tests still pass with it, create a Tests subclass that
232 overrides the _make_interp method to use your subclass:
233 sub _make_interp
235 {
236 my ($self, %interp_params) = @_;
237 return HTML::Mason::Interp->new
239 ( lexer_class => HTML::Mason::MyLexer,
240 %interp_params );
241 }
242
244 HTML::Mason
245perl v5.8.8 2007-04-17 HTML::Mason::Tests(3)