Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

Test::Differences(3)                 User Contributed Perl Documentation                Test::Differences(3)



NAME
       Test::Differences - Test strings and data structures and show differences if not ok

VERSION
       0.61

SYNOPSIS
          use Test;    ## Or use Test::More
          use Test::Differences;

          eq_or_diff $got,  "a\nb\nc\n",   "testing strings";
          eq_or_diff \@got, [qw( a b c )], "testing arrays";

          ## Passing options:
          eq_or_diff $got, $expected, $name, { context => 300 };  ## options

          ## Using with DBI-like data structures

          use DBI;

          ... open connection & prepare statement and @expected_... here...

          eq_or_diff $sth->fetchall_arrayref, \@expected_arrays  "testing DBI arrays";
          eq_or_diff $sth->fetchall_hashref,  \@expected_hashes, "testing DBI hashes";

          ## To force textual or data line numbering (text lines are numbered 1..):
          eq_or_diff_text ...;
          eq_or_diff_data ...;

EXPORT
       This module exports three test functions and four diff-style functions:

       •   Test functions

           •   "eq_or_diff"

           •   "eq_or_diff_data"

           •   "eq_or_diff_text"

       •   Diff style functions

           •   "table_diff" (the default)

           •   "unified_diff"

           •   "oldstyle_diff"

           •   "context_diff"

DESCRIPTION
       When the code you're testing returns multiple lines, records or data structures and they're just
       plain wrong, an equivalent to the Unix "diff" utility may be just what's needed.  Here's output from
       an example test script that checks two text documents and then two (trivial) data structures:

        t/99example....1..3
        not ok 1 - differences in text
        #     Failed test ((eval 2) at line 14)
        #     +---+----------------+----------------+
        #     | Ln|Got             |Expected        |
        #     +---+----------------+----------------+
        #     |  1|this is line 1  |this is line 1  |
        #     *  2|this is line 2  |this is line b  *
        #     |  3|this is line 3  |this is line 3  |
        #     +---+----------------+----------------+
        not ok 2 - differences in whitespace
        #     Failed test ((eval 2) at line 20)
        #     +---+------------------+------------------+
        #     | Ln|Got               |Expected          |
        #     +---+------------------+------------------+
        #     |  1|        indented  |        indented  |
        #     *  2|        indented  |\tindented        *
        #     |  3|        indented  |        indented  |
        #     +---+------------------+------------------+
        not ok 3
        #     Failed test ((eval 2) at line 22)
        #     +----+-------------------------------------+----------------------------+
        #     | Elt|Got                                  |Expected                    |
        #     +----+-------------------------------------+----------------------------+
        #     *   0|bless( [                             |[                           *
        #     *   1|  'Move along, nothing to see here'  |  'Dry, humorless message'  *
        #     *   2|], 'Test::Builder' )                 |]                           *
        #     +----+-------------------------------------+----------------------------+
        # Looks like you failed 3 tests of 3.

       eq_or_diff_...() compares two strings or (limited) data structures and either emits an ok indication
       or a side-by-side diff.  Test::Differences is designed to be used with Test.pm and with Test::Simple,
       Test::More, and other Test::Builder based testing modules.  As the SYNOPSIS shows, another testing
       module must be used as the basis for your test suite.

       These functions assume that you are presenting it with "flat" records, looking like:

          - scalars composed of record-per-line
          - arrays of scalars,
          - arrays of arrays of scalars,
          - arrays of hashes containing only scalars

       All of these are flattened in to single strings which are then compared for differences.  Differently
       data structures can be compared, as long as they flatten identically.

       All other data structures are run through Data::Dumper first.  This is a bit dangerous, as some
       versions of perl shipped with Data::Dumpers that could do the oddest things with unexpected, like
       core dump.  Only as of 5.8.0 does Data::Dumper sort hash keys, which is necessary for HASH dumps to
       be fully predictable.  This will be changed when this bites somebody or I get some free time.

       "eq_or_diff()" starts counting records at 0 unless you pass it two text strings:

          eq_or_diff $a, $b;   ## First line is line number 1
          eq_or_diff @a, @b;   ## First element is element 0
          eq_or_diff $a, @b;   ## First line/element is element 0

       If you want to force a first record number of 0, use "eq_or_diff_data".  If you want to force a first
       record number of 1, use "eq_or_diff_text".  I chose this over passing in an options hash because it's
       clearer and simpler this way.  YMMV.

OPTIONS
       The options to "eq_or_diff" give some fine-grained control over the output.

       •   "context"

           This allows you to control the amount of context shown:

              eq_or_diff $got, $expected, $name, { context => 50000 };

           will show you lots and lots of context.  Normally, eq_or_diff() uses some heuristics to determine
           whether to show 3 lines of context (like a normal unified diff) or 25 lines.

       •   "data_type"

           "text" or "data". See "eq_or_diff_text" and "eq_or_diff_data" to understand this. You can usually
           ignore this.

       •   "Sortkeys"

           If passed, whatever value is added is used as the argument for Data::Dumper Sortkeys option. See
           the Data::Dumper docs to understand how you can control the Sortkeys behavior.

