PHPackages                             xp-framework/test - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. xp-framework/test

ActiveLibrary[Testing & Quality](/categories/testing)

xp-framework/test
=================

Testing for the XP Framework

v2.2.1(5mo ago)0223.9k↑16.7%[1 PRs](https://github.com/xp-framework/test/pulls)20BSD-3-ClausePHPPHP >=7.4.0CI passing

Since Feb 9Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/xp-framework/test)[ Packagist](https://packagist.org/packages/xp-framework/test)[ Docs](http://xp-framework.net/)[ RSS](/packages/xp-framework-test/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (15)Used By (20)

Tests
=====

[](#tests)

[![Build status on GitHub](https://github.com/xp-framework/test/workflows/Tests/badge.svg)](https://github.com/xp-framework/test/actions)[![XP Framework Module](https://raw.githubusercontent.com/xp-framework/web/master/static/xp-framework-badge.png)](https://github.com/xp-framework/core)[![BSD Licence](https://raw.githubusercontent.com/xp-framework/web/master/static/licence-bsd.png)](https://github.com/xp-framework/core/blob/master/LICENCE.md)[![Requires PHP 7.4+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-7_4plus.svg)](http://php.net/)[![Supports PHP 8.0+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-8_0plus.svg)](http://php.net/)[![Latest Stable Version](https://camo.githubusercontent.com/126bcba3cdf1c8736604b7658da78deea4d5da036cdc9800352efc7e292c58fc/68747470733a2f2f706f7365722e707567782e6f72672f78702d6672616d65776f726b2f746573742f76657273696f6e2e737667)](https://packagist.org/packages/xp-framework/test)

Unit and integration tests for the XP Framework

Writing a test
--------------

[](#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.

```
use test\{Assert, Test};

class CalculatorTest {

  #[Test]
  public function addition() {
    Assert::equals(2, (new Calculator())->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
----------

[](#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
-----------------

[](#expected-failures)

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

```
use test\{Assert, Expect, Test};

class CalculatorTest {

  #[Test, Expect(DivisionByZero::class)]
  public function division_by_zero() {
    (new Calculator())->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
------------------

[](#value-driven-tests)

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

```
use test\{Assert, Test, Values};

class CalculatorTest {

  #[Test, Values([[0, 0], [1, 1], [-1, 1]])]
  public function addition($a, $b) {
    Assert::equals($a + $b, (new Calculator())->add($a, $b));
  }
}
```

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

```
use test\{Assert, Test, Values};

class CalculatorTest {

  private function operands(): iterable {
    yield [0, 0];
    yield [1, 1];
    yield [-1, 1];
  }

  #[Test, Values(from: 'operands')]
  public function addition($a, $b) {
    Assert::equals($a + $b, (new Calculator())->add($a, $b));
  }
}
```

Prerequisites
-------------

[](#prerequisites)

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

```
use test\verify\Runtime;
use test\{Assert, Test};

#[Runtime(extensions: ['bcmath'])]
class CalculatorTest {

  #[Test]
  public function addition() {
    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
--------------------------

[](#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:

```
use test\Args;
use com\mongodb\MongoConnection;

#[Args('use')]
class IntegrationTest {
  private $conn;

  public function __construct(string $dsn) {
    $this->conn= new MongoConnection($dsn);
  }

  // ...shortened for brevity
}
```

...then pass the arguments as follows:

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

See also
--------

[](#see-also)

- [RFC #344: New testing library](https://github.com/xp-framework/rfc/issues/344)

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance72

Regular maintenance activity

Popularity31

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~86 days

Recently: every ~225 days

Total

13

Last Release

156d ago

Major Versions

v1.5.2 → v2.0.02024-03-23

PHP version history (2 changes)v1.0.0PHP >=7.0.0

v2.0.0PHP >=7.4.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/07d18d882c8b4aaf3466432f64018214f2771eda333202175431ee7233795376?d=identicon)[thekid](/maintainers/thekid)

---

Top Contributors

[![thekid](https://avatars.githubusercontent.com/u/696742?v=4)](https://github.com/thekid "thekid (243 commits)")

---

Tags

annotationsassertionsphp7php8testcasetestingunittestxp-frameworkmodulexp

### Embed Badge

![Health badge](/badges/xp-framework-test/health.svg)

```
[![Health](https://phpackages.com/badges/xp-framework-test/health.svg)](https://phpackages.com/packages/xp-framework-test)
```

###  Alternatives

[xp-framework/compiler

XP Compiler

2026.0k9](/packages/xp-framework-compiler)[docler-labs/codeception-slim-module

Codeception Module for Slim framework.

13178.0k1](/packages/docler-labs-codeception-slim-module)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)