—

              
package Test::Stream::Manual::FromTestBuilder;
use strict;
use warnings;
1;
__END__
HideShow 428 lines of Pod
=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 'Classic' bundle:
    use Test::Stream -Classic;
    ...
If you do not like the idea of using L<Test::Stream> as a loader you can load
the classic bundle directly:
    use Test::Stream::Bundle::Classic;
    ...
The 'Classic' bundle is a bundle intended for people who are familiar with
Test::More and do not want to change how they do things. You could also take a
look at the 'V1' bundle, L<Test::Stream::Bundle::V1> and see if it is more to
your liking.
=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 is
Very little has changed as far as how this is used, but there are a lot of
changes under the hood, as well the signature has been changed much like
C<ok()>'s in that you can add diagnostics at the end to display in case of
failure.
This function will stringify the first 2 arguments and run a stgring
comparison. If both arguments are endefined that will also be considered a
pass.
=item isnt
Very little has changed, same changes as C<is()>.
=item is_deeply
Very little has changed as far as how this is used, but there are a lot of
changes under the hood, as well the signature has been changed much like
C<ok()>'s in that you can add diagnostics at the end to display in case of
failure.
This function will do a deep comparison recursing into hashrefs, arrayrefs, and
scalar refs. Any other values will be compared using string comparisons.
Diagnostics have been improved as well, you will get a table with all the
differences betwene the structures. Normally this will stop at 25 differences,
but the number can be tweaked using the C<$ENV{TS_MAX_DELTA}> environment
variable.
B<Note:> under the hood this uses the L<Test::Stream::Compare> library, as such
it will gladly accept any advanced check objects you produce with that library.
In practice this has no effect at all on you unless you use the Compare library
tools directly.
=item like
Not much has changed, added @ to signature for diagnostics.
=item unlike
Not much has changed, added @ to signature for diagnostics.
=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 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
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 '-Classic', 'Subtest' => ['streamed'];
Defined in L<Test::Stream::Plugin::Subtest>.
=item cmp_ok
Usage is still the same. Internals have been heavily modified to enhance
diagnostics. There is also now a list of supported operators, warnings are
issued if you use an unsupported one.
Defined in L<Test::Stream::Plugin::Core>.
=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 separate 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.
=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 something else, such as undef, to
        # the variable.
        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 -Classic;
    use utf8;
    set_encoding 'utf8';
    # No wide character warnings
    ok(1, '†');
B<Defined in> L<Test::Stream::Plugin::Core>.
=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 'Classic' 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://dev.perl.org/licenses/>
=cut