Dean Serenevy
and 1 contributors


Test::WWW::Mechanize::Driver - Drive Test::WWW::Mechanize Object Using YAML Configuration Files


 use strict; use warnings;
 use Test::WWW::Mechanize::Driver;
   load => [ glob( "t/*.yaml" ) ]

 use strict; use warnings;
 use Test::WWW::Mechanize::Driver;
 Test::WWW::Mechanize::Driver->new->run; # runs basename($0)*.{yaml.yml,dat}


Write Test::WWW::Mechanize tests in YAML. This module will load the tests make a plan and run the tests. Supports every-page tests, SKIP, TODO, and any object supporting the Test::WWW::Mechanize interface.

This document focuses on the Test::WWW::Mechanize::Driver object and the options it can take. See the Manual for a full description of the test data file format.



 Test::WWW::Mechanize::Driver->new( [ OPTIONS ] )

Number of tests running outside of Driver control. Use this option if your test script perfoirms other tests such as build-up of mock objects.


after_response is a callback sub triggered once per test group (is not triggered by submit_form_ok or other actions) immediately after the initial response is received. If any tests are run in the callback, the after_response_tests option must be set to the number of tests to be run each time so that the driver may make the proper plan.


Base URL for any test uris which are not absolute. If not defined, all test uris must be absolute.


Array ref of file names which should be loaded by the Driver. These tests are loaded at object creation time.


Name of loader package or object with package->load( $file ) method. Defaults to Test::WWW::Mechanize::Driver::YAMLLoader.


Override default mechanize object. The default object is:

 Test::WWW::Mechanize->new(cookie_jar => {})

When true, calling ->run will not print a test plan.


 num tests loaded = $tester->load( test filenames )

Load tests.


 num tests = $tester->tests()

Calculate number of tests currently loaded


 num groups = $tester->test_groups()

Return number of test groups currently loaded



Run each group of tests


 mech = $tester->mechanize()

Return or construct mechanize object




Feed a plan (expected_tests) to Test::Builder if a plan has not yet been given.


 $tester->_run_group( group hash )

Run a group of tests. Performs group-level actions (SKIP, TODO) and tests initial request.


 $tester->_make_initial_request( group hash )

Perform initial GET, POST, ... request. Makes after_response callback if present.


 $tester->_run_test( group hash, test hash )

Run an individual test. Tests (an action) at theis stage should be in one of the following forms:

 { sub => sub { ... do stuff },

 { name => "mechanize method name",
   args => [ array of method arguments ],



Open test files (listed in @{$$x{load}}) and attempt to load each contained document. Each testfile is loaded only once.


 $tester->_load_doc( any doc, id array )

Determine document type and hand off to appropriate loaders.


 $tester->_load_group( non-canonical group hash, id array )

Actually perform test "loading". As test groups are loaded the they are:

 * canonicalized:
     - all tests moved to actions array with one test per entry
     - url misspelling -> uri
     - uri -> $$x{base}/uri if necessary
 * tagged: the test's location in the file is inserted into the test hash


 canon-test (actions) array = $x->_prepare_actions( canon-group hash, actions array, group id array )

Prepare array of actions by:

 * expanding aliases
 * expanding tests


 list of canon-tests = $tester->_expand_tests( canon-group hash, non-canon action item, id array )

Expand a logical action item into possibly many explicit test items. When executed, each test item will increment the test count be exactly 1.

 * prepares argument list


 label = $tester->_test_label( group, name, id list )

Convert id components into something human-readable. For example:

 "[description] content_contains: file basic.yml, doc 3, group 5, test 2.b"



Calculates number of tests attributable to the given group. Accounts for initial requerst, explicit actions, and tests in any callbacks.



Attempt to load test files based on current script name. removes .t or .pl from $0 and globs base*.{yaml,yml,dat}



Configs local to a series of test documents should be cleared after each file is loaded.


Merge a new configuration into the local configuration. called for each hash document in a test configuration file.


Merge a new configuration into the local configuration. called for each hash document in a test configuration file.


test and perhaps implement proper enctype="multipart/form-data" file uploads
HEAD, PUT, DELETE requests
Custom Request headers (probably as a "headers" top level hash item so avoid using that as a custom field)


The original version of this code written by Dean Serenevy while under contract with National Financial Management who graciously allowed me to release it to the public.

 Dean Serenevy


This software is hereby placed into the public domain. If you use this code, a simple comment in your code giving credit and an email letting me know that you find it useful would be courteous but is not required.

The software is provided "as is" without warranty of any kind, either expressed or implied including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.


WWW::Mechanize, Test::WWW::Mechanize