| Current Path : /proc/2/root/usr/local/share/man/man3/ |
| Current File : //proc/2/root/usr/local/share/man/man3/Test2::Manual::Testing::Migrating.3pm |
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Test2::Manual::Testing::Migrating 3"
.TH Test2::Manual::Testing::Migrating 3 "2019-05-18" "perl v5.10.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"
Test2::Manual::Testing::Migrating \- How to migrate existing tests from
Test::More to Test2.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This tutorial covers the conversion of an existing test. This tutorial assumes
you have a test written using Test::More.
.SH "LEGACY TEST"
.IX Header "LEGACY TEST"
This tutorial will be converting this example test one section at a time:
.PP
\&\f(CW\*(C`t/example.t\*(C'\fR:
.PP
.Vb 2
\& #####################
\& # Boilerplate
\&
\& use strict;
\& use warnings;
\&
\& use Test::More tests => 14;
\&
\& use_ok \*(AqScalar::Util\*(Aq;
\& require_ok \*(AqExporter\*(Aq;
\&
\& #####################
\& # Simple assertions (no changes)
\&
\& ok(1, "pass");
\&
\& is("apple", "apple", "Simple string compare");
\&
\& like("foo bar baz", qr/bar/, "Regex match");
\&
\& #####################
\& # Todo
\&
\& {
\& local $TODO = "These are todo";
\&
\& ok(0, "oops");
\& }
\&
\& #####################
\& # Deep comparisons
\&
\& is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
\&
\& #####################
\& # Comparing references
\&
\& my $ref = [1];
\& is($ref, $ref, "Check that we have the same ref both times");
\&
\& #####################
\& # Things that are gone
\&
\& ok(eq_array([1], [1]), "array comparison");
\& ok(eq_hash({a => 1}, {a => 1}), "hash comparison");
\& ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison");
\&
\& note explain([1, 2, 3]);
\&
\& {
\& package THING;
\& sub new { bless({}, shift) }
\& }
\&
\& my $thing = new_ok(\*(AqTHING\*(Aq);
\&
\& #####################
\& # Tools that changed
\&
\& isa_ok($thing, \*(AqTHING\*(Aq, \*(Aq$thing\*(Aq);
\&
\& can_ok(_\|_PACKAGE_\|_, qw/ok is/);
.Ve
.SH "BOILERPLATE"
.IX Header "BOILERPLATE"
\&\s-1BEFORE:\s0
.PP
.Vb 2
\& use strict;
\& use warnings;
\&
\& use Test::More tests => 14;
\&
\& use_ok \*(AqScalar::Util\*(Aq;
\& require_ok \*(AqExporter\*(Aq;
.Ve
.PP
\&\s-1AFTER:\s0
.PP
.Vb 2
\& use Test2::V0;
\& plan(11);
\&
\& use Scalar::Util;
\& require Exporter;
.Ve
.IP "Replace Test::More with Test2::V0" 4
.IX Item "Replace Test::More with Test2::V0"
Test2::V0 is the recommended bundle. In a full migration you
will want to replace Test::More with the Test2::V0 bundle.
.Sp
\&\fBNote:\fR You should always double check the latest Test2 to see if there is
a new recommended bundle. When writing a new test you should always use the
newest Test::V# module. Higher numbers are newer version.
.IP "Stop using \fIuse_ok()\fR" 4
.IX Item "Stop using use_ok()"
\&\f(CW\*(C`use_ok()\*(C'\fR has been removed. a \f(CW\*(C`use MODULE\*(C'\fR statement will throw an exception
on failure anyway preventing the test from passing.
.Sp
If you \fI\s-1REALLY\s0\fR want/need to assert that the file loaded you can use the ok
module:
.Sp
.Vb 1
\& use ok \*(AqScalar::Util\*(Aq;
.Ve
.Sp
The main difference here is that there is a space instead of an underscore.
.IP "Stop using \fIrequire_ok()\fR" 4
.IX Item "Stop using require_ok()"
\&\f(CW\*(C`require_ok\*(C'\fR has been removed just like \f(CW\*(C`use_ok\*(C'\fR. There is no ok module
equivalent here. Just use \f(CW\*(C`require\*(C'\fR.
.IP "Remove strict/warnings (optional)" 4
.IX Item "Remove strict/warnings (optional)"
The Test2::V0 bundle turns strict and warnings on for you.
.IP "Change where the plan is set" 4
.IX Item "Change where the plan is set"
Test2 does not allow you to set the plan at import. In the old code you would
pass \f(CW\*(C`tests => 11\*(C'\fR as an import argument. In Test2 you either need to
use the \f(CW\*(C`plan()\*(C'\fR function to set the plan, or use \f(CW\*(C`done_testing()\*(C'\fR at the end
of the test.
.Sp
If your test already uses \f(CW\*(C`done_testing()\*(C'\fR you can keep that and no plan
changes are necessary.
.Sp
\&\fBNote:\fR We are also changing the plan from 14 to 11, that is because we
dropped \f(CW\*(C`use_ok\*(C'\fR, \f(CW\*(C`require_ok\*(C'\fR, and we will be dropping one more later on.
This is why \f(CW\*(C`done_testing()\*(C'\fR is recommended over a set plan.
.SH "SIMPLE ASSERTIONS"
.IX Header "SIMPLE ASSERTIONS"
The vast majority of assertions will not need any changes:
.PP
.Vb 2
\& #####################
\& # Simple assertions (no changes)
\&
\& ok(1, "pass");
\&
\& is("apple", "apple", "Simple string compare");
\&
\& like("foo bar baz", qr/bar/, "Regex match");
.Ve
.SH "TODO"
.IX Header "TODO"
.Vb 2
\& {
\& local $TODO = "These are todo";
\&
\& ok(0, "oops");
\& }
.Ve
.PP
The \f(CW$TODO\fR package variable is gone. You now have a \f(CW\*(C`todo()\*(C'\fR function.
.PP
There are 2 ways this can be used:
.ie n .IP "todo $reason => sub { ... }" 4
.el .IP "todo \f(CW$reason\fR => sub { ... }" 4
.IX Item "todo $reason => sub { ... }"
.Vb 3
\& todo "These are todo" => sub {
\& ok(0, "oops");
\& };
.Ve
.Sp
This is the cleanest way to do a todo. This will make all assertions inside the
codeblock into \s-1TODO\s0 assertions.
.ie n .IP "{ my $TODO = todo $reason; ... }" 4
.el .IP "{ my \f(CW$TODO\fR = todo \f(CW$reason\fR; ... }" 4
.IX Item "{ my $TODO = todo $reason; ... }"
.Vb 2
\& {
\& my $TODO = todo "These are todo";
\&
\& ok(0, "oops");
\& }
.Ve
.Sp
This is a system that emulates the old way. Instead of modifying a global
\&\f(CW$TODO\fR variable you create a todo object with the \f(CW\*(C`todo()\*(C'\fR function and
assign it to a lexical variable. Once the todo object falls out of scope the
\&\s-1TODO\s0 ends.
.SH "DEEP COMPARISONS"
.IX Header "DEEP COMPARISONS"
.Vb 1
\& is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");
.Ve
.PP
Deep comparisons are easy, simply replace \f(CW\*(C`is_deeply()\*(C'\fR with \f(CW\*(C`is()\*(C'\fR.
.PP
.Vb 1
\& is([1, 2, 3], [1, 2, 3], "Deep comparison");
.Ve
.SH "COMPARING REFERENCES"
.IX Header "COMPARING REFERENCES"
.Vb 2
\& my $ref = [1];
\& is($ref, $ref, "Check that we have the same ref both times");
.Ve
.PP
The \f(CW\*(C`is()\*(C'\fR function provided by Test::More forces both arguments into
strings, which makes this a comparison of the reference addresses. Test2's
\&\f(CW\*(C`is()\*(C'\fR function is a deep comparison, so this will still pass, but fails to
actually test what we want (that both references are the same exact ref, not
just identical structures.)
.PP
We now have the \f(CW\*(C`ref_is()\*(C'\fR function that does what we really want, it ensures
both references are the same reference. This function does the job better than
the original, which could be thrown off by string overloading.
.PP
.Vb 2
\& my $ref = [1];
\& ref_is($ref, $ref, "Check that we have the same ref both times");
.Ve
.SH "TOOLS THAT ARE GONE"
.IX Header "TOOLS THAT ARE GONE"
.Vb 3
\& ok(eq_array([1], [1]), "array comparison");
\& ok(eq_hash({a => 1}, {a => 1}), "hash comparison");
\& ok(eq_set([1, 3, 2], [1, 2, 3]), "set comparison");
\&
\& note explain([1, 2, 3]);
\&
\& {
\& package THING;
\& sub new { bless({}, shift) }
\& }
\&
\& my $thing = new_ok(\*(AqTHING\*(Aq);
.Ve
.PP
\&\f(CW\*(C`eq_array\*(C'\fR, \f(CW\*(C`eq_hash\*(C'\fR and \f(CW\*(C`eq_set\*(C'\fR have been considered deprecated for a
very long time, Test2 does not provide them at all. Instead you can just use
\&\f(CW\*(C`is()\*(C'\fR:
.PP
.Vb 2
\& is([1], [1], "array comparison");
\& is({a => 1}, {a => 1}, "hash comparison");
.Ve
.PP
\&\f(CW\*(C`eq_set\*(C'\fR is a tad more complicated, see Test2::Tools::Compare for an
explanation:
.PP
.Vb 1
\& is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
.Ve
.PP
\&\f(CW\*(C`explain()\*(C'\fR has a rocky history. There have been arguments about how it should
work. Test2 decided to simply not include \f(CW\*(C`explain()\*(C'\fR to avoid the
arguments. You can instead directly use Data::Dumper:
.PP
.Vb 2
\& use Data::Dumper;
\& note Dumper([1, 2, 3]);
.Ve
.PP
\&\f(CW\*(C`new_ok()\*(C'\fR is gone. The implementation was complicated, and did not add much
value:
.PP
.Vb 4
\& {
\& package THING;
\& sub new { bless({}, shift) }
\& }
\&
\& my $thing = THING\->new;
\& ok($thing, "made a new thing");
.Ve
.PP
The complete section after the conversion is:
.PP
.Vb 3
\& is([1], [1], "array comparison");
\& is({a => 1}, {a => 1}, "hash comparison");
\& is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
\&
\& use Data::Dumper;
\& note Dumper([1, 2, 3]);
\&
\& {
\& package THING;
\& sub new { bless({}, shift) }
\& }
\&
\& my $thing = THING\->new;
\& ok($thing, "made a new thing");
.Ve
.SH "TOOLS THAT HAVE CHANGED"
.IX Header "TOOLS THAT HAVE CHANGED"
.Vb 1
\& isa_ok($thing, \*(AqTHING\*(Aq, \*(Aq$thing\*(Aq);
\&
\& can_ok(_\|_PACKAGE_\|_, qw/ok is/);
.Ve
.PP
In Test::More these functions are very confusing, and most people use them
wrong!
.PP
\&\f(CW\*(C`isa_ok()\*(C'\fR from Test::More takes a thing, a class/reftype to check, and
then uses the third argument as an alternative display name for the first
argument (\s-1NOT\s0 a test name!).
.PP
\&\f(CW\*(C`can_ok()\*(C'\fR from Test::More is not consistent with \f(CW\*(C`isa_ok\*(C'\fR as all
arguments after the first are subroutine names.
.PP
Test2 fixes this by making both functions consistent and obvious:
.PP
.Vb 1
\& isa_ok($thing, [\*(AqTHING\*(Aq], \*(Aqgot a THING\*(Aq);
\&
\& can_ok(_\|_PACKAGE_\|_, [qw/ok is/], "have expected subs");
.Ve
.PP
You will note that both functions take a thing, an arrayref as the second
argument, then a test name as the third argument.
.SH "FINAL VERSION"
.IX Header "FINAL VERSION"
.Vb 2
\& #####################
\& # Boilerplate
\&
\& use Test2::V0;
\& plan(11);
\&
\& use Scalar::Util;
\& require Exporter;
\&
\& #####################
\& # Simple assertions (no changes)
\&
\& ok(1, "pass");
\&
\& is("apple", "apple", "Simple string compare");
\&
\& like("foo bar baz", qr/bar/, "Regex match");
\&
\& #####################
\& # Todo
\&
\& todo "These are todo" => sub {
\& ok(0, "oops");
\& };
\&
\& #####################
\& # Deep comparisons
\&
\& is([1, 2, 3], [1, 2, 3], "Deep comparison");
\&
\& #####################
\& # Comparing references
\&
\& my $ref = [1];
\& ref_is($ref, $ref, "Check that we have the same ref both times");
\&
\& #####################
\& # Things that are gone
\&
\& is([1], [1], "array comparison");
\& is({a => 1}, {a => 1}, "hash comparison");
\&
\& is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");
\&
\& use Data::Dumper;
\& note Dumper([1, 2, 3]);
\&
\& {
\& package THING;
\& sub new { bless({}, shift) }
\& }
\&
\& my $thing = THING\->new;
\&
\& #####################
\& # Tools that changed
\&
\& isa_ok($thing, [\*(AqTHING\*(Aq], \*(Aqgot a THING\*(Aq);
\&
\& can_ok(_\|_PACKAGE_\|_, [qw/ok is/], "have expected subs");
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Manual \- Primary index of the manual.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Manual can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH "AUTHORS"
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2018 Chad Granum <exodist@cpan.org>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)