package Test::Stream::Manual::FromTestBuilder;
use strict;
use warnings;

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Test::Stream::Manual::FromTestBuilder - Translation document for people moving
from L<Test::More>, L<Test::Simple>, or other L<Test::Builder> tools.

=head1 DESCRIPTION

This document covers things that are meaningful to someone switching from
L<Test::More>, L<Test::Simple>, and other L<Test::Builder> based tools. It
approaches the situation as though you are converting an old test, or writing a
new one. Instead of loading L<Test::More> you will be loading L<Test::Stream>
with the recommended bundle:

    use Test::Stream -V1;

    ...

=head1 WHAT IS (MOSTLY) THE SAME?

This is the list of stuff that has either not changed, or changed only in ways
not likely to be noticed.

=head2 FUNCTIONS

=over 4

=item ok

The signature is different, instead of C<ok($$;$)> it is now C<ok($$;$@)>. The
slurpy C<@> allows you to add diagnostics messages that will only be shown if
the test fails. This allows you to attach custom diagnostics directly to a
failing test.

Defined in L<Test::Stream::Plugin::Core>.

=item diag

No differences

Defined in L<Test::Stream::Plugin::Core>.

=item note

No differences

Defined in L<Test::Stream::Plugin::Core>.

=item pass

No differences

Defined in L<Test::Stream::Plugin::Core>.

=item fail

Signature changed from C<fail($)> to C<fail($;@)>. Extra arguments are
diagnostics that will be shown with your failing test.

Defined in L<Test::Stream::Plugin::Core>.

=item done_testing

No longer accepts arguments. Most people did not know it could accept arguments
in L<Test::More> so it is unlikely to effect many people.

Defined in L<Test::Stream::Plugin::Core>.

=item BAIL_OUT

No differences

Defined in L<Test::Stream::Plugin::Core>.

=item skip

No differences

Defined in L<Test::Stream::Plugin::Core>.

=item can_ok

No differences

Defined in L<Test::Stream::Plugin::Core>.

=back

=head2 BEHAVIOR

=over 4

=item TAP is still the default output format.

=item You get similar if not identical diagnostics at the end of a failing test file.

=item You get file and line number for failed tests.

=back

=head1 WHAT IS (SIGNIFICANTLY) DIFFERENT?

This is a list of very notable changes that are likely to hurt you if you are
not aware of them.

=head2 FUNCTIONS

=over 4

=item is

=item is_deeply

C<is> and C<is_deeply> have been combined. You can now use C<is> for simple
scalars, or nested data structures. This also means you can no longer use C<is>
to check that hash/array reference are the same exact reference, though you can
check that they have the exact same data. If you actually want to check if 2
hash/array refs are the same or different you can use C<ref_is()> or
C<ref_is_not()>, both of which are much safer for that purpose than C<is()>
ever was.

The signature has also been changed to add a slurpy '@' to the end for
specifying extra diagnostics that only show up if the test fails.

The diagnostics have also been improved so that a table is shown with all the
differences (default cap of 25 differences, this can be altered with the
TS_MAX_DELTA environment variable).

Here is an example of a failing test:

    is(
        { a => 1, b => 2, c => [ 'a', 'b', 'c' ]},
        { a => 2, b => 3, c => [ 'x', 'y', 'z' ]},
        "These are clearly different"
    );

It produces:

    not ok 1 - These are clearly different
    # Failed test 'These are clearly different'
    # at test.pl line 3.
    # +--------+-----+----+-------+
    # | PATH   | GOT | OP | CHECK |
    # +--------+-----+----+-------+
    # | {a}    | 1   | == | 2     |
    # | {b}    | 2   | == | 3     |
    # | {c}[0] | a   | eq | x     |
    # | {c}[1] | b   | eq | y     |
    # | {c}[2] | c   | eq | z     |
    # +--------+-----+----+-------+

Notice that it gives you all the differences. It tells you the path of each
difference within the structure, what it got, and what it was checking against.
It also tells you what operator it used for the comparison, that way you will
know if the problem is the comparison used rather than the values checked.

The final column is called 'CHECK' because there are extra tools provided by
L<Test::Stream::Plugin::Compare> that give you more control over how to compare
values and structures, 'EXPECTED' does not work as a heading.

The table is smart about your screen size and formatting values displayed
within. All whitespace apart from the ASCII single space is replaced with
either its escape sequence, or its unicode number. If there is trailing
whitespace the final whitespace character will also be replaced to make it
clear to you it is there.

