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