NAME

Test::Sims - Helps build semi-random data for testing

SYNOPSIS

package My::Sims;

use Test::Sims;

# Creates rand_name() and exported on demand.
make_rand name => [
    qw(Mal Zoe Jayne Kaylee Inara River Simon Wash Zoe Book)
];

# Automatically exported
sub sim_character {
    my %defaults = (
        name   => rand_name(),
        series => "Firefly",
    );

    require Character;
    return Character->new(
        %defaults, @_;
    );
}

DESCRIPTION

THIS IS AN EARLY RELEASE! While very well tested behaviors may change. The interface is not stable.

This is a module to help building semi-random data for testing and to create large, nested, interesting data structures.

This module contains no new assertions, but it does tie in with Test::Builder.

It does two things. It contains functions which make generating random data easier and it allows you to write repeatable, yet random, test data.

make_rand()

my $code = make_rand $name => \@list;
my $code = make_rand $name => sub { ... };

Creates a subroutine called <rand_$name> and exports it on request.

If a @list is given it will generate a subroutine which returns elements out of @list at random. It takes min and max arguments to control how many.

my @items = rand_$name(
    min => $min_random_items,
    max => $max_random_items
);

min and max both default to 1. So by default you get 1 item.

If a subroutine is given it will simply give that routine a name. This is just to get the convenience of adding it to the exports.

Also adds it to a "rand" export tag.

{
    package Sim::Firefly;

    make_rand crew => [
        qw(Zoe Wash Mal River Simon Book Jayne Kaylee Inara)
    ];
}

...later...

{
    use Sim::Firefly ":rand";

    my $crew = rand_crew;             # 1 name
    my @crew = rand_crew( max => 3 ); # 1, 2 or 3 names
}

export_sims()

export_sims();

A utility function which causes your module to export all the functions called <sims_*>. It also creates an export tag called "sims".

You should call this at the end of your Sim package.

Controlling randomness

You can control the random seed used by Test::Sims by setting the TEST_SIMS_SEED environment variable. This is handy to make test runs repeatable.

TEST_SIMS_SEED=12345 perl -Ilib t/some_test.t

Test::Sims will output the seed used at the end of each test run. If the test failed it will be visible to the user, otherwise it will be a TAP comment and only visible if the test is run verbosely.

If having new data every run is too chaotic for you, you can set TEST_SIMS_SEED to something which will remain fixed during a development session. Perhaps the PID of your shell or your uid or the date (20090704, for example).

sim functions

Test::Sims doesn't do anything with functions named sim_* but export them. Generally we recommend they're written like so:

sub sim_thing {
    my %defaults = (
        name        => rand_name(),
        age         => rand_age(),
        motto       => rand_text(),
        picture     => rand_image(),
    );

    return Thing->new( %defaults, @_ );
}

This way you can get a completely random Thing.

my $thing = sim_thing();

Or you can lock down the bits you need leaving the rest to float free.

# Joe's motto and picture remain random
my $joe = sim_thing(
    name => "Joe",
    age  => 64
);

EXAMPLE

Here's an example of making a simple package to generate random dates.

package Sim::Date;

use strict;
use warnings;

require DateTime;
use Test::Sims;

make_rand year  => [1800..2100];

sub sim_datetime {
    my %args = @_;

    my $year = $args{year} || rand_year();
    my $date = DateTime->new( year => $year );

    my $days_in_year = $date->is_leap_year ? 366 : 365;
    my $secs = rand( $days_in_year * 24 * 60 * 60 );
    $date->add( seconds => $secs );

    $date->set( %args );

    return $date;
}

export_sims();

And then using it.

use Sim::Date;

# Random date.
my $date = sim_datetime;

# Random date in July 2009
my $date = sim_datetime(
    year  => 2009,
    month => 7,
);

ENVIRONMENT

TEST_SIMS_SEED

If defined its value will be used to make tests repeatable. See "Controlling randomness".

SEE ALSO

"Generating Test Data with The Sims" http://schwern.org/talks/Generating%20Test%20Data%20With%20The%20Sims.pdf is a set of slides outlining the Sims testing technique which this module is supporting.

Data::Random for common rand_* routines.

Data::Generate to generate random data from a set of rules.

SOURCE

The source code repository can be found at http://github.com/schwern/Test-Sims.

The latest release can be found at http://search.cpan.org/dist/Test-Sims.

BUGS

Please report bugs, problems, rough corners, feedback and suggestions to http://github.com/schwern/Test-Sims/issues.

Report early, report often.

THANKS

Thanks go to the folks at Blackstar and Grant Street Group for helping to develop this technique.

LICENSE and COPYRIGHT

Copyright 2009 Michael G Schwern >schwern@pobox.com<

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

See http://www.perl.com/perl/misc/Artistic.html