B<Defined in> L<Test::Stream::Plugin::Compare>.

=item like

C<like> still works like it did before, C<like($var, qr/.../)> will not need to
be changed. However it has been changed much like C<is()> in that it can be
used to check deep data structures. However C<like> is not as strict as C<is>,
and only checks for things you specify. In addition regexes and coderefs
appearing in the second structure are used as checks rather than exact
comparisons:

    like(
        { a => 'aaa', b => 'bbb', c => ['a' .. 'z'], d => 'ddd' },
        {
            a => qr/a/,                  # regex is used to check the value
            b => sub { $_ eq 'bbb' },    # Code is run to check result
            c => [ 'a', 'b', 'c' ],      # Only the first 3 items are checked
            # hash key 'd' is ignored since we did not specify it
        },
        "Parts of the structure we care about match"
    );

B<Defined in> L<Test::Stream::Plugin::Compare>.

=item plan

Only accepts a number of test expected to be run.

    plan 5;

See C<skip_all> for skipping an entire test.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item skip_all

This is the new way to skip an entire test, it takes a reason as its argument.

    skip_all 'Broken for now';

B<Defined in> L<Test::Stream::Plugin::Core>.

=item isa_ok

It was common for people to use this incorrectly in L<Test::More>. It was
reasonable to assume it worked like C<can_ok> and accepted several package
names. Instead the L<Test::More> implementation used the third argument as an
alternate name for the first. This has been changed to be consistent with
C<can_ok> and similar tools.

    isa_ok($thing, 'My::Class', 'My::Subclass', ...);

B<Defined in> L<Test::Stream::Plugin::Core>.

=item subtest

Not loaded by default, you must ask for it:

    use Test::Stream qw/-V1 Subtest/;

