Download the PHP package ralder/phpunit-query-scaling without Composer

ralder/phpunit-query-scaling

Controlled multi-scale query-count assertions for Laravel tests (PHPUnit and Pest).

Instead of asserting "this scenario runs at most N queries" — a number nobody can defend six months later — this package measures your scenario at several dataset scales inside real database transactions and asserts a contract on how the query count changes:

• assertQueriesScaleConstantly(...) — the scenario issues the same number of queries whether the dataset holds 2 or 10 entities (eager loading done right), or
• assertQueryScaling(..., expectation: QueryGrowth::atMostSlope(1, 0)) — the count may grow, but no faster than one query per added item on every measured segment.

When a contract is violated, every SQL fingerprint that grew across the scales is reported, so the N+1 query (or worse) is found without digging through logs.

Installation

Requirements: PHP 8.3+, Laravel 12/13, PHPUnit 12/13 or Pest 4/5 (the CI matrix verifies Laravel ^12/^13 × PHP 8.3–8.5, plus a separate PHPUnit 13 / Pest 5 job — support claims reflect the verified CI matrix, including minimum dependency versions).

Usage

PHPUnit

Pest

The trait works with any Laravel-aware test case: Orchestra Testbench and Illuminate\Foundation\Testing\TestCase alike.

What happens when it detects growth

A failing assertion throws PHPUnit's ExpectationFailedException with a deterministic, CI-friendly report:

The trend line is a purely diagnostic least-squares fit over the measured checkpoints. No package can (and this one does not) prove an asymptotic complexity class from measurements: the assertion verifies the contract at the measured scale factors only.

Expectations

• QueryGrowth::constant(0) is not QueryGrowth::atMostSlope(0): the constant contract tolerates no upward segment at all, while atMostSlope(0) tolerates decreases.
• Tolerance is a deliberate safety valve (cache state, statistics-dependent plans), documented in summary() and reported in failures.

API reference

assertQueryScaling() receives its tolerance through the expectation factory, for example QueryGrowth::constant(tolerance: 1) or QueryGrowth::atMostSlope(maxSlope: 1, tolerance: 1). Prefer named arguments when calling either assertion so optional parameters remain unambiguous.

Invalid scale lists (unsorted, duplicates, fewer than two factors, non-positive factors) are rejected with InvalidArgumentException before any database work happens.

How isolation works

For every scale factor the package:

1. records the current transaction depth of each measured connection,
2. begins one nested transaction (savepoint) inside it,
3. runs populate($scale), optional warmup($scale) (unmeasured), then measures run(),
4. restores the transaction depth — usually by rolling back — even if your callbacks throw.

If your run() callback committed or rolled back transactions outside its own scope (or issued implicit-commit DDL on MySQL), the restore step throws IsolationViolationException, explaining the observed depth and connection. The package fails loudly instead of pretending the environment is clean.

A callback that commits the isolation transaction and then opens a new one — ending at exactly the measured depth — is caught the same way: the package watches the connection's transaction lifecycle events and reports the breach instead of silently rolling back the replacement transaction. Watching those events requires an event dispatcher on the connection (the normal Laravel setup); without one, restore() falls back to transaction-depth checks, which cannot see a balanced commit-and-re-open.

Isolation is limited to the database connection. Redis, the filesystem, queues, HTTP calls are not isolated — keep your run() callback idempotent with respect to them. This limitation is contractual; it will not change silently with new isolation strategies.

populate() and warmup() run in the same isolation scope; they receive the scale factor and must be pure functions of it (only populate the requested amount, no external side effects).

SQLite note: in-memory test databases are perfectly fine. Real FOREIGN keys and savepoints work with the transaction driver.

Multi-connection measurement

Query fingerprints

A fingerprint is {connection, normalized SQL} where normalization is conservative: trim + whitespace collapse. Two statements count as the same fingerprint iff they are identical on the same connection. Parameter values never change the fingerprint.

Opt-in normalizeLiterals: true additionally folds string and numeric literals into ?. It is a heuristic (useful when Eloquent is bypassed and raw SQL interpolates values) and is off by default; report the SQL you actually saw before enabling it.

Custom isolation

Provide your own Ralder\QueryScaling\Core\IsolationStrategy implementation (e.g. schema dumps or read-only connections) and pass it as the isolation: argument. Throw Ralder\QueryScaling\Core\IsolationViolationException when your strategy detects a callback broke its invariants — the framework will surface it instead of the measurement result.

What this package is not

• Not a count budget or threshold tool — it measures growth across scale factors.
• Not an asymptotic complexity detector — measured points support empirical contracts, not O() proofs.
• Not a replacement for query logging during debugging; use DB::listen()/Telescope for that.
• Not a machine-readable report format (yet): failures are rendered as deterministic, aligned text on the PHPUnit exception message. There is no JSON/structured payload in 0.1.0 — parse the text, or open an issue if you need a structured report for CI tooling.

Compatibility

The supported combinations are the ones exercised by the repository's CI workflow:

Warmup

Pass warmup: fn (int $scale) => ... when a route, container, metadata cache, or other read-only application state should be initialized before measurement. Warmup runs once per scale after populate, with the collector disabled, and its queries are not counted. It runs inside the same isolation scope and must not mutate the dataset; use populate for all scale-dependent data setup.

Troubleshooting

• IsolationViolationException: the callback committed or rolled back beyond its scope, left the physical transaction unavailable, or ran implicit-commit DDL such as MySQL CREATE TABLE/ALTER TABLE. Keep transaction ownership inside the assertion scope and move schema changes to setup/migrations.
• Overlapping measurement LogicException: a scaling assertion was started from inside another measured callback. Move the nested assertion outside the callback.
• Misapplied-trait RuntimeException: use QueryScalingAssertions on a booted Laravel-aware PHPUnit/Pest test case (Orchestra Testbench or Foundation TestCase).
• Cannot resolve the default database connection: pass connections: 'connection-name' or connections: ['primary', 'tenant'] explicitly, and ensure the Laravel database config has a non-empty database.default value.

Development

CI runs Laravel ^12/^13 × PHP 8.3/8.4/8.5 (including prefer-lowest) and a separate PHPUnit 13 / Pest 5 job on PHP 8.5.

License

MIT. See LICENSE.md.