{
    "mode": "perldoc",
    "parameter": "HTML::Mason::Tests",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/HTML%3A%3AMason%3A%3ATests/json",
    "generated": "2026-06-16T10:43:40Z",
    "synopsis": "use HTML::Mason::Tests;\nmy $group = HTML::Mason::Tests->new( name => 'name of group', description => 'tests something' );\n$group->addtest( name => 'foo',\ndescription => 'tests foo',\ncomponent => <<'EOF'\n<%args>\n$foo => 1\n</%args>\n<% $foo %>\nEOF\nexpect => <<'EOF',\n1\nEOF\n);\n$group->run;",
    "sections": {
        "NAME": {
            "content": "HTML::Mason::Tests - Test harness for testing Mason\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use HTML::Mason::Tests;\n\nmy $group = HTML::Mason::Tests->new( name => 'name of group', description => 'tests something' );\n$group->addtest( name => 'foo',\ndescription => 'tests foo',\ncomponent => <<'EOF'\n<%args>\n$foo => 1\n</%args>\n<% $foo %>\nEOF\nexpect => <<'EOF',\n1\nEOF\n);\n\n$group->run;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module is designed to automate as much as possible of the Mason test suite. It does tasks\nlike write component files to disk, call them, compare the actual results to the expected\nresults, and more. In addition, it also is capable of printing out useful information about test\nfailures when run in verbose mode. See the ADDITIONAL RUN MODES section for more information.\n\nIt also makes sure that any given group of tests provides all the information needed to run them\n(test names, components and results, etc.).\n\nNow you have no excuse for writing new tests (and that goes double for me!).\n",
            "subsections": []
        },
        "METHODS": {
            "content": "new\nTakes the following parameters:\n\n*   name (required)\n\nThe name of the entire group of tests.\n\n*   description (required)\n\nWhat this group tests.\n\n*   pretestcleanup (optional, default=1)\n\nIf this is true (the default), the component root and data directory will be deleted both\nbefore and after running tests.\n\naddsupport\nTakes the following parameters:\n\n*   path (required)\n\nThe path that other components will expect this component to be reachable at. All paths are\nprepended with the group name. So '/bar' as a support component in the 'foo' group's\nultimate path would be '/foo/bar'.\n\n*   component\n\nText of the support component. This parameter must have a value unless the skipcomponent\nparameter is true.\n\n*   skipcomponent\n\nIf true, then the test harness will not write a component to disk for this test.\n\naddtest\nTakes the following parameters:\n\n*   name (required)\n\nThe name of this test.\n\n*   description (required)\n\nWhat this test is testing.\n\n*   component (required)\n\nText of the component.\n\n*   path (optional)\n\nThe path that this component should written to. As with support components, this path is\nprepended with the group's name. If no path is given, it uses callpath, if given, otherwise\nit uses the name parameter.\n\n*   callpath (optional)\n\nThe path that should be used to call the component. If none is given, it will be /<group\nname>/<test name>. If a value is given, it is still prepended by /<group name>/.\n\n*   callargs (optional)\n\nThe arguments that should be passed to the component, in list or hash reference form. If\nnone is given, no arguments are passed.\n\n*   compilerparams\n\nThis is a hash reference of parameters to be passed to the Compiler->new method.\n\n*   interpparams\n\nThis is a hash reference of parameters to be passed to the Interp->new method.\n\n*   interp\n\nProvide an HTML::Mason::Interp object to be used for the test.\n\n*   todo\n\nIf this is given, the test will be treated as a todo test, so it will be expected to fail.\nThis should be a string.\n\nOne of the following three options is required:\n\n*   expect\n\nThe text expected as a result of calling the component. This parameter is not required\nwhen running in Create mode.\n\n*   expecterror\n\nA regex that will be matched against the error returned from the component execution.\n\n*   nowarnings\n\nIf true, this means that the test expects to run without generating any warnings. If\nwarnings are generated, the test fails.\n\n*   expectwarnings\n\nA regex that will be matched against any warnings output when running the component.\n\n*   skipexpect\n\nThis causes the component to be run but its output is ignored. However, if the component\nexecution causes an error this will cause the test to fail. This is used in a few situations\nwhere it is necessary to just run a component as part the preparation for another test.\n\nrun\nRun the tests in the group.\n",
            "subsections": [
                {
                    "name": "Class methods",
                    "content": "These methods are provided since some tests may need to know these values.\n\nbasepath\nThe base path under which the component root and data directory for the tests are created.\n\ncomproot\nReturns the component root directory.\n\ndatadir\nReturn the data directory\n\ncheckoutput ( actual => $actualoutput, expect => $expectedoutput )\nGiven the parameters shown above, this method will check to see if the two are equal. If they're\nnot equal, it will print out an error message attempting to highlight the difference.\n"
                }
            ]
        },
        "ADDITIONAL RUN MODES": {
            "content": "The following additional modes are available for running tests.\n",
            "subsections": [
                {
                    "name": "Verbose mode",
                    "content": "To turn this on, set the environment variables MASONVERBOSE or MASONDEBUG as true or run the\ntests as 'make test TESTVERBOSE=1'. In this mode, the \"run\" method will output information\nabout tests as they are run. If a test fails, then it will also show the cause of the failure.\n"
                },
                {
                    "name": "Debug mode",
                    "content": "To turn this on, set the MASONDEBUG environment variable to a true value. In this mode, the\n\"run\" method will print detailed information of its actions. This mode includes the output\nprinted in VERBOSE mode.\n"
                },
                {
                    "name": "No cleanup mode",
                    "content": "Setting the MASONNOCLEANUP environment variable will tell the module to not clean up generated\ndata from running the tests. This includes the components written to disk and the data directory\nused during testing. This can be useful when debugging.\n"
                },
                {
                    "name": "Create mode",
                    "content": "If the individual tests are run from the command line with the '--create' flag, then instead of\nchecking the output of a component, the test harness will simply output its results. This allows\nyou to cut and paste these results back into the test file (assuming they are correct!).\n\nRunning and/or skipping selected tests\nYou can run just some of a test file with the '--tests-to-run' flag or the MASONTESTSTORUN\nenvironment variable. Similarly you can skip specific tests with the '--tests-to-skip' flag or\nthe MASONTESTSTOSKIP environment variable.\n\nThe value of either flag is a comma-separated list of one or more of\n\n[testfilename:](testnumber|testname|*)\n\ne.g.\n\nperl ./01-syntax.t --tests-to-run=3,5\nMASONTESTSTOSKIP=fakepercent,emptypercents perl ./01-syntax.t\nMASONTESTSTORUN=\"misc:autohandler, request:*, interp:private1\" make test\n"
                },
                {
                    "name": "Subclassing this module",
                    "content": "You can run tests with your own Tests.pm subclass using the '--tests-class' flag or the\nMASONTESTSCLASS environment variable. The value is a fully qualified package name that will be\nloaded before each test file is run. e.g.\n\nperl ./01-syntax.t --tests-class=HTML::Mason::Tests::MyTests\nMASONTESTSCLASS=HTML::Mason::Tests::MyTests make test\n\nFor example, if you have created your own lexer subclass and want to make sure that tests still\npass with it, create a Tests subclass that overrides the makeinterp method to use your\nsubclass:\n\nsub makeinterp\n{\nmy ($self, %interpparams) = @;\n\nreturn HTML::Mason::Interp->new\n( lexerclass => HTML::Mason::MyLexer,\n%interpparams );\n}\n"
                }
            ]
        }
    },
    "summary": "HTML::Mason::Tests - Test harness for testing Mason",
    "flags": [],
    "examples": [],
    "see_also": []
}