The default output has been changed:

    ok 1 - Subtest Name {
        ok 1 - subtest result
        ok 2 - another result
        1..2
    # }

The old output format can be used if requested:

    use Test::Stream '-V1', 'Subtest' => ['streamed'];

Defined in L<Test::Stream::Plugin::Subtest>.

=back

=head1 WHAT IS COMPLETELY GONE?

These are no longer around for you to use.

=head2 FUNCTIONS

=over 4

=item use_ok

=item require_ok

Errors loading modules cause the test to die anyway, so just load them, if they
do not work the test will fail. Making a seperate API for this is a wasted
effort. Also doing this requires the functions to guess if you provided a
module name, or filename, and then munging the input to figure out what
actually needs to be loaded.

=item new_ok

This is easy enough:

    ok(my $one = $class->new(@args), "NAME");

The utility of C<new_ok()> is questionable at best.

=item eq_array

=item eq_hash

=item eq_set

L<Test::More> itself discourages you from using these, so we are not carrying
them forward.

=item explain

This method was copied in an API-incompatible way from L<Test::Most>. This
created an incompatability issue between the 2 libraries and made a real mess
of things. There is value in a tool like this, but if it is added it will be
added with a new name to avoid conflicts.

=item cmp_ok

It is easy to write:

    ok($got == $want, "$got == $want");

cmp_eq did not buy very much more. There were added diagnostics, and they were
indeed valuable. The issue is that the implementation for a cmp_ok that accepts
arbitrary comparison operators is VERY complex. Further there are a great many
edge cases to account for. Warnings that have to do with uninitialized or
improper arguments to the operators also report to internals if not handled
properly.

All these issues are solvable, but they lead to very complex, slow, and easily
broken code. I have fixed bugs in the old cmp_ok implementation, and can tell
you it is a mess. I have also written no less than 3 replacements for cmp_ok,
all of which proved complex enough that I do not feel it is worth maintaining
in Test::Stream core.

If you want cmp_ok badly enough you can write a plugin for it.

=back

=head2 VARIABLES

=over 4

=item $TODO

The C<$TODO> variable is completely gone. Do not use it. Instead we have the
C<todo()> function. There are 2 ways to use the todo function:

Similar to old way:

    TODO: {
        # Note, this is a lexical variable, not a package variable. Do not use
        # local. The todo will end when the variable is destroyed (at the end
        # of the scope, or when you assign it to undef.
        my $todo = todo "These are not ready yet";

        ok(0, 'todo');
    }

Another way:

    todo 'These are not ready yet' => sub {
        ok(0, 'todo');
    };

=item $Test::Builder::Level

See L<Test::Stream::Context> for how L<Test:Stream> solves the same problem.

=back

=head2 BEHAVIOR

=over 4

=item plan at import

C<done_testing> is the preferred way to plan. However if you really want a plan
you can use the C<plan()> or C<skip_all> functions. Setting the plan at compile
time resulted in bugs in the past (primarily with subtests that loaded external
files), moving away from that API shortcut helps to make things cleaner.

=back

=head1 WHAT ELSE DO I GET?

This is some new stuff you get for free!

=head2 FUNCTIONS

=over 4

=item DOES_ok

Just like C<isa_ok> and C<can_ok> except it checks C<DOES> instead of C<can> or
C<isa>. All caps is used to reflect the UNIVERSAL property used, it also helps
avoid conflicts with L<Moose> related stuff.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item ref_ok

Check that something is a ref, and optionally that it is a specific type of
ref.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item imported_ok

Check that the current namespace has the specified functions. This will not
find inherited methods, only subs actually defined in the current namespace. It
will B<NOT> check that the subs came from another package.

This is a better alternative to C<can_ok> when testing imports.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item not_imported_ok

This checks that the specified functions are not available in the current
namespace. It will ignore inherited methods, is only looks for subs in the
current namespace.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item ref_is

Check that 2 references are the same references, not a deep check, compares
addresses of the 2 provided refs. Will fail if either argument is not a
reference, or is undef.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item ref_is_not

Check that 2 references are not the same references, not a deep check, compares
addresses of the 2 provided refs. Will fail if either argument is not a
reference, or is undef.

B<Defined in> L<Test::Stream::Plugin::Core>.

=item set_encoding

Can be used to set the encoding of TAP, and possibly other formatters.

    use Test::Stream -V1;
    use utf8;

    set_encoding 'utf8';
    # No wide character warnings
    ok(1, '†');

B<Defined in> L<Test::Stream::Plugin::Core>.

=item context

This is the alternative to C<$Test::Builder::Level>. See
L<Test::Stream::Context> for more info.

B<Defined in> L<Test::Stream::Plugin::Context>.

=item mock

This is a 1-stop shop for all your mocking needs. Mock classes, instances, etc.
This is the next generation of mocking after L<Mock::Quick> and borrows the
good ideas from it. See the Mock plugin for more details, or for access to the
capabilities using multiple functions instead of a single monolithic one.

B<Defined in> L<Test::Stream::Plugin::Mock>.

=item mocked

Used to check if something has been mocked using the Mock plugin.

B<Defined in> L<Test::Stream::Plugin::Mock>.

=item warning { ... }

Run the code and return the warning it is expected to produce. Dies if it gets
too many warnings, or too few.

B<Defined in> L<Test::Stream::Plugin::Warnings>.

=item warns { ... }

Returns an arrayref of all the warnings from within the codeblock, undef if
there are no warnings.

    ok(!warns { ... }, "no warnings");

    like(
        warns { ... },
        [
            qr/xxx/,
            qr/yyy/,
        ],
        "Got both expected warnings",
    );

B<Defined in> L<Test::Stream::Plugin::Warnings>.

=item no_warnings { ... }

Returns false if the block produces warnings, true if there are none. This will
also display the warnings if any occur.

    ok(no_warnings { ... }, "got no warnings");

B<Defined in> L<Test::Stream::Plugin::Warnings>.

=item lives { ... }

Returns true if the block does not throw any exceptions. Returns false and
displays the exception as a warning if the block does die.

    ok(lives { ... }, "did not die");

B<Defined in> L<Test::Stream::Plugin::Exception>.

=item dies { ... }

Returns the exception produced by the block, or undef if it did not die.

    like(
        dies { ... },
        qr/xxx/,
        "Got excpetion"
    );

B<Defined in> L<Test::Stream::Plugin::Exception>.

=back

=head2 BEHAVIOR

=over 4

=item Forking/Threading support

Forking and threading in your tests will just work (so long as you use the
'IPC' plugin, which is included in the 'V1' bundle).

=back

=head1 SOURCE

The source code repository for Test::Stream can be found at
F<http://github.com/Test-More/Test-Stream/>.

=head1 MAINTAINERS

=over 4

=item Chad Granum E<lt>exodist@cpan.orgE<gt>

=back

=head1 AUTHORS

=over 4

=item Chad Granum E<lt>exodist@cpan.orgE<gt>

=back

=head1 COPYRIGHT

Copyright 2015 Chad Granum E<lt>exodist7@gmail.comE<gt>.

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

See F<http://www.perl.com/perl/misc/Artistic.html>

=cut
