README

Trainline is a tiny PHP testing framework.

Getting started

Trainline requires PHP ^8.1.

composer require --dev ilmiont/trainline

Create a trainline.json file in your working directory:

{
	"directory": "tests/",
	"namespace": "Tests"
}

You can now run vendor/bin/trainline to execute your tests!

You can override any configuration key using CLI arguments: vendor/bin/trainline --directory tests/. When overridden in this way, every given CLI argument must be given a value.

Writing tests

Test units must be classes implementing Trainline\Framework\UnitInterface. It's recommended your tests extend Trainline\Framework\Unit which implements Trainline\Framework\UnitInterface.

Units must be constructable without any arguments. They must also be PSR-4 autoloadable within the directory and namespace roots you define in your configuration. Trainline automatically loads the vendor/autoload.php file in your working directory.

When extending Unit, all public methods in your class which are not prefixed with __ will be executed as test cases. Test cases receive no arguments and are not expected to return a value. Test cases are executed sequentially.

A successful test case is any which executes without throwing up.

__init() and __after()

The __init() method of your unit will be called before every test case.

The __after() method of your unit will be called after every test case.

__init() and __after() receive no arguments and are not expected to return a value.

__tests()

You can define which of your unit's methods should be executed as test cases by implementing this method. It must return an array of method names to execute as test cases.

Assertions

A basic set of assertion functions is included in the Trainline\Assertions namespace:

• equiv(mixed $a, mixed $b) : bool - Checks $a == $b and throws a Trainline\Exceptions\AssertionException instance when this is not the case; the thrown exception when stringified contains pretty representations of the compared values.
• ident(mixed $a, mixed $b) : bool - Checks $a === $b and throws a Trainline\Exceptions\AssertionException instance when this is not the case; the thrown exception when stringified contains pretty representations of the compared values.
• throws(callable $callback, string $expect=null) - Invokes $callback and expects a Throwable to be thrown. Throws a Trainline\Exceptions\AssertionThrowsException when $callback executes without throwing. When $expect is given, the Throwable thrown by $callback must satisfy instanceof $expect; a Trainline\Exceptions\AssertionThrownException will be thrown when this is not the case, which emits pretty representations of the expected and received Throwable types when stringified. Returns the \Throwable thrown by $callback.

Reports

All output is currently emitted as formatted ANSI text to stdout.

ANSI compatibility is detected automatically. You can force ANSI output by setting the forceAnsi configuration key to true.

Test cases which encounter an error emit their name and the stringified representation of the Throwable which caused them to fail.

A summary containing test run statistics is emitted after all the test cases have been executed.

API

Trainline's internal API is not documented at this time.

You're welcome to examine the source to understand how extensions can be constructed.

©James Walker. Licensed under the MIT License.