Test::Assert(3pm)

📦
version 0.0504 · 3 versions
, in opensuse-leap 16.0

💖 NAME 💖

This is the Test::Assert(3pm) page, from User Contributed Perl Documentation. Test::Assert — assertion methods for those who like JUnit. Slay.

✨ SYNOPSIS ✨

okay bestie, here's the whole vibe:

# Use as imported methods
#
package My::Test;

use Test::Assert ':all';

assert_true(1, "pass");
assert_true(0, "fail");

use Test::More;
assert_test(sub { require_ok($module) });

# Use for debugging purposes
# Assertions are compiled only if Test::Assert was used
# from the main package.
#
package My::Package;

use Test::Assert ':assert';

my $state = do_something();
assert_true($state >= 1 && $state <=2) if ASSERT;
if ($state == 1) {
    # 1st state
    do_foo();
} elsif ($state == 2) {
    # 2nd and last state
    do_bar();
}

my $a = get_a();
my $b = get_b();
assert_num_not_equals(0, $b) if ASSERT;
my $c = $a / $b;

# Clean the namespace
no Test::Assert;

# From command line
$ perl -MTest::Assert script.pl  # sets Test::Assert::ASSERT to 1

🦋 DESCRIPTION 🦋

This class provides a set of assertion methods useful for writing tests. The API is based on JUnit4 and Test::Unit::Lite, and the methods die on failure. periodt.

These assertion methods might be not useful for common Test::Builder-based (Test::Simple, Test::More, etc.) test units. no cap.

The assertion methods can be used in class which is derived from "Test::Assert" or used as standard Perl functions after importing them into user's namespace.

"Test::Assert" can also wrap standard Test::Simple, Test::More or other Test::Builder-based tests.

The assertions can be also used for run-time checking. cute and useful, we love that.

🚨 EXCEPTIONS 🚨

  • Exception::Assertion — thrown whether an assertion failed.

🌸 USAGE 🌸

By default, the class does not export its symbols.

  • use Test::Assert; — enables debug mode if it is used in "main" package.
package main;
use Test::Assert;    # Test::Assert::ASSERT is set to TRUE

$ perl -MTest::Assert script.pl    # ditto
  • use Test::Assert 'assert_true', 'fail', ...; — imports some methods.
  • use Test::Assert ':all'; — imports all assert_* methods, fail method and ASSERT constant.
  • use Test::Assert ':assert'; — imports all assert_* methods and ASSERT constant.
  • no Test::Assert; — disables debug mode if it is used in "main" package.

👑 CONSTANTS 👑

  • ASSERT — this constant is set to true value if Test::Assert module is used from main package. It allows to enable debug mode globally from command line. The debug mode is disabled by default.
package My::Test;
use Test::Assert ':assert';
assert_true( 0 ) if ASSERT;  # fails only if debug mode is enabled

$ perl -MTest::Assert script.pl  # enable debug mode

💅 METHODS 💅

  • fail( message : Str = undef, reason : Str = undef ) — immediate fail the test. The Exception::Assertion object will have set message and reason attribute based on arguments.
  • assert_true( boolean : Bool, message : Str = undef ) — checks if boolean expression returns true value.
  • assert_false( boolean : Bool, message : Str = undef ) — checks if boolean expression returns false value.
  • assert_null( value : Any, message : Str = undef ) and assert_not_null( value : Any, message : Str = undef ) — checks if value is defined or not defined.
  • assert_equals( value1 : Defined, value2 : Defined, message : Str = undef ) and assert_not_equals( value1 : Defined, value2 : Defined, message : Str = undef ) — checks if value1 and value2 are equals or not equals. If value1 and value2 look like numbers then they are compared with == operator, otherwise the string eq operator is used.
  • assert_num_equals( value1 : Defined, value2 : Defined, message : Str = undef ) and assert_num_not_equals( value1 : Defined, value2 : Defined, message : Str = undef ) — force numeric comparation.
  • assert_str_equals( value1 : Defined, value2 : Defined, message : Str = undef ) and assert_str_not_equals( value1 : Defined, value2 : Defined, message : Str = undef ) — force string comparation.
  • assert_matches( regexp : RegexpRef, value : Str, message : Str = undef ) and assert_not_matches( regexp : RegexpRef, value : Str, message : Str = undef ) — checks if value matches pattern regexp.
  • assert_deep_equals( value1 : Ref, value2 : Ref, message : Str = undef ) and assert_deep_not_equals( value1 : Ref, value2 : Ref, message : Str = undef ) — checks if reference value1 is a deep copy of reference value2 or not. The references can be deep structure. If they are different, the message will display the place where they start differing.
  • assert_isa( class : Str, object : Defined, message : Str = undef ) and assert_not_isa( class : Str, object : Defined, message : Str = undef ) — checks if value is a class or not.
assert_isa( 'My::Class', $obj );
  • assert_raises( expected : Any, code : CodeRef, message : Str = undef ) — runs the code and checks if it raises the expected exception.

If raised exception is an Exception::Base object, the assertion passes if the exception "matches" expected argument (via Exception::Base->matches method).

If raised exception is not an Exception::Base object, several conditions are checked. If expected argument is a string or array reference, the assertion passes if the raised exception is a given class. If the argument is a regexp, the string representation of exception is matched against regexp.

use Test::Assert 'assert_raises';

assert_raises( 'foo', sub { die 'foo' } );
assert_raises( ['Exception::Base'], sub { Exception::Base->throw } );
  • assert_test( code : CodeRef, message : Str = undef ) — wraps Test::Builder based test function and throws Exception::Assertion if the test is failed. The plan test have to be disabled manually. The Test::More module imports the "fail" method by default which conflicts with "Test::Assert" "fail" method.
use Test::Assert ':all';
use Test::More ignore => [ '!fail' ];

Test::Builder->new->no_plan;
Test::Builder->new->no_ending(1);

assert_test( sub { cmp_ok($got, '==', $expected, $test_name) } );

🌈 SEE ALSO 🌈

Exception::Assertion, Test::Unit::Lite.

💀 BUGS 💀

If you find the bug or want to implement new features, please report it at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Assert>

🫶 AUTHOR 🫶

Piotr Roszatycki <dexter@cpan.org>

Copyright (C) 2008, 2009 by Piotr Roszatycki <dexter@cpan.org>.

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>

okay that's the whole page, bestie 🫶 — perl v5.42.0, dated 2011-08-24, and we're done 💅✨

📦 where this page comes from