NAME

Test::Stream::DeepCheck::Check - Library for comparisons and other simple checks with diagnostics.

EXPERIMENTAL CODE WARNING

This is an experimental release! Test-Stream, and all its components are still in an experimental phase. This dist has been released to cpan in order to allow testers and early adopters the chance to write experimental new tools with it, or to add experimental support for it into old tools.

PLEASE DO NOT COMPLETELY CONVERT OLD TOOLS YET. This experimental release is very likely to see a lot of code churn. API's may break at any time. Test-Stream should NOT be depended on by any toolchain level tools until the experimental phase is over.

DESCRIPTION

This library is used by several Test::Stream tools, particularily those that do deep datastructure checks. This library may be useful to test tool authors, but will not be useful to people just looking to write tests.

SYNOPSIS

    use Test::Stream::DeepCheck::Check;
    use Test::Stream::Context qw/context/;

    sub my_tool {
        my ($got, $want, $name) = @_;

        my $ctx = context();
        my $check = Test::Stream::DeepCheck::Check->new(
            debug => $ctx->debug,
            op    => '>=',
            val   => $want,
        );

        # Do the actual check
        my $bool = $check->verify($got);

        # The diagnostics are only used by ok() when $bool is false.
        $ctx->ok($bool, $name, [$check->diag($got)]);

        # return the boolean
        return $bool;
    }

METHODS

$check = $class->new(op => $op, val => $want, debug => $debug)

This is used to create a new instance.

$bool = $check->verify($got)

This will return a true or false value depening on if $got matches what we expect for the given operator and desired value.

$diag = $check->diag()

$diag = $check->diag($got)

This will return a diagnostics string with information about what went wrong. If you provide a $got value then the diagnostics message will show it, otherwise it will show '...'.

OPERATORS

Operators need to be registered with the module before they can be used. This is the safest way to run these checks. Test::More originally just used eval "$got $op $want", which had significant pitfalls (such as using '#' in the operator leading to false passes).

BUILT-IN OPERATORS

'=='

'!='

'>='

'<='

'>'

'<'

These are the numeric comparison operators. == and != will also work for references.

'eq'

'ne'

'ge'

'le'

'gt'

'lt'

These are the string comparison operators.

'=~'

'!~'

These compare the stringin <$got> to the pattern provided as val => $pattern during construction.

'!'

Simple operator, passes if $got is false. The val passed in during construction is not used.

You can prefix this operator with ! to invert the check:

    $check = $class->new( op => '!!', ... );

This will result in a check that $got is true.

'defined'

Simple operator, passes if $got is defined. The val passed in during construction is not used.

You can prefix this operator with ! to invert the check:

    $check = $class->new( op => '!defined', ... );

This will result in a check that $got is not defined.

'can'

Check $got->can($want). $want is passed in as val during construction.

'isa'

Check $got->isa($want). $want is passed in as val during construction.

'does'

Check $got->does($want). $want is passed in as val during construction.

'blessed'

Check blessed($got) eq $want. $want is passed in as val during construction.

'reftype'

Check reftype($got) eq $want. $want is passed in as val during construction.

REGISTERING NEW OPERATORS

You can add custom operators:

    Test::Stream::DeepCheck::Check::register_op(
        '=!=' => (
            # The actual check
            run => sub {
                my ($got, $want) = @_;
                return $got != $want;
            },

            # Produce diagnostics messages
            diag => sub {
                my ($op, $got, $want);
                return "...";
            },

            # Used to validate the '$want' value. This is optional.
            validate => sub {
                my ($op, $want) = @_;
                die unless $want...;
            },

            # Set this to true if you want to allow '!' prefixing to negate the check.
            neg => 1,
        ),
    );

SOURCE

The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2015 Chad Granum <exodist7@gmail.com>.

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

See http://www.perl.com/perl/misc/Artistic.html