Tests

Unit and integration tests for the XP Framework

Writing a test

Tests reside inside a class suffixed by "Test" (a test group) and consist of methods annotated with the Test attribute (the test cases). The convention for test method naming is to use lowercase, words separated by underscores, though this is not strictly necessary.

usetest\{Assert, Test};
class CalculatorTest {
#[Test]
publicfunctionaddition() {
Assert::equals(2, (newCalculator())->add(1, 1));
}
}

To run these tests, use the test subcommand:

$ xp test CalculatorTest.class.php
> [PASS] CalculatorTest
✓ addition
Tests cases: 1 succeeded, 0 skipped, 0 failed
Memory used: 1556.36 kB (1610.49 kB peak)
Time taken: 0.001 seconds

Assertions

The following shorthand methods exist on the Assert class:

• equals(mixed $expected, mixed $actual) - check two values are equal. Uses the util.Objects::equal() method internally, which allows overwriting object comparison.
• notEquals(mixed $expected, mixed $actual) - opposite of above
• true(mixed $actual) - check a given value is equal to the true boolean
• false(mixed $actual) - check a given value is equal to the false boolean
• null(mixed $actual) - check a given value is null
• instance(string|lang.Type $expected, mixed $actual) - check a given value is an instance of the given type.
• matches(string $pattern, mixed $actual) - verify the given value matches a given regular expression.
• throws(string|lang.Type $expected, callable $actual) - verify the given callable raises an exception.

Expected failures

Using the Expect annotation, we can write tests that assert a given exception is raised:

usetest\{Assert, Expect, Test};
class CalculatorTest {
#[Test, Expect(DivisionByZero::class)]
publicfunctiondivision_by_zero() {
(newCalculator())->divide(1, 0);
}
}

To check the expected exceptions' messages, use the following:

• Any message: Expect(DivisionByZero::class)
• Exact message: Expect(DivisionByZero::class, 'Division by zero')
• Message matching regular expression: Expect(DivisionByZero::class, '/Division by (0|zero)/i')

Value-driven tests

To keep test code short and concise, tests may be value-driven. Values can be provided either directly inline:

usetest\{Assert, Test, Values};
class CalculatorTest {
#[Test, Values([[0, 0], [1, 1], [-1, 1]])]
publicfunctionaddition($a, $b) {
Assert::equals($a + $b, (newCalculator())->add($a, $b));
}
}

...or by referencing a provider method as follows:

usetest\{Assert, Test, Values};
class CalculatorTest {
privatefunctionoperands(): iterable {
yield [0, 0];
yield [1, 1];
yield [-1, 1];
}
#[Test, Values(from: 'operands')]
publicfunctionaddition($a, $b) {
Assert::equals($a + $b, (newCalculator())->add($a, $b));
}
}

Prerequisites

Test classes and methods may have prerequisites, which must successfully verify in order for the tests to run:

usetest\verify\Runtime;
usetest\{Assert, Test};
#[Runtime(extensions: ['bcmath'])]
class CalculatorTest {
#[Test]
publicfunctionaddition() {
Assert::equals(3, (int)bcadd(1, 2));
}
}

The following verifications are included:

• Runtime(os: '^WIN', php: '^8.0', extensions: ['bcmath']) - runtime verifications.
• Condition(assert: 'function_exists("random_int")') - verify given expression in the context of the test class.

Passing arguments to tests

Especially for integration tests, passing values like a connection string from the command line to the test class is important. Add the Args annotation to the class as follows:

usetest\Args;
usecom\mongodb\MongoConnection;
#[Args('use')]
class IntegrationTest {
private$conn;
publicfunction__construct(string$dsn) {
$this->conn= newMongoConnection($dsn);
}
// ...shortened for brevity
}

...then pass the arguments as follows:

$ xp test IntegrationTest --use=mongodb://locahost
# ...

See also

• RFC #344: New testing library