NAME

Test::Ability

ABSTRACT

Property-Based Testing for Perl 5

SYNOPSIS

  package main;

  use Test::Ability;

  my $t = Test::Ability->new;

DESCRIPTION

This package provides methods for generating values and test-cases, prodiving a framework for performing property-based testing.

INTEGRATES

This package integrates behaviors from:

Data::Object::Role::Buildable

Data::Object::Role::Stashable

LIBRARIES

This package uses type constraints from:

Types::Standard

SCENARIOS

This package supports the following scenarios:

stash

  # given: synopsis

  $t->stash(direction => sub {
    my ($self) = @_;

    {
      move => ('forward', 'reverse')[rand(1)],
      time => time
    }
  });

The package provides a stash object for default and user-defined value generators. You can easily extend the default generators by adding your own. Once defined, custom generators can be specified in the gen-spec (generator specification) arrayref provided to the test method (and others).

ATTRIBUTES

This package has the following attributes:

arguments

  arguments(ArrayRef)

This attribute is read-only, accepts (ArrayRef) values, and is optional.

invocant

  invocant(Object)

This attribute is read-only, accepts (Object) values, and is optional.

METHODS

This package implements the following methods:

array

  array(Maybe[Int] $min, Maybe[Int] $max) : ArrayRef

The array method returns a random array reference.

array example #1

  # given: synopsis

  $t->array;

array_object

  array_object(Maybe[Int] $min, Maybe[Int] $max) : Object

The array_object method returns a random array object.

array_object example #1

  # given: synopsis

  $t->array_object;

choose

  choose(ArrayRef[ArrayRef] $args) : Any

The choose method returns a random value from the set of specified generators.

choose example #1

  # given: synopsis

  $t->choose([['datetime'], ['words', [2,3]]]);

code

  code(Maybe[Int] $min, Maybe[Int] $max) : CodeRef

The code method returns a random code reference.

code example #1

  # given: synopsis

  $t->code;

code_object

  code_object(Maybe[Int] $min, Maybe[Int] $max) : Object

The code_object method returns a random code object.

code_object example #1

  # given: synopsis

  $t->code_object;

date

  date(Maybe[Str] $min, Maybe[Str] $max) : Str

The date method returns a random date.

date example #1

  # given: synopsis

  $t->date;

datetime

  datetime(Maybe[Str] $min, Maybe[Str] $max) : Str

The datetime method returns a random date and time.

datetime example #1

  # given: synopsis

  $t->datetime;

hash

  hash(Maybe[Int] $min, Maybe[Int] $max) : HashRef

The hash method returns a random hash reference.

hash example #1

  # given: synopsis

  $t->hash;

hash_object

  hash_object(Maybe[Int] $min, Maybe[Int] $max) : Object

The hash_object method returns a random hash object.

hash_object example #1

  # given: synopsis

  $t->hash_object;

maybe

  maybe(ArrayRef[ArrayRef] $args) : Any

The maybe method returns a random choice using the choose method, or the undefined value.

maybe example #1

  # given: synopsis

  $t->maybe([['date'], ['time']]);

number

  number(Maybe[Int] $min, Maybe[Int] $max) : Int

The number method returns a random number.

number example #1

  # given: synopsis

  $t->number;

number_object

  number_object(Maybe[Int] $min, Maybe[Int] $max) : Object

The number_object method returns a random number object.

number_object example #1

  # given: synopsis

  $t->number_object;

object

  object() : Object

The object method returns a random object.

object example #1

  # given: synopsis

  $t->object;

regexp

  regexp(Maybe[Str] $exp) : RegexpRef

The regexp method returns a random regexp.

regexp example #1

  # given: synopsis

  $t->regexp;

regexp_object

  regexp_object(Maybe[Str] $exp) : Object

The regexp_object method returns a random regexp object.

regexp_object example #1

  # given: synopsis

  $t->regexp_object;

scalar

  scalar(Maybe[Int] $min, Maybe[Int] $max) : Ref

The scalar method returns a random scalar reference.

scalar example #1

  # given: synopsis

  $t->scalar;

scalar_object

  scalar_object(Maybe[Int] $min, Maybe[Int] $max) : Object

The scalar_object method returns a random scalar object.

scalar_object example #1

  # given: synopsis

  $t->scalar_object;

string

  string(Maybe[Int] $min, Maybe[Int] $max) : Str

The string method returns a random string.

string example #1

  # given: synopsis

  $t->string;

string_object

  string_object(Maybe[Int] $min, Maybe[Int] $max) : Object

The string_object method returns a random string object.

string_object example #1

  # given: synopsis

  $t->string_object;

test

  test(Str $name, Int $cycles, ArrayRef[ArrayRef] $spec, CodeRef $callback) : Undef

The test method generates subtests using "subtest" in Test::More, optionally generating and passing random values to each iteration as well as a Data::Object::Try object for easy execution of callbacks and interception of exceptions. This callback expected should have the signature ($tryable, @arguments) where @arguments gets assigned the generated values in the order specified. The callback must return the $tryable object, which is called for you automatically, executing the subtest logic you've implemented.

test example #1

  # given: synopsis

  # use Test::More;

  sub is_an_adult {
    my ($age) = @_;

    $age >= 18;
  }

  $t->test('is_an_adult', 100, [['number', [10, 30]]], sub {
    my ($tryable, $age) = @_;

    $tryable->call(sub {
      if ($age >= 18) {
        ok is_an_adult($age),
          "age is $age, is an adult";
      }
      else {
        ok !is_an_adult($age),
          "age is $age, is not an adult";
      }
    });

    $tryable
  });

time

  time(Maybe[Str] $min, Maybe[Str] $max) : Str

The time method returns a random time.

time example #1

  # given: synopsis

  $t->time;

undef

  undef() : Undef

The undef method returns the undefined value.

undef example #1

  # given: synopsis

  $t->undef;

undef_object

  undef_object() : Object

The undef_object method returns the undefined value as an object.

undef_object example #1

  # given: synopsis

  $t->undef_object;

word

  word() : Str

The word method returns a random word.

word example #1

  # given: synopsis

  $t->word;

words

  words(Maybe[Int] $min, Maybe[Int] $max) : Str

The words method returns random words.

words example #1

  # given: synopsis

  $t->words;

AUTHOR

Al Newkirk, awncorp@cpan.org

LICENSE

Copyright (C) 2011-2019, Al Newkirk, et al.

This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file".

PROJECT

Wiki

Project

Initiatives

Milestones

Contributing

Issues

cpanm Test::Ability

perl -MCPAN -e shell
install Test::Ability