README

Unittests for the XP Framework

Writing a test

Tests reside inside a class and are annotated with the @test attribute.

use unittest\{Assert, Test}; class CalculatorTest { #[Test] public function addition() { Assert::equals(2, 1 + 1); } }

To run the test, use the test subcommand:

$ xp test CalculatorTest [.] ♥: 1/1 run (0 skipped), 1 succeeded, 0 failed Memory used: 1672.58 kB (1719.17 kB peak) Time taken: 0.000 seconds

Assertion methods

The unittest package provides the following six assertion methods:

public abstract class unittest.Assert { public static void equals(var $expected, var $actual, string $error)  public static void notEquals(var $expected, var $actual, string $error) public static void true(var $actual, string $error) public static void false(var $actual, string $error) public static void null(var $actual, string $error)  public static void instance(string|lang.Type $type, var $actual, string $error)  public static void throws(string|lang.Type $type, callable $block) }

If you need more than that, you can use xp-forge/assert on top of this library.

Setup and teardown

In order to run a method before and after the tests are run, annotate methods with the @before and @after attributes:

use unittest\{Assert, Before, After, Test}; class CalculatorTest { private $fixture; #[Before] public function newFixture() { $this->fixture= new Calculator(); } #[After] public function cleanUp() { unset($this->fixture); } #[Test] public function addition() { Assert::equals(2, $this->fixture->add(1, 1)); } }

Note: All test methods are run with the same instance of CalculatorTest!

Expected exceptions

The Expect attribute is a shorthand for catching exceptions and verifying their type manually.

use lang\IllegalArgumentException; use unittest\{Test, Expect}; class CalculatorTest { #[Test, Expect(IllegalArgumentException::class)] public function cannot_divide_by_zero() { (new Calculator())->divide(1, 0); } }

Ignoring tests

The Ignore attribute can be used to ignore tests. This can be necessary as a temporary measure or when overriding a test base class and not wanting to run one of its methods.

use unittest\{Test, Ignore}; class EncodingTest { #[Test, Ignore('Does not work with all iconv implementations')] public function transliteration() { /* ... */ } }

Parameterization

The Values attribute can be used to run a test with a variety of values which are passed as parameters.

use lang\IllegalArgumentException; use unittest\{Test, Expect, Values}; class CalculatorTest { #[Test, Expect(IllegalArgumentException::class), Values([1, 0, -1])] public function cannot_divide_by_zero($dividend) { (new Calculator())->divide($dividend, 0); } }

Actions

To execute code before and after tests, test actions can be used. The unittest library comes with the following built-in actions:

• unittest.actions.ExtensionAvailable(string $extension) - Verifies a given PHP extension is loaded.
• unittest.actions.IsPlatform(string $platform) - Verifies tests are running on a given platform via case-insensitive match on PHP_OS. Prefix with ! to invert.
• unittest.actions.RuntimeVersion(string $version) - Verifies tests are running on a given PHP runtime. See version_compare for valid syntax.
• unittest.actions.VerifyThat(function(): var|string $callable) - Runs the given function, verifying it neither raises an exception nor return a false value.

use unittest\actions\{IsPlatform, VerifyThat}; use unittest\{Test, Action}; class FileSystemTest { #[Test, Action(eval: 'new IsPlatform("!WIN")')] public function not_run_on_windows() { // ... } #[Test, Action(eval: 'new VerifyThat(fn() => file_exists("/\$Recycle.Bin");')] public function run_when_recycle_bin_exists() { // ... } }

Multiple actions can be run around a test by passing an array to the @action attribute.

Further reading

• XP RFC #0283: Unittest closure actions
• XP RFC #0272: Unittest actions
• XP RFC #0267: Unittest parameterization
• XP RFC #0188: Test outcome
• XP RFC #0187: @expect withMessage
• XP RFC #0150: Before and after methods for test cases
• XP RFC #0145: Make unittests strict
• XP RFC #0059: Timeouts for unittests
• XP RFC #0032: Add attributes for Unittest API
• XP RFC #0020: Metadata for unittests