/ 
Devel-Maypole-0.1
River stage zero No dependents
/ Devel::Maypole

NAME

Devel::Maypole - support utilities for developing the Maypole stack

SYNOPSIS

# In a test script:

use Test::More tests => 42;

use Devel::Maypole qw/:test/;

my ( $database, $application );

BEGIN { 

    $ENV{MAYPOLE_CONFIG}    = 'config/beerdb.simple.yaml';
    $ENV{MAYPOLE_TEMPLATES} = 't/templates';

    $database = database( ddl  => 'sql/ddl/beerdb.simple.sql',
                          data => 'sql/data/beerdb.simple.sql',
                          );
    
    $application = application( plugins => [ qw( Config::YAML AutoUntaint Relationship ) ],
                                );    
}

use Test::WWW::Mechanize::Maypole $application, $database;

# ----- BEGIN TESTING -----

# frontpage
{   

    my $mech = Test::WWW::Mechanize::Maypole->new;
    $mech->get_ok("http://localhost/beerdb/");
    
    $mech->content_contains( 'This is the frontpage' );
    
    is($mech->ct, "text/html");
    is($mech->status, 200);
}


# --------------------------------------
# In an installation script:

use Maypole::Devel qw/:install/;

# optionally suppress interactive questions:
# $ENV{MAYPOLE_TEMPLATES_INSTALL_PREFIX} = '/usr/local/maypole';

install_templates( 'Maypole::Plugin::Foo', 'distribution-templates-dir/set1', 'set1' );

DESCRIPTION

Builds a database and a simple application driver, ready to use in test scripts for Maypole plugins and components.

EXPORTS

Nothing is exported by default. You can import individual functions, or groups, using these tags:

tag         functions
--------------------------------
:test       database application
:install    install_templates

TESTING UTILITIES

database

Builds and populates an SQLite database in a temporary file, and returns a DBI connection string to the database.

Suitable SQL files are included in the distribution to build a reasonably complex version of the beer database.

Returns a DBI connection string.

Options:

ddl

Name of the SQL DDL (schema) file to use. A couple of suitable files are included at sql/ddl/beerdb.default.sql and sql/ddl/beerdb.simple.sql in this distribution.

data

Name of the SQL data file to use. Suitable files are included at sql/data/beerdb.default.sql and sql/data/beerdb.simple.sql in this distribution.

Set false to not unlink the generated database file. Default true (unlink when script exits).

application

Builds a simple Maypole driver in a temporary file in the current directory.

Returns the package name of the application, which will be MaypoleTestApp_XXXXX where XXXXX are random characters.

Options:

plugins

Arrayref of plugin names, just as you would supply to use Maypole::Application.

See Custom driver code below.

config

Hashref of Maypole options, or a Maypole::Config object. See Configuration below.

unlink

Set false to not unlink the generated application file. Default true (unlink when script exits).

Configuration

You can build up configuration data in your test script, either as a hashref or as a Maypole::Config object, and supply that as the config parameter to application().

Alternatively, include Maypole::Plugin::Config::YAML in the list of plugins, and set $ENV{MAYPOLE_CONFIG} to the path to a config file. See the Maypole::Plugin::Config::YAML docs for details.

This distribution includes a couple of canned config files, in the config subdirectory.

$ENV{MAYPOLE_CONFIG} = 'path/to/config/beerdb.simple.yaml'; 
$ENV{MAYPOLE_CONFIG} = 'path/to/config/beerdb.default.yaml';

You can considerably simplify your config by including Maypole::Plugin::AutoUntaint in the list of plugins - the supplied config files assume this.

The supplied configs also assume Maypole::Plugin::Relationship is included in the plugins.

Custom driver code

If you need to add custom code to the application, you could put the code in a plugin, and supply the name of the plugin to plugins.

Alternatively, eval code in your test script, e.g. from 01.simple.t:

# For testing classmetadata
eval <<CODE;
    sub $application\::Beer::classdata: Exported {};
    sub $application\::Beer::list_columns  { return qw/score name price style brewery url/};
CODE

die $@ if $@;

INSTALLATION SUPPORT

install_templates( $for, $from, [ $to ] )

Installs a set of templates.

This function is intended to be called from a command line script, such as a Makefile.PL or Build.PL script. It will ask the user to confirm install locations, unless $ENV{MAYPOLE_TEMPLATES_INSTALL_PREFIX} is defined, in which case that location will be used as the root of the install location.

On Unix-like systems, the default install root is /usr/local/maypole/templates. On Windows, C:/Program Files/Maypole/templates.

$for should be the name of a package. This will be converted into a subdirectory, e.g. Maypole::Plugin::Foo becomes plugin/foo.

$from is the relative path to the templates directory in your distribution, e.g. templates.

$to is an optional subdirectory to install to. So if you say

install_templates( 'Maypole::Plugin::Foo', 'templates/set1', 'set1' )

the templates will be installed in /usr/local/maypole/templates/plugin/foo/set1.

TODO

Canned tests e.g. run_standard_tests( $application )

Complex schema, with sufficient data for paging.

Add more template sets.

Support for other RDBMS's (easy enough to implement, patches welcome).

AUTHOR

David Baird, <cpan@riverside-cms.co.uk>

BUGS

Please report any bugs or feature requests to bug-maypole-testtools@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Maypole-TestTools. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2005 David Baird, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.