NAME

Test::MockRandom - Replaces random number generation with non-random number generation

SYNOPSIS

use Test::MockRandom;

# functional
srand(0.5);
if ( rand() == 0.5 ) { print "good guess!" };

# object-oriented
my $nrng = Test::MockRandom->new(0.42);
$nrng->rand(); # returns 0.42

# using a seed-array
$nrng->srand(0.23, 0.34, oneish() );
$nrng->rand(); # returns 0.23
$nrng->rand(); # returns 0.34
$nrng->rand(); # returns a number just barely less than one
$nrng->rand(); # returns 0, as the seed array is empty

# mask rand in another package
export_rand_to( 'Some::Other::Package' );

DESCRIPTION

This perhaps ridiculous-seeming module was created to test routines that manipulate random numbers by providing a known output from rand. It exports srand and rand, hijacking the system function calls. Given an array of seeds, it will return each in turn. After seeded random numbers are exhausted, it will always return 0. It can also be used to generate objects, with each object maintaining its own distinct seed array.

Seed numbers must follow the expected output from rand with no arguments -- they must be between 0 (inclusive) and 1 (exclusive). In order to facilitate generating a nearly-one number, this module exports the function oneish, which returns a number just fractionally less than one. This module also exports the function export_rand_to which can be used to hijack rand in another namespace (e.g., a class being tested).

If for some reason you want to use this module without hijacking the built-in functions (i.e. objects only), you can use the module without any imported functions with use Test::MockRandom qw();.

USAGE

new

$obj = new( LIST OF SEEDS );

Returns a new Test::MockRandom object with the specified list of seeds.

srand

srand( LIST OF SEEDS );
$obj->srand( LIST OF SEEDS);

If called as a bare function call or package method, sets the seed list for bare/package calls to rand. If called as an object method, sets the seed list for that object.

rand

$rv = rand();
$rv = $obj->rand();
$rv = rand(3);

If called as a bare or package function, returns the next value from the package seed list. If called as an object method, returns the next value from the object seed list.

If rand is called with a numeric argument, it follows the same behavior as the built-in function -- it multiplies the argument with the next value from the seed array (resulting in a random fractional value between 0 and the argument, just like the built-in). If the argument is 0, undef, or non-numeric, it is treated as if the argument is 1.

Using this with an argument in testing may be complicated, as limits in floating point precision mean that direct numeric comparisons are not reliable. E.g.

srand(1/3);
rand(3);       # does this return 1.0 or .999999999 etc.

export_rand_to

export_rand_to( 'Some::Other::Package' );

As the name implies, this function exports rand into another package namespace. This is useful in testing object which call rand. E.g.,

package Some::Class;
sub foo { print rand(); }

package main;
use Test::MockRandom;
export_rand_to( 'Some::Class' );
srand(0.5);
Some::Class::foo();   # prints "0.5"

Note that this uses the Test::MockRandom package globals, not class objects. So a call to srand in this package still affects the results of rand called in Some::Class.

Using this on an object oriented package that also defines a rand method will likely cause major errors.

oneish

srand( oneish() );
if ( rand() == oneish() ) { print "It's almost one." };

A utility function to return a nearly-one value. Equal to ( 2^32 - 1 ) / 2^32. Useful in srand and test functions.

BUGS

Please report bugs using the CPAN Request Tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-MockRandom

AUTHOR

David A. Golden (DAGOLDEN)
dagolden@dagolden.com
http://dagolden.com/

COPYRIGHT

Copyright (c) 2004 by David A. Golden

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

Test::MockObject

Test::MockModule

cpanm Test::MockRandom

perl -MCPAN -e shell
install Test::MockRandom