Backend Testing

This guide covers running backend test suites in PhpStorm and on the command line.

Prerequisites

• Complete backend environment setup: docs/backend/setup.md
• Ensure Docker services are running.
• Ensure VPN access is active.

Before running backend tests, seed the testing database:

echo 'y' | AWS_PROFILE=internal-services docker-compose exec -T core.web ./seed-testing-local.sh

For an interactive local run, use:

just seed-testing-local

Procedure

1. Add the migration name (without .php) to the INSERT INTO \migrations` VALUES ...block indatabase/schema/core-test-schema.sql`.
2. Use batch number last batch + 1 (insert above the add_your_migration_above_this_line placeholder).
3. If the migration creates tables, add the matching CREATE TABLE DDL to the dump. If it alters or drops tables/columns, amend or remove the existing DDL in the dump so it matches the new structure.

Authoring PHPUnit tests

Prefer PHPUnit 10+ PHP attributes over legacy docblock annotations or relying only on the test* method prefix:

• Mark test methods with #[Test] from PHPUnit\Framework\Attributes\Test.
• Use attribute-based #[DataProvider], #[TestWith], #[CoversClass], etc. where applicable, matching existing tests under tests/Unit/.

Test structure (Arrange–Act–Assert or Given–When–Then)

Every new test method must label its phases with // comments.

Default: Arrange / Act / Assert (// Arrange, // Act, // Assert).

Given / When / Then only when:

• explicitly requested (e.g. acceptance-style scenarios), or
• updating a file that already uses Given/When/Then — stay consistent within that file.

Do not leave multi-step tests unlabelled.

Example (default style):

#[Test]
public function it_returns_forbidden_for_unauthorized_users(): void
{
    // Arrange
    $user = $this->vanillaLoginRoleUser(Role::PARTNER);

    // Act
    $response = $this->getAsHubUser($user, RouteAliases::SOME_ROUTE);

    // Assert
    $response->assertForbidden();
}

Testing in PhpStorm

The Unit, Feature, Integration, and Characterisation test suites should be present in your IDE automatically and kept up to date via git (see the .run folder).

To run a suite individually, select the suite and click the run button.

!WARNING Check your xdebug mode configuration in local/xdebug/xdebug.ini. If it is not off, test execution will be slower.

Executing tests with xdebug enabled

If you run tests with the debug button, -dxdebug.mode=debug is added to the interpreter and overrides the value set in local/xdebug/xdebug.ini.

Command line testing

If you prefer to run tests from the command line, use the commands below.

Characterisation

just test-characterisation

Feature

just test-feature

Integration

just test-integration

Unit

just test-unit