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, providing 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