/functional-tests

name: functional-tests
description: Write functional tests for Symfony controllers and HTTP endpoints using WebTestCase, getContainer, loginUser, and DAMA rollback
capabilities: [read, search, edit, shell]
tags: [testing]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash

Functional Tests (Symfony)

Use when

• A controller or HTTP endpoint must be checked through the kernel: status, redirect, rendered DOM, form errors, emails.
• A repository or service must be tested against the real database with `KernelTestCase`.
• An authenticated or role-restricted route needs coverage via `loginUser()`.
• Key URLs need cheap smoke tests.

Default workflow

1. Choose the base class: `WebTestCase` for HTTP, `KernelTestCase` for services, plain `TestCase` for pure logic. 2. Call `static::createClient()` directly (never `bootKernel()` first) and read private services with `static::getContainer()`. 3. Authenticate with `$client->loginUser($user)` instead of replaying the login form. 4. Assert the response and the DOM: `assertResponseIsSuccessful()`, `assertResponseRedirects()`, `assertSelectorTextContains()`, `assertEmailCount()`. 5. Isolate tests with the DAMADoctrineTestBundle `PHPUnitExtension`, plus Foundry reset for fixtures. 6. Add smoke tests with a data provider and hardcoded URLs.

Guardrails

• Use the real database and real repositories; do not mock the EntityManager or repositories in data-touching tests.
• Invalid form submissions assert 422 with `assertResponseIsUnprocessable()` (Symfony 8.0+ behavior).
• `.env.local` is not loaded in the test environment: use `.env.test` or `.env.test.local`.
• `assertSessionHasFlashMessage()` requires Symfony 8.1+.

Progressive disclosure

• Use this file for execution posture and risk controls.
• Open references when deep implementation details are needed.

Output contract

• Test classes with the base class chosen for each.
• The authentication and database isolation strategy.
• Status codes, DOM assertions and smoke URLs covered.

References

• `reference.md`