1HTML::Mason::Tests(3) User Contributed Perl DocumentationHTML::Mason::Tests(3)
2
3
4

NAME

6       HTML::Mason::Tests - Test harness for testing Mason
7

SYNOPSIS

9        use HTML::Mason::Tests;
10
11        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
25        $group->run;
26

DESCRIPTION

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
35       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
39       Now you have no excuse for writing new tests (and that goes double for
40       me!).
41

METHODS

43   new
44       Takes the following parameters:
45
46       •   name (required)
47
48           The name of the entire group of tests.
49
50       •   description (required)
51
52           What this group tests.
53
54       •   pre_test_cleanup (optional, default=1)
55
56           If this is true (the default), the component root and data
57           directory will be deleted both before and after running tests.
58
59   add_support
60       Takes the following parameters:
61
62       •   path (required)
63
64           The path that other components will expect this component to be
65           reachable at.  All paths are prepended with the group name.  So
66           '/bar' as a support component in the 'foo' group's ultimate path
67           would be '/foo/bar'.
68
69       •   component
70
71           Text of the support component.  This parameter must have a value
72           unless the skip_component parameter is true.
73
74       •   skip_component
75
76           If true, then the test harness will not write a component to disk
77           for this test.
78
79   add_test
80       Takes the following parameters:
81
82       •   name (required)
83
84           The name of this test.
85
86       •   description (required)
87
88           What this test is testing.
89
90       •   component (required)
91
92           Text of the component.
93
94       •   path (optional)
95
96           The path that this component should written to.  As with support
97           components, this path is prepended with the group's name.  If no
98           path is given, it uses call_path, if given, otherwise it uses the
99           name parameter.
100
101       •   call_path (optional)
102
103           The path that should be used to call the component.  If none is
104           given, it will be /<group name>/<test name>.  If a value is given,
105           it is still prepended by /<group name>/.
106
107       •   call_args (optional)
108
109           The arguments that should be passed to the component, in list or
110           hash reference form. If none is given, no arguments are passed.
111
112       •   compiler_params
113
114           This is a hash reference of parameters to be passed to the
115           Compiler->new method.
116
117       •   interp_params
118
119           This is a hash reference of parameters to be passed to the
120           Interp->new method.
121
122       •   interp
123
124           Provide an HTML::Mason::Interp object to be used for the test.
125
126       •   todo
127
128           If this is given, the test will be treated as a todo test, so it
129           will be expected to fail.  This should be a string.
130
131       One of the following three options is required:
132
133       •   expect
134
135           The text expected as a result of calling the component.  This
136           parameter is _not_ required when running in Create mode.
137
138       •   expect_error
139
140           A regex that will be matched against the error returned from the
141           component execution.
142
143       •   no_warnings
144
145           If true, this means that the test expects to run without generating
146           any warnings.  If warnings are generated, the test fails.
147
148       •   expect_warnings
149
150           A regex that will be matched against any warnings output when
151           running the component.
152
153       •   skip_expect
154
155           This causes the component to be run but its output is ignored.
156           However, if the component execution causes an error this will cause
157           the test to fail.  This is used in a few situations where it is
158           necessary to just run a component as part the preparation for
159           another test.
160
161   run
162       Run the tests in the group.
163
164   Class methods
165       These methods are provided since some tests may need to know these
166       values.
167
168   base_path
169       The base path under which the component root and data directory for the
170       tests are created.
171
172   comp_root
173       Returns the component root directory.
174
175   data_dir
176       Return the data directory
177
178   check_output ( actual => $actual_output, expect => $expected_output )
179       Given the parameters shown above, this method will check to see if the
180       two are equal.  If they're not equal, it will print out an error
181       message attempting to highlight the difference.
182

ADDITIONAL RUN MODES

184       The following additional modes are available for running tests.
185
186   Verbose mode
187       To turn this on, set the environment variables MASON_VERBOSE or
188       MASON_DEBUG as true or run the tests as 'make test TEST_VERBOSE=1'.  In
189       this mode, the "run" method will output information about tests as they
190       are run.  If a test fails, then it will also show the cause of the
191       failure.
192
193   Debug mode
194       To turn this on, set the MASON_DEBUG environment variable to a true
195       value.  In this mode, the "run" method will print detailed information
196       of its actions.  This mode includes the output printed in VERBOSE mode.
197
198   No cleanup mode
199       Setting the MASON_NO_CLEANUP environment variable will tell the module
200       to not clean up generated data from running the tests.  This includes
201       the components written to disk and the data directory used during
202       testing.  This can be useful when debugging.
203
204   Create mode
205       If the individual tests are run from the command line with the
206       '--create' flag, then instead of checking the output of a component,
207       the test harness will simply output its results.  This allows you to
208       cut and paste these results back into the test file (assuming they are
209       correct!).
210
211   Running and/or skipping selected tests
212       You can run just some of a test file with the '--tests-to-run' flag or
213       the MASON_TESTS_TO_RUN environment variable. Similarly you can skip
214       specific tests with the '--tests-to-skip' flag or the
215       MASON_TESTS_TO_SKIP environment variable.
216
217       The value of either flag is a comma-separated list of one or more of
218
219          [test_file_name:](test_number|test_name|*)
220
221       e.g.
222
223           perl ./01-syntax.t --tests-to-run=3,5
224           MASON_TESTS_TO_SKIP=fake_percent,empty_percents perl ./01-syntax.t
225           MASON_TESTS_TO_RUN="misc:autohandler, request:*, interp:private1" make test
226
227   Subclassing this module
228       You can run tests with your own Tests.pm subclass using the
229       '--tests-class' flag or the MASON_TESTS_CLASS environment variable.
230       The value is a fully qualified package name that will be loaded before
231       each test file is run.  e.g.
232
233           perl ./01-syntax.t --tests-class=HTML::Mason::Tests::MyTests
234           MASON_TESTS_CLASS=HTML::Mason::Tests::MyTests make test
235
236       For example, if you have created your own lexer subclass and want to
237       make sure that tests still pass with it, create a Tests subclass that
238       overrides the _make_interp method to use your subclass:
239
240           sub _make_interp
241           {
242               my ($self, %interp_params) = @_;
243
244               return HTML::Mason::Interp->new
245                   ( lexer_class => HTML::Mason::MyLexer,
246                     %interp_params );
247           }
248
249
250
251perl v5.36.0                      2022-07-22             HTML::Mason::Tests(3)
Impressum