ATC - APITestCase

A fluent, batteries-included testing layer for Symfony JSON APIs.

Fluent API testing for Symfony, with zero boilerplate. ATC is a batteries-included testing layer on top of WebTestCase: chained HTTP+JSON assertions, JSON Schema and JMESPath, container-aware mocking, profiler-backed N+1 detection, and ready-to-use in-memory swaps for Messenger, Mailer, Notifier, HTTP client, and Cache.

Contents

• Installation
• Quick start
• Issuing requests
• Asserting on responses
• JMESPath assertions
• JSON Schema validation
• Performance assertions
• Authentication
• Container mocking
• Database
• Messenger
• Mailer
• Notifier
• HTTP client
• Cache
• Profiler & N+1 detection
• Customization
• Compatibility
• Recommended companions

Installation

That is it. No bundle to register, no YAML to write. Extend Tyloo\Atc\ApiTestCase in any functional test and you have the full surface. Sensible defaults out of the box:

• tests/Schemas/ for JSON Schema files
• No default headers, no default mocks
• In-memory transports auto-discovered from your framework.messenger config
• HTTP client mock is strict (unmatched outbound requests fail the test)

Each default has a protected override hook on the test case (see Customization).

Quick start

A realistic scenario:

• Spin up an authenticated admin with Zenstruck Foundry
• Validate the response against a JSON Schema
• Assert the welcome email got queued
• Confirm the row landed in the database

One method, no setup boilerplate. The rest of this README walks through every feature in detail.

Issuing requests

All HTTP verbs are available on the test case via InteractsWithApi (auto-loaded in ApiTestCase):

Headers and query strings are first-class arguments:

Form payloads and file uploads:

When json: is provided it takes precedence; formData is ignored. Content-Type: application/json is set automatically.

Persist headers across multiple requests in the same test:

Asserting on responses

Every verb call returns an ApiResponse that you can chain assertions on:

Status

Headers

JSON body, exact match

Order and types must match. Use assertJsonContains when you only care about a subset.

JSON body, subset match

Recursive: nested arrays only need to contain the listed keys.

Raw access

When the assertion helpers aren't enough, grab the decoded body directly:

JMESPath assertions

ATC uses JMESPath for navigating JSON responses (powered by mtdowling/jmespath.php):

Pass a callable to assert with a predicate (truthy = pass):

Assert that a path does not resolve to a value, or count items at a path:

JSON Schema validation

Drop a JSON Schema file under tests/Schemas/ (configurable; see Customization) and validate the response shape against it:

Powered by justinrainbow/json-schema. Failures include the schema path and a human-readable list of validation errors.

Performance assertions

Wall-clock duration of each request is measured automatically:

Tip: use generous bounds in CI to avoid flakiness.

Authentication

ATC targets stateless / token-based APIs, so authentication is just "attach the right header to the next request".

Raw tokens

actingAs($user) — paired with Foundry

By default, actingAs($user) looks for a getApiToken(): string method on the user object and attaches the result as a Bearer token. Perfect when your User entity already exposes an API token.

The recommended pattern: build the user with Zenstruck Foundry, then pass it straight to actingAs():

Your User entity (or its Foundry factory) just needs a getApiToken(): string accessor. Foundry handles persistence, actingAs() handles the Bearer header, ATC handles the rest.

Custom auth strategy

Override authenticate() in your base test case to plug in any strategy (JWT, HMAC signature, opaque token, anything that maps user → request credentials):

actingAs($user) will then route through your override across every test that extends BaseApiTestCase. No registry, no $using: argument, no bundle config — one method, one strategy per test suite.

Container mocking

InteractsWithContainer lets you swap services for test doubles without touching services.yaml.

Full mock

Partial mock (real behavior on un-listed methods)

Partial mocks require a concrete class.

Inject any object as a service

Default mocks for the whole test suite

Centralize "always-mocked-in-tests" services in a base test case:

Database

Add the trait. ATC does not manage database lifecycle, so pair it with Zenstruck Foundry or DAMA/DoctrineTestBundle:

Messenger

InteractsWithMessenger discovers in-memory:// transports and lets you inspect dispatched messages. Handlers do not auto-execute, so you assert on the dispatch itself:

Other helpers:

Mailer

InteractsWithMailer swaps the real Mailer for an in-memory capture and exposes assertions on sent emails:

Notifier

InteractsWithNotifier captures Symfony Notifier sends:

HTTP client

InteractsWithHttpClient swaps the Symfony HTTP client for a MockHttpClient you control, and records every outbound request:

By default the mock is strict: an unmatched request fails the test. Override resolveHttpClientStrict() in your test case to return false if you'd rather let unmatched requests pass through.

Cache

InteractsWithCache swaps every cache pool for an ArrayAdapter:

Profiler & N+1 detection

InteractsWithProfiler enables Symfony's Profiler per-request and exposes the captured Profile. Useful for catching N+1 query regressions:

Requires framework.profiler enabled in the test kernel and doctrine/doctrine-bundle (for the db collector).

Customization

There is no bundle, no YAML config, no DI extension. Every default lives on a protected method that you override in a base test case. Define one base class for your project and inherit everywhere:

Cherry-pick the overrides you need. The defaults handle the common case.

Compatibility

CI runs the full matrix on each push.

Recommended companions

• Zenstruck Foundry: test data factories.
• DAMA/DoctrineTestBundle: transactional DB rollback per test.

Inspirations

ATC borrows ideas from:

• Laravel's testing helpers: fluent actingAs / assertOk style and the "what should the test actually look like" north star.
• api-platform/core's ApiTestCase: convention of subclassing WebTestCase with HTTP-centric helpers.
• zenstruck/browser: KernelBrowser-based fluent testing, profiler integration, and in-memory infrastructure capture patterns.

Contributing

See Code of Conduct.

Security

Report vulnerabilities via GitHub Security Advisories. See SECURITY.md.

License

MIT © Julien Bonvarlet