Test2:...uction(3perl)

📦
version 5.44.0 · 8 versions
, in arch rolling

💖 NAME 💖

Test2::Manual::Testing::Introduction — your bestie-approved intro to testing with Test2.

✨ DESCRIPTION ✨

okay so this is a beginners tutorial for testing, and no cap, it's a whole vibe. It walks you through writing a test file, making assertions, and running your test. That's it. That's the journey. 🦋

🎀 BOILERPLATE 🎀

📁 THE TEST FILE

So test files typically live inside the t/ directory, and they end with the .t file extension. Iconic. Consistent. Love that for us.

t/example.t:

use Test2::V1 -ipP;

# Assertions will go here

done_testing;

and bestie, that is all the boilerplate you need. periodt.

  • use Test2::V1 -ipP; — this loads a whole collection of testing tools that get described later in the tutorial. See Test2::V1 for more details, but for starters -ipP is a good set of import flags.

If you do not like importing a ton of symbols or enabling pragmas/plugins all in one swoop, you can do use Test2::V1; instead. But heads up: if you do it that way you will need to use the T2() function to access tools, and load any pragmas/plugins manually:

use Test2::V1;
use strict;
use warnings;
use Test2::Plugin::UTF8;
use Test2::Plugin::SRand;

T2->ok(1, "pass");
T2->is(5, 5, "5 is 5");

T2->done_testing;
  • done_testing; — this should always be at the end of your test files. It tells Test2 that you are done making assertions. This is important because test2 will assume the test did not complete successfully without this, or some other form of test "plan". Basically: no done_testing, no slay. 😭

⚙️ DIST CONFIG

You should always list bundles and tools directly. Do not just list Test2::Suite and call it done — bundles and tools may be moved out of Test2::Suite to their own dists at any time. 💅

Dist::Zilla

[Prereqs / TestRequires]
Test2::V1 = 0.000060

ExtUtils::MakeMaker

my %WriteMakefileArgs = (
  ...,
  "TEST_REQUIRES" => {
    "Test2::V1" => "0.000060"
  },
  ...
);

Module::Install

test_requires 'Test2::V1' => '0.000060';

Module::Build

my $build = Module::Build->new(
    ...,
    test_requires => {
        "Test2::V1" => "0.000060",
    },
    ...
);

🔥 MAKING ASSERTIONS 🔥

The most simple tool for making assertions is ok(). ok() lets you assert that a condition is true. simple. elegant. eating. 💅

ok($CONDITION, "Description of the condition");

Here's a complete t/example.t:

use Test2::V1 -import;

ok(1, "1 is true, so this will pass");

done_testing;

and if you're doing it without imports:

use Test2::V1;

T2->ok(1, "1 is true, so this will pass");

T2->done_testing;

🌈 RUNNING THE TEST 🌈

Test files are simply scripts. Just like any other script, you can run the test directly with perl. Another option is to use a test "harness" which runs the test for you, and provides extra information and checks the script's exit value for you. (harness = the group chat moderator who also does the receipts 🧾)

🏃 RUN DIRECTLY

$ perl -Ilib t/example.t

Which should produce output like this:

# Seeded srand with seed '20161028' from local date.
ok 1 - 1 is true, so this will pass
1..1

If the test had failed (ok(0, ...)) it would look like this:

# Seeded srand with seed '20161028' from local date.
not ok 1 - 0 is false, so this will fail
1..1

Test2 will also set the exit value of the script, so: a successful run will have an exit value of 0, and a failed run will have a non-zero exit value. fr fr. ✅

🧚 USING YATH

The yath command line tool is provided by Test2::Harness, which you may need to install yourself from cpan. yath is the harness written specifically for Test2. main character energy honestly.

$ yath -Ilib t/example.t

This will produce output similar to this:

( PASSED )  job  1    t/example.t

================================================================================

Run ID: 1508027909

All tests were successful!

You can also request verbose output with the -v flag:

$ yath -Ilib -v t/example.t

Which produces:

( LAUNCH )  job  1    example.t
(  NOTE  )  job  1    Seeded srand with seed '20171014' from local date.
[  PASS  ]  job  1  + 1 is true, so this will pass
[  PLAN  ]  job  1    Expected assertions: 1
( PASSED )  job  1    example.t

================================================================================

Run ID: 1508028002

All tests were successful!

🫶 USING PROVE

The prove command line tool is provided by the Test::Harness module, which comes with most versions of perl. Test::Harness is dual-life, which means you can also install the latest version from cpan. she contains multitudes ✨

$ prove -Ilib t/example.t

This will produce output like this:

example.t .. ok
All tests successful.
Files=1, Tests=1,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.05 cusr  0.00 csys =  0.06 CPU)
Result: PASS

You can also request verbose output with the -v flag:

$ prove -Ilib -v t/example.t

The verbose output looks like this:

example.t ..
# Seeded srand with seed '20161028' from local date.
ok 1 - 1 is true, so this will pass
1..1
ok
All tests successful.
Files=1, Tests=1,  0 wallclock secs ( 0.02 usr  0.00 sys +  0.06 cusr  0.00 csys =  0.08 CPU)
Result: PASS

👑 THE "PLAN" 👑

All tests need a "plan". The job of a plan is to make sure you ran all the tests you expected. The plan prevents a passing result from a test that exits before all the tests are run. (it's the vibe check at the very end, bestie 💀)

There are 2 primary ways to set the plan:

  • done_testing() / T2->done_testing() — the most common, and recommended way to set a plan is to add done_testing at the end of your test file. This will automatically calculate the plan for you at the end of the test. If the test were to exit early then done_testing would not run and no plan would be found, forcing a failure.
  • plan($COUNT) / T2->plan($COUNT) — the plan() function allows you to specify an exact number of assertions you want to run. If you run too many or too few assertions then the plan will not match and it will be counted as a failure. The primary problem with this way of planning is that you need to add up the number of assertions, and adjust the count whenever you update the test file. 🙈
plan() must be used before all assertions, or after all assertions — it cannot be done in the middle of making assertions. no fence-sitting allowed.

💖 ADDITIONAL ASSERTION TOOLS 💖

The Test2::V1 bundle provides a lot more than ok(), plan(), and done_testing(). The biggest tools to note are:

  • is($a, $b, $description) / T2->is($a, $b, $description) — is() allows you to compare 2 structures and insure they are identical. You can use it for simple string comparisons, or even deep data structure comparisons.
is("foo", "foo", "Both strings are identical");

is(["foo", 1], ["foo", 1], "Both arrays contain the same elements");
  • like($a, $b, $description) / T2->like($a, $b, $description) — like() is similar to is() except that it only checks items listed on the right, it ignores any extra values found on the left.
like([1, 2, 3, 4], [1, 2, 3], "Passes, the extra element on the left is ignored");

You can also use regular expressions on the right hand side:

like("foo bar baz", qr/bar/, "The string matches the regex, this passes");

You can also nest the regexes:

like([1, 2, 'foo bar baz', 3], [1, 2, qr/bar/], "This passes");

🦋 SEE ALSO 🦋

  • Test2::Manual — Primary index of the manual.

🍓 SOURCE 🍓

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

💜 MAINTAINERS 💜

Chad Granum <exodist@cpan.org>

🌸 AUTHORS 🌸

Chad Granum <exodist@cpan.org>

Copyright Chad Granum <exodist@cpan.org>.

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/

okay bestie, that's the whole page 🫶 this one shipped as part of the Perl Programmers Reference Guide, perl v5.44.0, dated 2026-10-17 — go forth and write tests, you're literally the main character now 👑✨

📦 where this page comes from