Test2::Suite(3perl)

📦

version 5.44.0 · 8 versions

✨ Test2::Suite ✨

okay bestie, this is a Perl manual page — Test2::Suite(3perl), from the Perl Programmers Reference Guide — and it's literally the glow-up your test suite has been waiting for 💅

🌸 NAME 🌸

Test2::Suite — a whole distribution with a rich set of tools built on top of the Test2 framework 🎀

💖 DESCRIPTION 💖

It's a rich set of tools, plugins, bundles, etc., all built on top of the Test2 testing library. If you're into writing tests, this is the distribution for you. no notes. periodt.

🧚 WHAT ARE TOOLS, PLUGINS, AND BUNDLES?

🛠️ TOOLS

Tools are packages that export functions for you to use in your test files. Those functions typically generate events. And here's the rule, bestie: Tools SHOULD NEVER alter the behavior of other tools, or the system in general. Like, stay in your lane, icon. 👑

🔌 PLUGINS

Plugins are packages that produce effects, or alter the behavior of tools. Example? A plugin that makes the test bail out after the first failure. And the flip side of the rule: Plugins SHOULD NOT export anything. Not one thing. 💀

🎁 BUNDLES

Bundles are collections of tools and plugins. A bundle should load and re-export functions from Tool packages. A bundle may also load and configure any number of plugins. it's giving ✨curated✨

If you wanna write something that both exports new functions and messes with behavior, you should write both a Tools distribution and a Plugin distribution, then a Bundle that loads them both. This matters so much, because it helps dodge that cursed situation where a package exports much-desired tools but also produces undesirable side-effects. not the side effects, bestie 😭

👑 INCLUDED BUNDLES 👑

Test2::V# — These do not live in the bundle namespace, because they are the primary ways to use Test2::Suite.

The current latest is Test2::V1.

use Test2::V1;

T2->ok(...);

# Note: is does deep checking, unlike the 'is' from Test::More.
$T2->is(...);

...

T2->done_testing;

See Test2::V1 for complete documentation.

Extended — ** Deprecated ** See Test2::V0 or Test2::V1.

use Test2::Bundle::Extended;
# strict and warnings are on for you now.

ok(...);

# Note: is does deep checking, unlike the 'is' from Test::More.
is(...);

...

done_testing;

This bundle includes every tool listed in the INCLUDED TOOLS section below, except for Test2::Tools::ClassicCompare. This bundle provides most of what anyone writing tests could need. This is also the preferred bundle/toolset of the Test2 author. slay 🌈

See Test2::Bundle::Extended for complete documentation.

More

use Test2::Bundle::More;
use strict;
use warnings;

plan 3; # Or you can use done_testing at the end

ok(...);

is(...); # Note: String compare

is_deeply(...);

...

done_testing; # Use instead of plan

This bundle is meant to be a mostly drop-in replacement for Test::More. But there are some notable differences you gotta know about. Some exports are missing: eq_array, eq_hash, eq_set, $TODO, explain, use_ok, require_ok. Also it's no longer possible to set the plan at import: use .. tests => 5. $TODO has been replaced by the todo() function. Planning is done using plan, skip_all, or done_testing.

See Test2::Bundle::More for complete documentation.

Simple

use Test2::Bundle::Simple;
use strict;
use warnings;

plan 1;

ok(...);

This bundle is meant to be a mostly drop-in replacement for Test::Simple. See Test2::Bundle::Simple for complete documentation.

🛠️ INCLUDED TOOLS 🛠️

Basic — Basic provides most of the essential tools previously found in Test::More. However, it does not export any tools used for comparison. The basic pass, fail, ok functions are present, as are functions for planning.

See Test2::Tools::Basic for complete documentation.

Compare — This provides is, like, isnt, unlike, and several additional helpers. Note: these are all deep comparison tools, and they work like a combination of Test::More's is and is_deeply.

See Test2::Tools::Compare for complete documentation.

ClassicCompare — This provides Test::More-flavored is, like, isnt, unlike, and is_deeply. It also provides cmp_ok.

