Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTML::Mason::Tests(3) User Contributed Perl DocumentationHTML::Mason::Tests(3)

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

	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'
	$foo =>	1
	<% $foo	%>
			  expect => <<'EOF',


       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, components and results,

       Now you have no excuse for writing new tests (and that goes double for

       Takes the following parameters:

       o   name	(required)

	   The name of the entire group	of tests.

       o   description (required)

	   What	this group tests.

       o   pre_test_cleanup (optional, default=1)

	   If this is true (the	default), the component	root and data
	   directory will be deleted both before and after running tests.

       Takes the following parameters:

       o   path	(required)

	   The path that other components will expect this component 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'.

       o   component

	   Text	of the support component.  This	parameter must have a value
	   unless the skip_component parameter is true.

       o   skip_component

	   If true, then the test harness will not write a component to	disk
	   for this test.

       Takes the following parameters:

       o   name	(required)

	   The name of this test.

       o   description (required)

	   What	this test is testing.

       o   component (required)

	   Text	of the component.

       o   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, it uses call_path, if	given, otherwise it uses the
	   name	parameter.

       o   call_path (optional)

	   The path that should	be used	to call	the component.	If none	is
	   given, it will be /<group name>/<test name>.	 If a value is given,
	   it is still prepended by /<group name>/.

       o   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.

       o   compiler_params

	   This	is a hash reference of parameters to be	passed to the
	   Compiler->new method.

       o   interp_params

	   This	is a hash reference of parameters to be	passed to the
	   Interp->new method.

       o   interp

	   Provide an HTML::Mason::Interp object to be used for	the test.

       o   todo

	   If this is given, the test will be treated as a todo	test, so it
	   will	be expected to fail.  This should be a string.

       One of the following three options is required:

       o   expect

	   The text expected as	a result of calling the	component.  This
	   parameter is	_not_ required when running in Create mode.

       o   expect_error

	   A regex that	will be	matched	against	the error returned from	the
	   component execution.

       o   no_warnings

	   If true, this means that the	test expects to	run without generating
	   any warnings.  If warnings are generated, the test fails.

       o   expect_warnings

	   A regex that	will be	matched	against	any warnings output when
	   running the component.

       o   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 the tests in	the group.

   Class methods
       These methods are provided since	some tests may need to know these

       The base	path under which the component root and	data directory for the
       tests are created.

       Returns the component root directory.

       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.

       The following additional	modes are available for	running	tests.

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

   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.

   No cleanup mode
       Setting the MASON_NO_CLEANUP environment	variable will tell the module
       to not clean up generated data from running the tests.  This includes
       the components written to disk and the data directory used during
       testing.	 This can be useful when debugging.

   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

   Running and/or skipping selected tests
       You can run just	some of	a test file with the '--tests-to-run' flag or
       the MASON_TESTS_TO_RUN environment variable. Similarly you can skip
       specific	tests with the '--tests-to-skip' flag or the
       MASON_TESTS_TO_SKIP environment variable.

       The value of either flag	is a comma-separated list of one or more of



	   perl	./01-syntax.t --tests-to-run=3,5
	   MASON_TESTS_TO_SKIP=fake_percent,empty_percents perl	./01-syntax.t
	   MASON_TESTS_TO_RUN="misc:autohandler, request:*, interp:private1" make test

   Subclassing this module
       You can run tests with your own	subclass using the
       '--tests-class' flag or the MASON_TESTS_CLASS environment variable.
       The value is a fully qualified package name that	will be	loaded before
       each test file is run.  e.g.

	   perl	./01-syntax.t --tests-class=HTML::Mason::Tests::MyTests
	   MASON_TESTS_CLASS=HTML::Mason::Tests::MyTests make test

       For example, if you have	created	your own lexer subclass	and want to
       make sure that tests still pass with it,	create a Tests subclass	that
       overrides the _make_interp method to use	your subclass:

	   sub _make_interp
	       my ($self, %interp_params) = @_;

	       return HTML::Mason::Interp->new
		   ( lexer_class => HTML::Mason::MyLexer,
		     %interp_params );

perl v5.24.1			  2014-11-15		 HTML::Mason::Tests(3)


Want to link to this manual page? Use this URL:

home | help