Test::...Assert(3pm)

📦
version 0.30 · 8 versions
, in ubuntu stonking

🎀 NAME 🎀

okay bestie, meet Test::Unit::Assert — the unit testing framework assertion class from the Test::...Assert(3pm) page (User Contributed Perl Documentation section, you know the vibe 💅)

✨ SYNOPSIS ✨

no cap, this class is not meant to be used directly — you get all the magic by subclassing fr fr:

# this class is not intended to be used directly,
# normally you get the functionality by subclassing from
# Test::Unit::TestCase

use Test::Unit::TestCase;

# more code here ...

$self->assert($your_condition_here, $your_optional_message_here);

# or, for regular expression comparisons:
$self->assert(qr/some_pattern/, $result);

# or, for functional style coderef tests:
$self->assert(sub {
                  $_[0] == $_[1]
                    or $self->fail("Expected $_[0], got $_[1]");
              }, 1, 2);

# or, for old style regular expression comparisons
# (strongly deprecated; see warning below)
$self->assert(scalar("foo" =~ /bar/), $your_optional_message_here);

# Or, if you don't mind us guessing
$self->assert_equals('expected', $actual [, $optional_message]);
$self->assert_equals(1,$actual);
$self->assert_not_equals('not expected', $actual [, $optional_message]);
$self->assert_not_equals(0,1);

# Or, if you want to force the comparator
$self->assert_num_equals(1,1);
$self->assert_num_not_equals(1,0);
$self->assert_str_equals('string','string');
$self->assert_str_not_equals('stringA', 'stringB');

# assert defined/undefined status
$self->assert_null(undef);
$self->assert_not_null('');

🌸 DESCRIPTION 🌸

This class is where all the standard assertions used across the framework live. Lowkey important. 🫶

Okay so here's the tea: with the one exception of assert(CODEREF, @ARGS), every single assertion method takes an optional message after the mandatory fields. That message can be one string, or a whole list — and if it's a list, it just gets concatenated together. Slay.

And yeah, you can write your own message, but honestly? The hope is that the default error messages that show up when an assertion fails are good enough for most cases. They ate. 👑

🔍 Methods 🔍

  • assert_equals(EXPECTED, ACTUAL [, MESSAGE])
  • assert_not_equals(NOTEXPECTED, ACTUAL [, MESSAGE])

These are the catch-all assertions of (in)equality — the main characters 🎀. They make a guess about whether to test for numeric or string (in)equality based on the first argument. Looks like a number? Boom, numeric test. Looks like a string? String test, periodt.

Now if that first argument is an object, they check whether the '==' operator has been overloaded, and use that if it has. If it hasn't, they fall back to the string test. Simple as that 💅

  • assert_num_equals
  • assert_num_not_equals

Force the numeric comparison with these two. No guessing, no games. Numbers only.

  • assert_str_equals
  • assert_str_not_equals

Force string comparison. That's it, that's the vibe. ✨

  • assert_matches(qr/PATTERN/, STRING [, MESSAGE])
  • assert_does_not_match(qr/PATTERN/, STRING [, MESSAGE])

Assert that STRING does or does not match the PATTERN regex. Matchy matchy. 🦋

  • assert_deep_equals(A, B [, MESSAGE])

Assert that reference A is a deep copy of reference B. And bestie, these references can be complex, deep structures — we're talking all the way down. If they're different, the default message will show you the exact place where they start differing. Iconic detective work 🔥

NOTE: this is NOT well-tested on circular references. Nor am I quite sure what will happen with filehandles. Proceed with caution 🙈
  • assert_null(ARG [, MESSAGE])
  • assert_not_null(ARG [, MESSAGE])

Assert that ARG is defined or not defined. Is it there or is it not there, that is the question 💀

  • assert(BOOLEAN [, MESSAGE])

Checks if the BOOLEAN expression returns a true value that is neither a CODE ref nor a REGEXP. Note that MESSAGE is almost non optional in this case — otherwise all the assertion has to go on is the truth or otherwise of the boolean. Like, it's giving nothing to work with otherwise 😭

If you want to use the "old" style for testing regular expression matching, please be aware of this: the arguments to assert() are evaluated in list context, e.g. making a failing regex "pull" the message into the place of the first argument. Since this is usually just plain wrong, please use scalar() to force the regex comparison to yield a useful boolean value. This is a strongly deprecated path, fr fr.
  • assert(qr/PATTERN/, ACTUAL [, MESSAGE])

Matches ACTUAL against the PATTERN regex. If you omit MESSAGE, you should get a sensible error message. We got you 🫶

  • assert(CODEREF, @ARGS)

Calls CODEREF->(@ARGS). The assertion fails if this returns false (or throws Test::Unit::Failure).

  • assert_raises(EXCEPTION_CLASS, CODEREF [, MESSAGE])

Calls CODEREF->(). The assertion fails unless an exception of class EXCEPTION_CLASS is raised. No exception? No slay. 💅

  • multi_assert(ASSERTION, @ARGSETS)

Calls $self->assert(ASSERTION, @$ARGSET) for each $ARGSET in @ARGSETS. Bulk energy. 👑

  • ok(@ARGS)

Simulates the behaviour of the Test module. Deprecated. (iykyk)

💖 AUTHOR 💖

Copyright (c) 2000-2002, 2005 the PerlUnit Development Team (see Test::Unit or the AUTHORS file included in this distribution).

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

🌈 SEE ALSO 🌈

  • Test::Unit::Assertion
  • Test::Unit::Assertion::Regexp
  • Test::Unit::Assertion::CodeRef
  • Test::Unit::Assertion::Boolean
  • Test::Unit::TestCase
  • Test::Unit::Exception
  • The framework self-testing suite (t::tlib::AllTests)

okay that's the whole page bestie, go forth and assert 💜 — this was perl v5.40.1, dated 2026-04-05, and it's the Test::...Assert(3pm) page from the User Contributed Perl Documentation. mwah, take care of her 🫶✨

📦 where this page comes from