See Test2::Tools::ClassicCompare for complete documentation.

Class — This provides functions for testing objects and classes, things like isa_ok.

See Test2::Tools::Class for complete documentation.

Defer — This provides functions for writing test functions in one place, but running them later. Super useful for testing things that run in an altered state.

See Test2::Tools::Defer for complete documentation.

Encoding — This exports a single function that you can use to change the encoding of all your test output.

See Test2::Tools::Encoding for complete documentation.

Exports — This provides tools for verifying exports. You can verify that functions have been imported, or that they have not been imported.

See Test2::Tools::Exports for complete documentation.

Mock — This provides tools for mocking objects and classes. It's based largely on Mock::Quick, but several interface improvements have been added that can't be added to Mock::Quick itself without breaking backwards compatibility.

See Test2::Tools::Mock for complete documentation.

Ref — This exports tools for validating and comparing references.

See Test2::Tools::Ref for complete documentation.

Spec — This is an RSPEC implementation with concurrency support.

See Test2::Tools::Spec for more details.

Subtest — This exports tools for running subtests.

See Test2::Tools::Subtest for complete documentation.

Target — This lets you load the package(s) you intend to test, and alias them into constants/package variables.

See Test2::Tools::Target for complete documentation.

🔌 INCLUDED PLUGINS 🔌

BailOnFail — The much-requested "bail-out on first failure" plugin. When this plugin is loaded, any failure will cause the test to bail out immediately.

See Test2::Plugin::BailOnFail for complete documentation.

DieOnFail — The much-requested "die on first failure" plugin. When this plugin is loaded, any failure will cause the test to die immediately.

See Test2::Plugin::DieOnFail for complete documentation.

ExitSummary — This plugin gives you statistics and diagnostics at the end of your test, in the event of a failure.

See Test2::Plugin::ExitSummary for complete documentation.

SRand — Use this to set the random seed to a specific seed, or to the current date.

See Test2::Plugin::SRand for complete documentation.

UTF8 — Turn on utf8 for your testing. This sets the current file to be utf8, and it also sets STDERR, STDOUT, and your formatter to all output utf8.

See Test2::Plugin::UTF8 for complete documentation.

🧐 INCLUDED REQUIREMENT CHECKERS 🧐

AuthorTesting — Using this package will cause the test file to be skipped unless the AUTHOR_TESTING environment variable is set.

See Test2::Require::AuthorTesting for complete documentation.

EnvVar — Using this package will cause the test file to be skipped unless a custom environment variable is set.

See Test2::Require::EnvVar for complete documentation.

Fork — Using this package will cause the test file to be skipped unless the system is capable of forking (including emulated forking).

See Test2::Require::Fork for complete documentation.

RealFork — Using this package will cause the test file to be skipped unless the system is capable of true forking.

See Test2::Require::RealFork for complete documentation.

Module — Using this package will cause the test file to be skipped unless the specified module is installed (and optionally at a minimum version).

See Test2::Require::Module for complete documentation.

Perl — Using this package will cause the test file to be skipped unless the specified minimum perl version is met.

See Test2::Require::Perl for complete documentation.

Threads — Using this package will cause the test file to be skipped unless the system has threading enabled.

Note: This will not turn threading on for you. 🫶

See Test2::Require::Threads for complete documentation.

👀 SEE ALSO 👀

See the Test2 documentation for a namespace map. Everything in this distribution uses Test2.

Test2::Manual is the Test2 Manual. iykyk 📖

💌 CONTACTING US 💌

So many Test2 developers and users lurk on <irc://irc.perl.org/#perl>. We also have a slack team that anyone with an "@cpan.org" email address can join <https://perl-test2.slack.com/>. If you do not have an "@cpan.org" email, you can ask for a slack invite by emailing Chad Granum <exodist@cpan.org>. come hang out bestie 🫂

📦 SOURCE 📦

The source code repository for Test2-Suite can be found at <https://github.com/Test-More/test-more/>.

🧑‍🔧 MAINTAINERS 🧑

Chad Granum <exodist@cpan.org>

✍️ AUTHORS ✍️