NAME

Test::Override::UserAgent::Manual::ConfigurationPackage - Creating configuration packages

WHAT IS A CONFIGURATION PACKAGE?

A "configuration package" is a normal perl package that Test::Override::UserAgent has imported a special set of symbols into and makes it easy to reuse override definitions in different test files.

BOILERPLATE

To create a configuration package, just import Test::Override::UserAgent specifying it is for configuration:

package My::Overrides;

use Test::Override::UserAgent 0.001 for => 'configuration';

# ... configuration here

1;

If you would like to setup your configuration module to give a nice error message, you may use:

package My::Overrides::Nice;

BEGIN {
    if (!eval 'use Test::Override::UserAgent 0.001; 1;') {
        die "Test::Override::UserAgent >= 0.001 must be installed: $@";
    }

    # Import for configuration
    Test::Override::UserAgent->import(for => 'configuration');
}

# ... configuration here

1;

WHAT IS IMPORTED

When then module is imported for configuration, the following subroutines are imported into the package:

allow_live

This is the same as the method allow_live_requests in Test::Override::UserAgent but acts on the configuration in the package. If no arguments are provided, then live requests are enabled.

# Allow live requests
allow_live(1);

configuration

This is a special method that returns the instance of Test::Override::UserAgent for this package.

override_for

Added in version 0.003; be sure to require this version for this feature.

This is a very convenient function to set some defaults for an entire block of code. This function takes the exact same arguments as override_request except the subroutine reference at the end is a block that will be built with the default arguments to all calls of override_request within. Calls made to override_for within an override_for block will extend the current scope's defaults with those provided. The main scope begins with no defaults.

override_for host => 'localhost', sub {
    override_request path => '/', sub {
        # ... only for host localhost and path /
    };

    # Make an easy REST URL
    override_for path => '/rest', sub {
        # GET
        override_request method => 'GET'   , sub { ... };
        # POST
        override_request method => 'POST'  , sub { ... };
        # DELETE
        override_request method => 'DELETE', sub { ... };
        # PUT
        override_request method => 'PUT'   , sub { ... };
    };
};

override_request

This is the same as the method in Test::Override::UserAgent but acts on the configuration in the package.

override_request path => '/', sub {
    # ...
};

EXAMPLE

A full example of a configuration file:

package My::Overrides;

use Test::Override::UserAgent 0.001 for => 'configuration';

# No live requests for us
allow_live(0);

# The root directory is always forbidden for localhost
override_request
    host => 'localhost',
    path => '/',
    sub { [403, ['Content-Type' => 'text/plain'], ['Forbidden!'] };

1;

USING IN A TEST

To use a configuration package simply use it in the test file. Then using Package::Name->configuration will return the instance object so the configuration may be installed in a user agent or into the scope.

#!/usr/bin/env perl -T

use My::Overrides;

# Install into the current scope
my $scope = My::Overrides->configuration->install_in_scope;

# ... tests

exit 0;