Unittests

Unittests for the XP Framework

Writing a test

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

use unittest\Assert;

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)
}

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 annotations:

use unittest\Assert;

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 annotation is a shorthand for catching exceptions and verifying their type manually.

use lang\IllegalArgumentException;

class CalculatorTest {

  #[@test, @expect(IllegalArgumentException::class)]
  public function cannot_divide_by_zero() {
    (new Calculator())->divide(1, 0);
  }
}

Ignoring tests

The @ignore annotation 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.

class EncodingTest {

  #[@test, @ignore('Does not work with all iconv implementations')]
  public function transliteration() {
    /* ... */
  }
}

Parameterization

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

use lang\IllegalArgumentException;

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};

class FileSystemTest {

  #[@test, @action(new IsPlatform('!WIN'))
  public function not_run_on_windows() {
    // ...
  }

  #[@test, @action(new VerifyThat(function() {
  #  return 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 annotation.

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 annotations for Unittest API
• XP RFC #0020: Metadata for unittests