NAME

Test::Assert - Assertion methods for those who like JUnit.

SYNOPSIS

  # 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.

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

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.

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 )

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 )

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 )

assert_num_not_equals( value1 : Defined, value2 : Defined, message : Str = undef )

Force numeric comparation.

assert_str_equals( value1 : Defined, value2 : Defined, message : Str = undef )

assert_str_not_equals( value1 : Defined, value2 : Defined, message : Str = undef )

Force string comparation.

assert_matches( regexp : RegexpRef, value : Str, message : Str = undef )

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 )

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 )

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

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