/ 
Test-Simple-1.301001_104
River stage five • 24171 direct dependents • 33703 total dependents
/ Test::Stream::Transition

NAME

Test::Stream::Transition - How to transition from Test::Builder to Test::Stream

DESCRIPTION

This document demonstrates how to transition code from Test::Builder to Test::Stream. This is a list of things people frequently need to do, and how to do them with both systems.

MAKE ASSERTIONS -> SEND EVENTS

LEGACY

use Test::Builder;

# A majority of tools out there do this:
# my $TB = Test::Builder->new;
# This works, but has always been wrong, forcing Test::Builder to implement
# subtests as a horrific hack. It also causes problems for tools that try
# to replace the singleton (also discouraged).

sub my_ok($;$) {
    my ($bool, $name) = @_;
    my $TB = Test::Builder->new;
    $TB->ok($bool, $name);
}

sub my_diag($) {
    my ($msg) = @_;
    my $TB = Test::Builder->new;
    $TB->diag($msg);
}

STREAM

use Test::Stream qw/context/;

sub my_ok($;$) {
    my ($bool, $name) = @_;
    my $ctx = context();
    $ctx->ok($bool, $name);
}

sub my_diag($) {
    my ($msg) = @_;
    $ctx->diag($msg);
}

The context object has API compatible implementations of the following methods:

ok($bool, $name)
diag(@messages)
note(@messages)
subtest($name, $code)

If you are looking for helpers with is, like, and others, see Test::More::Tools.

WRAP EXISTING TOOLS

LEGACY

use Test::Mote;

sub exclusive_ok {
    my ($bool1, $bool2, $name) = @_;

    # Ensure errors are reported 1 level higher
    local $Test::Builder::Level = $Test::Builder::Level + 1;

    $ok = $bool1 || $bool2;
    $ok &&= !($bool1 && $bool2);
    ok($ok, $name);

    return $bool;
}

Every single tool in the chain from this, to ok, to anything ok calls needs to increment the $Level variable. When an error occurs Test::Builder will do a trace to the stack frame determined by $Level, and report that file+line as the one where the error occured. If you or any other tool you use forgets to set $Level then errors will be reported to the wrong place.

STREAM

use Test::Mote;

sub exclusive_ok {
    my ($bool1, $bool2, $name) = @_;

    # Grab and store the context, even if you do not need to use it
    # directly.
    my $ctx = context();

    $ok = $bool1 || $bool2;
    $ok &&= !($bool1 && $bool2);
    ok($ok, $name);

    return $bool;
}

Instead of using $Level to perform a backtrace, Test::Stream uses a context object. In this sample you create a context object and store it. This locks the context (errors report 1 level up from here) for all wrapped tools to find. You do not need to use the context object, but you do need to store it in a variable. Once the sub ends the $ctx variable is destroyed which lets future tools find their own.

USING UTF8

LEGACY

# Set the mode BEFORE anything loads Test::Builder
use open ':std', ':encoding(utf8)';
use Test::More;

Or

# Modify the filehandles
my $builder = Test::More->builder;
binmode $builder->output,         ":encoding(utf8)";
binmode $builder->failure_output, ":encoding(utf8)";
binmode $builder->todo_output,    ":encoding(utf8)";

STREAM

use Test::Stream 'utf8';

or

use Test::Stream encoding => 'utf8'; # Or any other encoding

or

use Test::Stream qw/tap_encoding/;

# Use utf8 for one result
tap_encoding('utf8');
ok(1, "SOMETHING UTF8");

# Go back to the legacy encoding
tap_encoding('legacy');
ok(1, "Something ASCII");

With Test::Stream encoding is flexible and can be changed as needed.

AUTHORS, CONTRIBUTORS AND REVIEWERS

The following people have all contributed to this document in some way, even if only for review.

Chad Granum (EXODIST) <exodist@cpan.org>

SOURCE

The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.

MAINTAINER

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2015 Chad Granum <exodist7@gmail.com>.

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

See http://www.perl.com/perl/misc/Artistic.html