NAME¶

Test2::Compare - Test2 extension for writing deep comparison tools.

DESCRIPTION¶

This library is the driving force behind deep comparison tools such as "Test2::Tools::Compare::is()" and "Test2::Tools::ClassicCompare::is_deeply()".

SYNOPSIS¶

    package Test2::Tools::MyCheck;
    use Test2::Compare::MyCheck;
    use Test2::Compare qw/compare/;
    sub MyCheck {
        my ($got, $exp, $name, @diag) = @_;
        my $ctx = context();
        my $delta = compare($got, $exp, \&convert);
        if ($delta) {
            $ctx->ok(0, $name, [$delta->table, @diag]);
        }
        else {
            $ctx->ok(1, $name);
        }
        $ctx->release;
        return !$delta;
    }
    sub convert {
        my $thing = shift;
        return $thing if blessed($thing) && $thing->isa('Test2::Compare::MyCheck');
        return Test2::Compare::MyCheck->new(stuff => $thing);
    }

See Test2::Compare::Base for details about writing a custom check.

EXPORTS¶

$delta = compare($got, $expect, \&convert)

This will compare the structures in $got with those in $expect, The convert sub should convert vanilla structures inside $expect into checks. If there are differences in the structures they will be reported back as an Test2::Compare::Delta tree.

$build = get_build()

Get the current global build, if any.

push_build($build)

Set the current global build.

$build = pop_build($build)

Unset the current global build. This will throw an exception if the build passed in is different from the current global.

build($class, sub { ... })

Run the provided codeblock with a new instance of $class as the current build. Returns the new build.

$check = convert($thing)

$check = convert($thing, $config)

This convert function is used by "strict_convert()" and "relaxed_convert()" under the hood. It can also be used as the basis for other convert functions.

If you want to use it with a custom configuration you should wrap it in another sub like so:

    sub my_convert {
        my $thing_to_convert = shift;
        return convert(
            $thing_to_convert,
            { ... }
        );
    }
    

Or the short variant:

    sub my_convert { convert($_[0], { ... }) }
    

There are several configuration options, here they are with the default setting listed first:

$check = strict_convert($thing)

Convert $thing to an Test2::Compare::* object. This will behave strictly which means it uses these settings:

$compare = relaxed_convert($thing)

Convert $thing to an Test2::Compare::* object. This will be relaxed which means it uses these settings:

WRITING A VARIANT OF IS/LIKE¶

    use Test2::Compare qw/compare convert/;
    sub my_like($$;$@) {
        my ($got, $exp, $name, @diag) = @_;
        my $ctx = context();
        # A custom converter that does the same thing as the one used by like()
        my $convert = sub {
            my $thing = shift;
            return convert(
                $thing,
                {
                    implicit_end => 0,
                    use_code     => 1,
                    use_regex    => 1,
                }
            );
        };
        my $delta = compare($got, $exp, $convert);
        if ($delta) {
            $ctx->ok(0, $name, [$delta->diag, @diag]);
        }
        else {
            $ctx->ok(1, $name);
        }
        $ctx->release;
        return !$delta;
    }

The work of a comparison tool is done by 3 entities:

compare()

The "compare()" function takes the structure you got, the specification you want to check against, and a "\&convert" sub that will convert anything that is not an instance of an Test2::Compare::Base subclass into one.

This tool will use the "\&convert" function on the specification, and then produce an Test2::Compare::Delta structure that outlines all the ways the structure you got deviates from the specification.

\&convert

Converts anything that is not an instance of an Test2::Compare::Base subclass, and turns it into one. The objects this produces are able to check that a structure matches a specification.

$delta

An instance of Test2::Compare::Delta is ultimately returned. This object represents all the ways in with the structure you got deviated from the specification. The delta is a tree and may contain child deltas for nested structures.

The delta is capable of rendering itself as a table, use "@lines = $delta->diag" to get the table (lines in @lines will not be terminated with "\n").

The "convert()" function provided by this package contains all the specification behavior of "like()" and "is()". It is intended to be wrapped in a sub that passes in a configuration hash, which allows you to control the behavior.

You are free to write your own "$check = compare($thing)" function, it just needs to accept a single argument, and produce a single instance of an Test2::Compare::Base subclass.

SOURCE¶

The source code repository for Test2-Suite can be found at https://github.com/Test-More/Test2-Suite/.

MAINTAINERS¶

Chad Granum <exodist@cpan.org>

AUTHORS¶

Chad Granum <exodist@cpan.org>

COPYRIGHT¶

Copyright 2017 Chad Granum <exodist@cpan.org>.

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

See http://dev.perl.org/licenses/