xp-framework / unittest
Unittests for the XP Framework
Installs: 125 800
Dependents: 27
Suggesters: 1
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: >=7.0.0
- xp-framework/core: ^11.0 | ^10.0 | ^9.0 | ^8.0 | ^7.0
- dev-master
- v11.4.1
- v11.4.0
- v11.3.2
- v11.3.1
- v11.3.0
- v11.2.0
- v11.1.0
- v11.0.1
- v11.0.0
- v10.1.1
- v10.1.0
- v10.0.0
- v9.7.1
- v9.7.0
- v9.6.1
- v9.6.0
- v9.5.1
- v9.5.0
- v9.4.2
- v9.4.1
- v9.4.0
- v9.3.0
- v9.2.0
- v9.1.1
- v9.1.0
- v9.0.1
- v9.0.0
- v8.0.0
- v7.2.0
- v7.1.1
- v7.1.0
- v7.0.2
- v7.0.1
- v7.0.0
- v6.10.1
- v6.10.0
- v6.9.0
- v6.8.3
- v6.8.2
- v6.8.1
- v6.8.0
- v6.7.2
- v6.7.1
- v6.7.0
- v6.6.2
- v6.6.1
- v6.6.0
- v6.5.0
- v6.4.2
- dev-refactor/listeners
- dev-refactor/test-running
This package is auto-updated.
Last update: 2023-11-19 10:30:40 UTC
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 onPHP_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