Testing

Overview

Tempest uses PHPUnit for testing and provides an integration through the Tempest\Framework\Testing\IntegrationTest test case. This class boots the framework with configuration suitable for testing, and provides access to multiple utilities.

Testing utilities specific to components are documented in their respective chapters. For instance, testing the router is described in the routing documentation.

Running tests

Any test class that wants to interact with Tempest should extend from IntegrationTest. Next, any test class should end with the suffix Test.

Running the test suite is done by running composer phpunit.

composer phpunit

Test-specific discovery locations

Tempest will only discover non-dev namespaces defined in composer.json automatically. That means that require-dev namespaces aren't discovered automatically. Whenever you need Tempest to discover test-specific locations, you may specify them within the discoverTestLocations() method of the provided IntegrationTest class.

On top of that, Tempest will look for files in the tests/Fixtures directory and discover them by default. You can override this behavior by providing your own implementation of discoverTestLocations(), where you can return an array of DiscoveryLocation objects (or nothing).

use Tempest\Core\DiscoveryLocation;
use Tempest\Framework\Testing\IntegrationTest;

final class HomeControllerTest extends IntegrationTest
{
    protected function discoverTestLocations(): array
    {
        return [
            new DiscoveryLocation('Tests\\OtherFixtures', __DIR__ . '/OtherFixtures'),
        ];
    }
}

Using the database

If you want to test code that interacts with the database, your test class can call the setupDatabase() method. This method will create and migrate a clean database for you on the fly.

final class TodoControllerTest extends IntegrationTest
{
    protected function setUp(): void
    {
        parent::setUp();

        $this->setupDatabase();
    }
}

Most likely, you'll want to use a test-specific database connection. You can create a database.config.php file anywhere within test-specific discovery locations, and Tempest will use that connection instead of the project's default. For example, you can create a file tests/Fixtures/database.config.php like so:

use Tempest\Database\Config\SQLiteConfig;

return new SQLiteConfig(
    path: __DIR__ . '/database-testing.sqlite'
);

By default, no tables will be migrated. You can choose to provide a list of migrations that will be run for every test that calls setupDatabase(), or you can run specific migrations on a per-test basis.

final class TodoControllerTest extends IntegrationTest
{
    protected function migrateDatabase(): void
    {
        $this->migrate(
            CreateMigrationsTable::class,
            CreateTodosTable::class,
        );
    }
}

final class TodoControllerTest extends IntegrationTest
{
    public function test_create_todo(): void
    {
        $this->migrate(
            CreateMigrationsTable::class,
            CreateTodosTable::class,
        );
        
        // …
    }
}

Tester utilities

The IntegrationTest provides several utilities to make testing easier. You can read the details about each tester utility on the documentation page of its respective component. For example, there's the http tester that helps you test HTTP requests:

$this->http
    ->get('/account/profile')
    ->assertOk()
    ->assertSee('My Profile');

There's the console tester:

$this->console
    ->call(ExportUsersCommand::class)
    ->assertSuccess()
    ->assertSee('12 users exported');

$this->console
    ->call(WipeDatabaseCommand::class)
    ->assertSee('caution')
    ->submit()
    ->assertSuccess();

And many, many more.

Changing the location of tests

The phpunit.xml file contains a <testsuite> element that configures the directory in which PHPUnit looks for test files. This may be changed to follow any rule of your convenience.

For instance, you may colocate test files and their corresponding class by changing the suffix attribute in phpunit.xml to the following:

<testsuites>
	<testsuite name="Tests">
- 		<directory suffix="Test.php">./tests</directory>
+ 		<directory suffix="Test.php">./app</directory>
	</testsuite>
</testsuites>

Using Pest as a test runner

Pest is a test runner built on top of PHPUnit. It provides a functional way of writing tests similar to JavaScript testing frameworks like Vitest, and features an elegant console reporter.

Pest is framework-agnostic, so you may use it in place of PHPUnit if that is your preference. The installation process consists of removing the dependency on phpunit/phpunit in favor of pestphp/pest.

composer remove phpunit/phpunit
composer require pestphp/pest --dev --with-all-dependencies

The next step is to create a tests/Pest.php file, which will instruct Pest how to run tests. You may read more about this file in the dedicated documentation.

pest()
    ->extend(Tests\IntegrationTest::class)
    ->in(__DIR__);

You may now run ./vendor/bin/pest to run your test suite. You might also want to replace the phpunit script in composer.json by one that uses Pest.