.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Differences 3pm" .TH Test::Differences 3pm "2019-07-21" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Differences \- Test strings and data structures and show differences if not ok .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Test; ## Or use Test::More \& use Test::Differences; \& \& eq_or_diff $got, "a\enb\enc\en", "testing strings"; \& eq_or_diff \e@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, \e@expected_arrays "testing DBI arrays"; \& eq_or_diff $sth\->fetchall_hashref, \e@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 ...; .Ve .SH "EXPORT" .IX Header "EXPORT" This module exports three test functions and four diff-style functions: .IP "\(bu" 4 Test functions .RS 4 .IP "\(bu" 4 \&\f(CW\*(C`eq_or_diff\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`eq_or_diff_data\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`eq_or_diff_text\*(C'\fR .RE .RS 4 .RE .IP "\(bu" 4 Diff style functions .RS 4 .IP "\(bu" 4 \&\f(CW\*(C`table_diff\*(C'\fR (the default) .IP "\(bu" 4 \&\f(CW\*(C`unified_diff\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`oldstyle_diff\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`context_diff\*(C'\fR .RE .RS 4 .RE .SH "DESCRIPTION" .IX Header "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 \&\f(CW\*(C`diff\*(C'\fR 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: .PP .Vb 10 \& 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 |\etindented * \& # | 3| indented | indented | \& # +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& not ok 3 \& # Failed test ((eval 2) at line 22) \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | Elt|Got |Expected | \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # * 0|bless( [ |[ * \& # * 1| \*(AqMove along, nothing to see here\*(Aq | \*(AqDry, humorless message\*(Aq * \& # * 2|], \*(AqTest::Builder\*(Aq ) |] * \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # Looks like you failed 3 tests of 3. .Ve .PP 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 \s-1SYNOPSIS\s0 shows, another testing module must be used as the basis for your test suite. .SH "OPTIONS" .IX Header "OPTIONS" The options to \f(CW\*(C`eq_or_diff\*(C'\fR give some fine-grained control over the output. .IP "\(bu" 4 \&\f(CW\*(C`context\*(C'\fR .Sp This allows you to control the amount of context shown: .Sp .Vb 1 \& eq_or_diff $got, $expected, $name, { context => 50000 }; .Ve .Sp will show you lots and lots of context. Normally, \fBeq_or_diff()\fR uses some heuristics to determine whether to show 3 lines of context (like a normal unified diff) or 25 lines. .IP "\(bu" 4 \&\f(CW\*(C`data_type\*(C'\fR .Sp \&\f(CW\*(C`text\*(C'\fR or \f(CW\*(C`data\*(C'\fR. See \f(CW\*(C`eq_or_diff_text\*(C'\fR and \f(CW\*(C`eq_or_diff_data\*(C'\fR to understand this. You can usually ignore this. .IP "\(bu" 4 \&\f(CW\*(C`Sortkeys\*(C'\fR .Sp 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. .IP "\(bu" 4 \&\f(CW\*(C`filename_a\*(C'\fR and \f(CW\*(C`filename_b\*(C'\fR .Sp The column headers to use in the output. They default to 'Got' and 'Expected'. .SH "DIFF STYLES" .IX Header "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: .IP "\(bu" 4 \&\f(CW\*(C`table_diff\*(C'\fR (the default) .IP "\(bu" 4 \&\f(CW\*(C`unified_diff\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`oldstyle_diff\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`context_diff\*(C'\fR .PP You can run the following to understand the different diff output styles: .PP .Vb 2 \& use Test::More \*(Aqno_plan\*(Aq; \& use Test::Differences; \& \& my $long_string = join \*(Aq\*(Aq => 1..40; \& \& TODO: { \& local $TODO = \*(AqTesting diff styles\*(Aq; \& \& # 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", \*(Aqtable diff\*(Aq; \& \& unified_diff; \& eq_or_diff $long_string, "\-$long_string", \*(Aqunified diff\*(Aq; \& \& context_diff; \& eq_or_diff $long_string, "\-$long_string", \*(Aqcontext diff\*(Aq; \& \& oldstyle_diff; \& eq_or_diff $long_string, "\-$long_string", \*(Aqoldstyle diff\*(Aq; \& } .Ve .SH "UNICODE" .IX Header "UNICODE" Generally you'll find that the following test output is disappointing. .PP .Vb 1 \& use Test::Differences; \& \& my $want = { \*(AqTraditional Chinese\*(Aq => \*(Aq中國\*(Aq }; \& my $have = { \*(AqTraditional Chinese\*(Aq => \*(Aq中国\*(Aq }; \& \& eq_or_diff $have, $want, \*(AqUnicode, baby\*(Aq; .Ve .PP The output looks like this: .PP .Vb 10 \& # Failed test \*(AqUnicode, baby\*(Aq \& # at t/unicode.t line 12. \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | Elt|Got |Expected | \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | 0|\*(AqTraditional Chinese\*(Aq |\*(AqTraditional Chinese\*(Aq | \& # * 1|\*(Aq\exe4\exb8\exad\exe5\ex9b\exbd\*(Aq |\*(Aq\exe4\exb8\exad\exe5\ex9c\ex8b\*(Aq * \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # Looks like you failed 1 test of 1. \& Dubious, test returned 1 (wstat 256, 0x100) .Ve .PP This is generally not helpful and someone points out that you didn't declare your test program as being utf8, so you do that: .PP .Vb 2 \& use Test::Differences; \& use utf8; \& \& my $want = { \*(AqTraditional Chinese\*(Aq => \*(Aq中國\*(Aq }; \& my $have = { \*(AqTraditional Chinese\*(Aq => \*(Aq中国\*(Aq }; \& \& eq_or_diff $have, $want, \*(AqUnicode, baby\*(Aq; .Ve .PP Here's what you get: .PP .Vb 11 \& # Failed test \*(AqUnicode, baby\*(Aq \& # at t/unicode.t line 12. \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | Elt|Got |Expected | \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | 0|\*(AqTraditional Chinese\*(Aq |\*(AqTraditional Chinese\*(Aq | \& # * 1|\*(Aq\ex{4e2d}\ex{56fd}\*(Aq |\*(Aq\ex{4e2d}\ex{570b}\*(Aq * \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # Looks like you failed 1 test of 1. \& Dubious, test returned 1 (wstat 256, 0x100) \& Failed 1/1 subtests .Ve .PP That's better, but still awful. However, if you have \f(CW\*(C`Text::Diff\*(C'\fR 0.40 or higher installed, you can add this to your code: .PP .Vb 1 \& BEGIN { $ENV{DIFF_OUTPUT_UNICODE} = 1 } .Ve .PP Make sure you do this \fIbefore\fR you load Text::Diff. Then this is the output: .PP .Vb 6 \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | Elt|Got |Expected | \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | 0|\*(AqTraditional Chinese\*(Aq |\*(AqTraditional Chinese\*(Aq | \& # * 1|\*(Aq中国\*(Aq |\*(Aq中國\*(Aq * \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .SH "DEPLOYING" .IX Header "DEPLOYING" There are several basic ways of deploying Test::Differences requiring more or less labor by you or your users. .IP "\(bu" 4 Fallback to \f(CW\*(C`is_deeply\*(C'\fR. .Sp This is your best option if you want this module to be optional. .Sp .Vb 6 \& use Test::More; \& BEGIN { \& if (!eval q{ use Test::Differences; 1 }) { \& *eq_or_diff = \e&is_deeply; \& } \& } .Ve .IP "\(bu" 4 .Sp .Vb 1 \& eval "use Test::Differences"; .Ve .Sp If you want to detect the presence of Test::Differences on the fly, something like the following code might do the trick for you: .Sp .Vb 1 \& 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"; .Ve .IP "\(bu" 4 \&\s-1PREREQ_PM\s0 => { .... \*(L"Test::Differences\*(R" => 0, ... } .Sp This method will let \s-1CPAN\s0 and \s-1CPANPLUS\s0 users download it automatically. It will discomfit those users who choose/have to download all packages manually. .IP "\(bu" 4 t/lib/Test/Differences.pm, t/lib/Text/Diff.pm, ... .Sp 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 \s-1CPAN\s0 or \s-1CPANPLUS.\s0 .Sp If you put a \f(CW\*(C`use lib "t/lib";\*(C'\fR in the top of each test suite before the \&\f(CW\*(C`use Test::Differences;\*(C'\fR, \f(CW\*(C`make test\*(C'\fR should work well. .Sp You might want to check once in a while for new Test::Differences releases if you do this. .SH "LIMITATIONS" .IX Header "LIMITATIONS" .ie n .SS """Test"" or ""Test::More""" .el .SS "\f(CWTest\fP or \f(CWTest::More\fP" .IX Subsection "Test or Test::More" This module \*(L"mixes in\*(R" 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 \f(CW%INC\fR, 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. .SS "Exporting" .IX Subsection "Exporting" Exports all 3 functions by default (and by design). Use .PP .Vb 1 \& use Test::Differences (); .Ve .PP to suppress this behavior if you don't like the namespace pollution. .PP This module will not override functions like \fBok()\fR, \fBis()\fR, \fBis_deeply()\fR, etc. If it did, then you could \f(CW\*(C`eval "use Test::Differences qw( is_deeply );"\*(C'\fR to get automatic upgrading to diffing behaviors without the \f(CW\*(C`sub my_ok\*(C'\fR 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. .SS "Unicode" .IX Subsection "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. .ie n .SS """Data::Dumper"" and older Perls." .el .SS "\f(CWData::Dumper\fP and older Perls." .IX Subsection "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. \f(CW $Data::Dumper::Sortkeys \fR \fIis\fR set to 1, so on more recent versions of Data::Dumper, this should not occur. Check \s-1CPAN\s0 to see if it's been peeled out of the main perl distribution and backported. Reported by Ilya Martynov , although the Sortkeys \*(L"future perfect\*(R" workaround has been set in anticipation of a new Data::Dumper for a while. Note that the two hashes should report the same here: .PP .Vb 10 \& not ok 5 \& # Failed test (t/ctrl/05\-home.t at line 51) \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | Elt|Got | Elt|Expected | \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& # | 0|{ | 0|{ | \& # | 1| \*(Aqpassword\*(Aq => \*(Aq\*(Aq, | 1| \*(Aqpassword\*(Aq => \*(Aq\*(Aq, | \& # * 2| \*(Aqmethod\*(Aq => \*(Aqlogin\*(Aq, * | | \& # | 3| \*(Aqctrl\*(Aq => \*(Aqhome\*(Aq, | 2| \*(Aqctrl\*(Aq => \*(Aqhome\*(Aq, | \& # | | * 3| \*(Aqmethod\*(Aq => \*(Aqlogin\*(Aq, * \& # | 4| \*(Aqemail\*(Aq => \*(Aqtest\*(Aq | 4| \*(Aqemail\*(Aq => \*(Aqtest\*(Aq | \& # | 5|} | 5|} | \& # +\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP Data::Dumper also overlooks the difference between .PP .Vb 2 \& $a[0] = \e$a[1]; \& $a[1] = \e$a[0]; # $a[0] = \e$a[1] .Ve .PP and .PP .Vb 3 \& $x = \e$y; \& $y = \e$x; \& @a = ( $x, $y ); # $a[0] = \e$y, not \e$a[1] .Ve .PP The former involves two scalars, the latter 4: \f(CW$x\fR, \f(CW$y\fR, and \f(CW@a\fR[0,1]. This was carefully explained to me in words of two syllables or less by Yves Orton . The plan to address this is to allow you to select Data::Denter or some other module of your choice as an option. .SS "Code-refs" .IX Subsection "Code-refs" Test::Differences turns on \f(CW$Data::Dumper::Deparse\fR, so any code-refs in your data structures will be turned into text before they are examined, using B::Deparse. The precise text generated for a sub-ref might not be what you expect as it is generated from the compiled version of the code, but it should at least be consistent and spot differences correctly. .PP You can turn this behaviour off by setting \f(CW$Test::Differences::NoDeparse\fR. .SH "AUTHORS" .IX Header "AUTHORS" .Vb 1 \& Barrie Slaymaker \- original author \& \& Curtis "Ovid" Poe \& \& David Cantrell .Ve .SH "LICENSE" .IX Header "LICENSE" Copyright Barrie Slaymaker, Curtis \*(L"Ovid\*(R" Poe, and David Cantrell. .PP All Rights Reserved. .PP You may use, distribute and modify this software under the terms of the \s-1GNU\s0 public license, any version, or the Artistic license.