DIFF STYLES
       For extremely long strings, a table diff can wrap on your screen and be hard to read.  If you are
       comfortable with different diff formats, you can switch to a format more suitable for your data.
       These are the four formats supported by the Text::Diff module and are set with the following
       functions:

       •   "table_diff" (the default)

       •   "unified_diff"

       •   "oldstyle_diff"

       •   "context_diff"

       You can run the following to understand the different diff output styles:

        use Test::More 'no_plan';
        use Test::Differences;

        my $long_string = join '' => 1..40;

        TODO: {
            local $TODO = 'Testing diff styles';

            # this is the default and does not need to explicitly set unless you need
            # to reset it back from another diff type
            table_diff;
            eq_or_diff $long_string, "-$long_string", 'table diff';

            unified_diff;
            eq_or_diff $long_string, "-$long_string", 'unified diff';

            context_diff;
            eq_or_diff $long_string, "-$long_string", 'context diff';

            oldstyle_diff;
            eq_or_diff $long_string, "-$long_string", 'oldstyle diff';
        }

DEPLOYING
       There are several basic ways of deploying Test::Differences requiring more or less labor by you or
       your users.

       •   Fallback to "is_deeply".

           This is your best option if you want this module to be optional.

            use Test::More;
            BEGIN {
                if (!eval q{ use Test::Differences; 1 }) {
                    *eq_or_diff = \&is_deeply;
                }
            }

       •

            eval "use Test::Differences";

           If you want to detect the presence of Test::Differences on the fly, something like the following
           code might do the trick for you:

               use Test qw( !ok );   ## get all syms *except* ok

               eval "use Test::Differences";
               use Data::Dumper;

               sub ok {
                   goto &eq_or_diff if defined &eq_or_diff && @_ > 1;
                   @_ = map ref $_ ? Dumper( @_ ) : $_, @_;
                   goto Test::&ok;
               }

               plan tests => 1;

               ok "a", "b";

       •   PREREQ_PM => { .... "Test::Differences" => 0, ... }

           This method will let CPAN and CPANPLUS users download it automatically.  It will discomfit those
           users who choose/have to download all packages manually.

       •   t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ...

           By placing Test::Differences and its prerequisites in the t/lib directory, you avoid forcing your
           users to download the Test::Differences manually if they aren't using CPAN or CPANPLUS.

           If you put a "use lib "t/lib";" in the top of each test suite before the "use
           Test::Differences;", "make test" should work well.

           You might want to check once in a while for new Test::Differences releases if you do this.

LIMITATIONS
   "Test" or "Test::More"
       This module "mixes in" with Test.pm or any of the test libraries based on Test::Builder
       (Test::Simple, Test::More, etc).  It does this by peeking to see whether Test.pm or Test/Builder.pm
       is in %INC, so if you are not using one of those, it will print a warning and play dumb by not
       emitting test numbers (or incrementing them).  If you are using one of these, it should interoperate
       nicely.

   Exporting
       Exports all 3 functions by default (and by design).  Use

           use Test::Differences ();

       to suppress this behavior if you don't like the namespace pollution.

       This module will not override functions like ok(), is(), is_deeply(), etc.  If it did, then you could
       "eval "use Test::Differences qw( is_deeply );"" to get automatic upgrading to diffing behaviors
       without the "sub my_ok" shown above.  Test::Differences intentionally does not provide this behavior
       because this would mean that Test::Differences would need to emulate every popular test module out
       there, which would require far more coding and maintenance that I'm willing to do.  Use the eval and
       my_ok deployment shown above if you want some level of automation.

   Unicode
       Perls before 5.6.0 don't support characters > 255 at all, and 5.6.0 seems broken.  This means that
       you might get odd results using perl5.6.0 with unicode strings.

   "Data::Dumper" and older Perls.
       Relies on Data::Dumper (for now), which, prior to perl5.8, will not always report hashes in the same
       order.   $Data::Dumper::SortKeys  is set to 1, so on more recent versions of Data::Dumper, this
       should not occur.  Check CPAN to see if it's been peeled out of the main perl distribution and
       backported.  Reported by Ilya Martynov <ilya@martynov.org>, although the SortKeys "future perfect"
       workaround has been set in anticipation of a new Data::Dumper for a while.  Note that the two hashes
       should report the same here:

           not ok 5
           #     Failed test (t/ctrl/05-home.t at line 51)
           # +----+------------------------+----+------------------------+
           # | Elt|Got                     | Elt|Expected                |
           # +----+------------------------+----+------------------------+
           # |   0|{                       |   0|{                       |
           # |   1|  'password' => '',     |   1|  'password' => '',     |
           # *   2|  'method' => 'login',  *    |                        |
           # |   3|  'ctrl' => 'home',     |   2|  'ctrl' => 'home',     |
           # |    |                        *   3|  'method' => 'login',  *
           # |   4|  'email' => 'test'     |   4|  'email' => 'test'     |
           # |   5|}                       |   5|}                       |
           # +----+------------------------+----+------------------------+

       Data::Dumper also overlooks the difference between

           $a[0] = \$a[1];
           $a[1] = \$a[0];   # $a[0] = \$a[1]

       and

           $x = \$y;
           $y = \$x;
           @a = ( $x, $y );  # $a[0] = \$y, not \$a[1]

       The former involves two scalars, the latter 4: $x, $y, and @a[0,1].  This was carefully explained to
       me in words of two syllables or less by Yves Orton <demerphq@hotmail.com>.  The plan to address this
       is to allow you to select Data::Denter or some other module of your choice as an option.

AUTHOR
           Barrie Slaymaker <barries@slaysys.com>

MAINTAINER
           Curtis "Ovid" Poe <ovid@cpan.org>

LICENSE
       Copyright 2001-2008 Barrie Slaymaker, All Rights Reserved.

       You may use this software under the terms of the GNU public license, any version, or the Artistic
       license.



perl v5.16.2                                     2013-08-25                             Test::Differences(3)