html::mason::tests(3)

NAME

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

SYNOPSIS

use HTML::Mason::Tests;
my $group = HTML::Mason::Tests->new(  name  =>  'name  of
group', description => 'tests something' );
$group->add_test( name => 'foo',
                  description => 'tests foo',
                  component => <<'EOF'
<%args>
$foo => 1
</%args>
<% $foo %>
EOF
                  expect => <<'EOF',
1
EOF
                );

DESCRIPTION

This module is designed to automate as much as possible of
the Mason test suite. It does tasks like write component
files to disk, call them, compare the actual results to
the expected results, and more. In addition, it also is
capable of printing out useful information about test
failures when run in verbose mode. See the ADDITIONAL RUN
MODES section for more information.

It also makes sure that any given group of tests provides
all the information needed to run them (test names, compo
nents and results, etc.).

Now you have no excuse for writing new tests (and that
goes double for me!).

METHODS

new

Takes the following parameters:

� name (required): The name of the entire group of tests.
� description (required): What this group tests.
add_support
Takes the following parameters:
� path (required): The path that other components will expect this compo
nent to be reachable at. All paths are prepended with
the group name. So '/bar' as a support component in
the 'foo' group's ultimate path would be '/foo/bar'.
� component: Text of the support component. This parameter must
have a value unless the skip_component parameter is
true.
� skip_component: If true, then the test harness will not write a compo
nent to disk for this test.
add_test
Takes the following parameters:
� name (required): The name of this test.
� description (required): What this test is testing.
� component (required): Text of the component.
� path (optional): The path that this component should written to. As
with support components, this path is prepended with
the group's name. If no path is given, the value of
the name parameter is used.
� call_path (optional): The path that should be used to call the component.
If none is given, then the value is the same as the
path option, if that exists, otherwise it is /<group
name>/<test name>. If a value is given, it is still
prepended by /<group name>/.
� call_args (optional): The arguments that should be passed to the component,
in list or hash reference form. If none is given, no
arguments are passed.
� parser_params: This is a hash reference of parameters to be passed to
the Parser->new method.
� interp_params: This is a hash reference of parameters to be passed to
the Interp->new method.
� interp: Provide an HTML::Mason::Interp object to be used for
the test.
One of the following three options is required:
� expect: The text expected as a result of calling the compo
nent. This parameter is _not_ required when running
in Create mode.
� expect_error: A regex containing that will be matched against the
error returned from the component execution.
� skip_expect: This causes the component to be run but its output is
ignored. However, if the component execution causes
an error this will cause the test to fail. This is
used in a few situations where it is necessary to just
run a component as part the preparation for another
test.
run
Run the tests in the group.
Class methods
These methods are provided since some tests may need to know these values.
base_path
The base path under which the component root and data directory for the tests are created.
comp_root
Returns the component root directory.
data_dir
Return the data directory
check_output ( actual => $actual_output, expect => $expected_output )
Given the parameters shown above, this method will check to see if the two are equal. If they're not equal, it will print out an error message attempting to highlight the difference.

ADDITIONAL RUN MODES

The following additional modes are available for running
tests.

Verbose mode

To turn this on, set the environment variables MASON_VER
BOSE or MASON_DEBUG as true or run the tests as 'make test
TEST_VERBOSE=1'. In this mode, the "run" method will out
put information about tests as they are run. If a test
fails, then it will also show the cause of the failure.

Debug mode

To turn this on, set the MASON_DEBUG environment variable
to a true value. In this mode, the "run" method will
print detailed information of its actions. This mode
includes the output printed in VERBOSE mode.

Create mode

If the individual tests are run from the command line with
the '--create' flag, then instead of checking the output
of a component, the test harness will simply output its
results. This allows you to cut and paste these results
back into the test file (assuming they are correct!).

docs.sk