/ 
Fennec-0.024
River stage one • 9 direct dependents • 9 total dependents
/ Fennec::DeveloperManual::Assertions

NAME

Fennec::DeveloperManual::Assertions - Writing Custom Assertion Libraries

SYNOPSIS

package Fennec::Assert::MyAssert;
use strict;
use warnings;

use Fennec::Assert;

tester my_ok => sub {
    my ( $ok, $name ) = @_;
    result(
        pass => $ok ? 1 : 0,
        name => $name || 'nameless test',
    );
};

tester 'my_is';
sub my_is {
    my ( $want, $got, $name ) = @_;
    my $ok = $want eq $got;
    result(
        pass => $ok,
        name => $name || 'nameless test',
    );
}

util 'my_util' => sub {
    ...
};

1;

STARTING

This is the only boilerplate:

use Fennec::Assert;

This will add make your class a subclass of 'Fennec::Assert'. This will also give you the following functions:

EXPORTED FUNCTIONS

tester($name; $sub)

Export a tester function

util($name; $sub)

Export a util function

result( pass => $p, name => $n, %result_props )

Generate a result

diag( @messages )

Produce diagnostics output (stderr)

$wrapped_sub = tb_wrapper($sub)

Wrap a Test::Builder based function to group a result and its diagnostics.

my %file_and_line = test_caller()

Returns ( line => $num, file => $file ) containing the line number and filename of the first Fennec::TestFile in the caller stack. Useful to make sure you report the correct line and filename in the test file being run.

EXPORTS

An assert library is basically a package that exports functions for use within tests. There are 2 types of export: tester, and util. Exports are defined by calling the tester() or util() functions with a name and optional coderef.

Exporter::Declare is used for the exporting, as such you do not need to think about it beyond calling tester() and util().

TESTERS

Tester functions are functions you export using the tester() function. Your function will be wrapped inside another function that provides extra information such as diagnostics, benchmarking, and scope/caller information to generated results.

The wrapper function will be defined with the same prototype as the function being wrapped. If the original was defined as sub($$) {...} then $newsub will also have the ($$) prototype.

tester( 'name' )
tester( name => sub { ... })

In the first form you export a package sub as a tester by name. In the second form you create a new export with an anonymous sub.

UTILS

Utility functions are not wrapped like tester functions are, this means no free diagnostics, scope, or caller. However unlike tester() a util can produce any number of results, or no results at all.

util( 'name' )
util( name => sub { ... })

In the first form you export a package sub as a util by name. In the second form you create a new export with an anonymous sub.

WRAPPING TEST::BUILDER

This is actual code from Fennec 0.11 as an example

package Fennec::Assert::TBCore::More;
use strict;
use warnings;

use Fennec::Assert;
use Fennec::Output::Result;
require Test::More;

our @LIST = qw/ ok is isnt like unlike cmp_ok can_ok isa_ok new_ok pass fail
                use_ok require_ok is_deeply /;

for my $name ( @LIST ) {
    no strict 'refs';
    next unless Test::More->can( $name );
    tester $name => tb_wrapper \&{ 'Test::More::' . $name };
}

# Technically "util 'diag';" would work, but it is less clear since diag()
# is imported.
util diag => \&diag;

util note => \&diag;

1;

MAGIC

Test::Builder overrides

Fennec::Assert will override some subs within Test::Bulder so that it generates Fennec::Output objects instead of printing to STDIN and STDERR.

Subclassing

When you use Fennec::Assert it will automatically make your package a subclass of Fennec::Assert.

package My::Assert;
use strict;
use warnings;

# Import functions AND add 'Fennec::Assert' to @ISA.
use Fennec::Assert;

This is important because it gives your package an import() and some export helper functions that allow the 'tester' and 'util' methods to define exports that may not actually be subs in your package. This provides an export_to method that Fennec uses to provide your assert functions to tests, it also allows 'use My::Assert' to work as expected.

SEE ALSO

Fennec::Assert - Assert module API documation.

USER DOCUMENTATION

User documentation is for those who wish to use Fennec to write simple tests, or manage a test suite for a project.

Fennec::UserManual

DEVELOPER DOCUMENTATION

Developer documentation is for those who wish to extend Fennec, or contribute to overall Fennec development.

Fennec::DeveloperManual

API DOCUMENTATION

API Documentation covers object internals. See the POD within each individual module.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2010 Chad Granum

Fennec is free software; Standard perl licence.

Fennec is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.