NAME

Test::QuickGen - Utilities for generating random test data

SYNOPSIS

use Test::QuickGen qw(:all);

my $id = id();
my $ascii = ascii_string(10);
my $alphanum = alphanumeric_string(10);
my $utf8 = utf8_string(20);
my $clean = utf8_sanitized(15);

my $rand = between(1, 100);
my $opt = nullable("value");
my $item = pick(qw(a b c));

my $words = words(\&ascii_string, 5);

DESCRIPTION

Test::QuickGen provides a set of utility functions for generating random data, primarily intended for testing purposes. These generators are simple, fast, and have minimal dependencies.

COMMAND LINE TOOL

This module comes bundled with an optional test runner, see quicktest for more details.

IMPORTING

Nothing is exported by default.

Import functions explicitly:

use Test::QuickGen qw(id ascii_string);

Import groups of functions using tags:

use Test::QuickGen qw(:all);
use Test::QuickGen qw(:ascii);
use Test::QuickGen qw(:utf8);
use Test::QuickGen qw(:basic);

• :all

  All available functions.

• :ascii

  ASCII specific functions.

• :utf8

  UTF-8 specific functions.

• :basic

  Simple utils like pick or id.

See source for exact composition of the imports.

FUNCTIONS

id

my $id1 = id();
my $id2 = id();

# $id1 != $id2

Returns a monotonically increasing integer starting from 0.

The counter is process-local and resets each time the program runs.

string_of($n, @chars)

my $str = string_of(10, qw(a b c));

Generates a random string of length $n using the provided list of characters @chars.

• $n must be a non-negative integer.
• At least one character must be provided.

ascii_string($n)

my $str = ascii_string(10);

Generates a random ASCII string length $n.

The character set includes all visible ASCII symbols and characters (in the range 33 to 126).

alphanumeric_string($n)

my $str = alphanumeric_string($n);

Generates a random ASCII string of only alphanumericeric characters of length $n.

utf8_string($n)

my $str = utf8_string(10);

Generates a random UTF-8 string of $n characters.

The generator:

• Includes visible Unicode characters up to code point 0x2FFF.
• Excludes control characters and invalid Unicode ranges.
• Skips surrogate pairs and non-characters.

Note: Because characters may vary in byte length, this function targets character count (not byte length).

utf8_sanitized($n)

my $clean = utf8_sanitized(10);

Generates a UTF-8 string of length $n and removes all non-alphanumericeric characters, retaining only:

• Unicode letters (\p{L})
• Unicode numbers (\p{N})
• Whitespace

If all characters are filtered out, the function retries until a non-empty string is produced.

words($gen, $n, $max_len = 70)

my $str = words(\&string_generator, 5);

Generates a string made up of $n space-separated "words".

Each word is produced by calling the generator function $gen.

• $gen

  A coderef that is called once per word.

  It accepts a single integer argument (the desired length), and returns a string.

  For example:

    sub string_generator {
      my ($len) = @_;
      # return a string of length $len
    }
  

• $max_len

  An optional parameter to set the maximum length (inclusive) of a word. Defaults to 70. Must be a positive number.

• Word generation

  For each of the $n words, a random length between 1 and $max_len is chosen. That length is passed to $gen, which returns the word.

• Output format

  The generated words are joined together with a single space.

Example:

words(\&ascii_string, 3);
# might return: "aZ3 kLm92 Q"

between($min, $max)

my $n = between(1, 10);

Returns a random integer between $min and $max (inclusive).

$min must be <= $max.

nullable($val)

my $value = nullable("data");

Returns either the given value or undef.

25% chance of returning undef, 75% chance of returning the original value. Useful for testing optional fields.

pick(@items)

my $item = pick(qw(a b c));

Returns a random element from the provided list.

If provided an empty list, will return undef.

NOTES

• These functions are not cryptographically secure.
• Randomness uses the builtin function rand, so all limitations that apply to that also apply here. Randomness in this module's functions is uniform in its distribution unless specified otherwise.
• They are intended for testing, fuzzing, and data generation only.

AUTHOR

Antonis Kalou kalouantonis@protonmail.com

CONTRIBUTORS

bas080: https://github.com/bas080

Penfold: Mike Whitaker pendfold@cpan.org

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE for details.