NAME

       Test2::Manual::Testing::Migrating - How to migrate existing tests from Test::More to
       Test2.

DESCRIPTION

       This tutorial covers the conversion of an existing test. This tutorial assumes you have a
       test written using Test::More.

LEGACY TEST

       This tutorial will be converting this example test one section at a time:

       "t/example.t":

           #####################
           # Boilerplate

           use strict;
           use warnings;

           use Test::More tests => 14;

           use_ok 'Scalar::Util';
           require_ok 'Exporter';

           #####################
           # 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('THING');

           #####################
           # Tools that changed

           isa_ok($thing, 'THING', '$thing');

           can_ok(__PACKAGE__, qw/ok is/);

BOILERPLATE

       BEFORE:

           use strict;
           use warnings;

           use Test::More tests => 14;

           use_ok 'Scalar::Util';
           require_ok 'Exporter';

       AFTER:

           use Test2::V0;
           plan(11);

           use Scalar::Util;
           require Exporter;

       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.

           Note: 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.

       Stop using use_ok()
           "use_ok()" has been removed. a "use MODULE" statement will throw an exception on
           failure anyway preventing the test from passing.

           If you REALLY want/need to assert that the file loaded you can use the ok module:

               use ok 'Scalar::Util';

           The main difference here is that there is a space instead of an underscore.

       Stop using require_ok()
           "require_ok" has been removed just like "use_ok". There is no ok module equivalent
           here. Just use "require".

       Remove strict/warnings (optional)
           The Test2::V0 bundle turns strict and warnings on for you.

       Change where the plan is set
           Test2 does not allow you to set the plan at import. In the old code you would pass
           "tests => 11" as an import argument. In Test2 you either need to use the "plan()"
           function to set the plan, or use "done_testing()" at the end of the test.

           If your test already uses "done_testing()" you can keep that and no plan changes are
           necessary.

           Note: We are also changing the plan from 14 to 11, that is because we dropped
           "use_ok", "require_ok", and we will be dropping one more later on.  This is why
           "done_testing()" is recommended over a set plan.

SIMPLE ASSERTIONS

       The vast majority of assertions will not need any changes:

           #####################
           # 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");
           }

       The $TODO package variable is gone. You now have a "todo()" function.

       There are 2 ways this can be used:

       todo $reason => sub { ... }
               todo "These are todo" => sub {
                   ok(0, "oops");
               };

           This is the cleanest way to do a todo. This will make all assertions inside the
           codeblock into TODO assertions.

       { my $TODO = todo $reason; ... }
               {
                   my $TODO = todo "These are todo";

                   ok(0, "oops");
               }

           This is a system that emulates the old way. Instead of modifying a global $TODO
           variable you create a todo object with the "todo()" function and assign it to a
           lexical variable. Once the todo object falls out of scope the TODO ends.

DEEP COMPARISONS

           is_deeply([1, 2, 3], [1, 2, 3], "Deep comparison");

       Deep comparisons are easy, simply replace "is_deeply()" with "is()".

           is([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");

       The "is()" function provided by Test::More forces both arguments into strings, which makes
       this a comparison of the reference addresses. Test2's "is()" 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.)

       We now have the "ref_is()" 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.

           my $ref = [1];
           ref_is($ref, $ref, "Check that we have the same ref both times");

TOOLS 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('THING');

       "eq_array", "eq_hash" and "eq_set" have been considered deprecated for a very long time,
       Test2 does not provide them at all. Instead you can just use "is()":

           is([1], [1], "array comparison");
           is({a => 1}, {a => 1}, "hash comparison");

       "eq_set" is a tad more complicated, see Test2::Tools::Compare for an explanation:

           is([1, 3, 2], bag { item 1; item 2; item 3; end }, "set comparison");

       "explain()" has a rocky history. There have been arguments about how it should work. Test2
       decided to simply not include "explain()" to avoid the arguments. You can instead directly
       use Data::Dumper:

           use Data::Dumper;
           note Dumper([1, 2, 3]);

       "new_ok()" is gone. The implementation was complicated, and did not add much value:

           {
               package THING;
               sub new { bless({}, shift) }
           }

           my $thing = THING->new;
           ok($thing, "made a new thing");

       The complete section after the conversion is:

           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");

TOOLS THAT HAVE CHANGED

           isa_ok($thing, 'THING', '$thing');

           can_ok(__PACKAGE__, qw/ok is/);

       In Test::More these functions are very confusing, and most people use them wrong!

       "isa_ok()" 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 (NOT a test name!).

       "can_ok()" from Test::More is not consistent with "isa_ok" as all arguments after the
       first are subroutine names.

       Test2 fixes this by making both functions consistent and obvious:

           isa_ok($thing, ['THING'], 'got a THING');

           can_ok(__PACKAGE__, [qw/ok is/], "have expected subs");

       You will note that both functions take a thing, an arrayref as the second argument, then a
       test name as the third argument.

FINAL VERSION

           #####################
           # 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, ['THING'], 'got a THING');

           can_ok(__PACKAGE__, [qw/ok is/], "have expected subs");

SEE ALSO

       Test2::Manual - Primary index of the manual.

SOURCE

       The source code repository for Test2-Manual 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/