NAME

App::Yath::Converting - Things you may need to change in your tests before you can use yath.

UTF8 STDERR/STDOUT THAT POINT AT FILES

By default yath tells any Test2 or Test::Builder tests to use Test2::Formatter::Stream instead of Test2::Formatter::TAP. This is done in order to make sure as much data as possible makes it to yath, TAP is a lossy formater by comparison. A consequence of this is that STDOUT and STDERR are redirected to files, and the ':utf8' encoding is set.

GOTCHAS / CAVEATS

syswrite

If your test uses syswrite on STDERR/STDOUT you will be hit by a warning in some perl versions, and it will be fatal in 5.30+. This is because syswrite on utf8 filehandle is a bad thing.

print

If you print non-utf8 characters to STDERR/STDOUT you will get wide character in print warnings under yath.

is / is_deeply / diag

If you compare non-utf8 strings in testing tools like is` they will report diagnostics which include the non-utf8 characters, which will result in wide character warnings.

SOLUTIONS

Update your test

Update your test to use UTF8. In many cases this is as simple as importing Test2::Plugin::UTF8.

    #!/usr/bin/perl
    use Test2::Plugin::UTF8;
    ...

This sets all output handles (STDERR/STDOUT) including those of any Test2::Formatter subclasses to use utf8. This will also import the utf8 pragma for you to read your test fiel source as utf8.

HARNESS-NO-STREAM

You can add a harness directive to the top of offending tests that tell the harness those specific tests should still use the TAP formatter.

    #!/usr/bin/perl
    # HARNESS-NO-STREAM
    ...

This directive can come after the #! line, and after use statements, but must come BEFORE any empty lines or runtime statements.

--no-stream

You can run yath with the --no-stream option, which will have tests default to TAP. This is not recommended as TAP is lossy.

TESTS ARE RUN VIA FORK BY DEFAULT

The default mode for yath is to preload a few things, then fork to spawn each test. This is a complicated procedure, and it uses goto::file under the hood. Sometimes you have tests that simply will not work this way, or tests that verify specific libraries are not already loaded.

SOLUTIONS

HARNESS-NO-PRELOAD

You can use this harness directive inside your tests to tell yath not to fork, but to instead launch a new perl process to run the test.

    #!/usr/bin/perl
    # HARNESS-NO-PRELOAD
    ...

--no-fork

--no-preload

Both these options tell yath not to preload+fork, but to run ALL tests in new processes. This is slow, it is better to mark specific tests that have issues in preload mode.

SOURCE

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

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2020 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://dev.perl.org/licenses/

cpanm Test2::Harness

perl -MCPAN -e shell
install Test2::Harness