Pyrameter Laravel Package

Technical Evaluation

Architecture fit

Pyrameter is a dev-only PHPUnit extension, not a runtime Laravel package. It hooks PHPUnit's extension/event system, classifies each test (unit / integration / E2E), renders an ASCII shape, and can fail the run when the suite deviates from a configured target shape. For a typical Laravel codebase this is directly relevant: Laravel's opinionated tests/Unit, tests/Feature, tests/Browser split plus heavy use of RefreshDatabase routinely produces the "Integration Mountain" the tool calls out. There is no service provider, no config publish, no runtime coupling — the architecture fit is clean precisely because it stays inside the test harness.

Integration feasibility

Low effort: composer require --dev boundwize/pyrameter, register the extension in phpunit.xml under <extensions>, add a shape config, run the suite. Because it is a Composer dev dependency it never reaches production images if --no-dev is used. The main friction is that Laravel teams commonly invoke php artisan test, which shells out to PHPUnit — the extension's output will appear, but exit-code semantics and output interleaving need to be verified rather than assumed.

Technical risk

• Single-maintainer / single-vendor risk. 9 stars, 0 dependents, one release line. No ecosystem signal that this survives a PHPUnit major.
• PHPUnit API coupling. Extension APIs and event classes changed materially across PHPUnit 10/11/12. A PHPUnit upgrade can break bootstrap, which is worse than a failing assertion because it can abort the entire run.
• Classification accuracy. The usefulness of the whole tool rests on how tests are bucketed — namespace, directory, attribute, or heuristic. Misclassification produces a plausible-looking shape chart that drives bad decisions.
• Pest compatibility. Many Laravel teams use Pest. If classification depends on PHPUnit attributes or method-level metadata, Pest suites may be silently misshapen.
• Low blast radius, high visibility. Worst case is a red build from a policy tool, not a production incident. That asymmetry is what makes an evaluation cheap.

Key questions

1. What is the classification mechanism, and can it be overridden explicitly per test/directory?
2. Which PHPUnit versions and which Pest versions are supported, and is that tested in CI?
3. Does it support --testsuite filtering, ParaTest/sharding, and per-directory partial runs (i.e., is the shape computed on the run subset or the declared suite)?
4. Is "violated" a non-zero exit by default, and can it run report-only?
5. Who maintains it, and what is the stated policy for PHPUnit major upgrades?
6. Does it emit machine-readable output (JUnit/JSON) we could trend over time?

Integration Approach

Stack fit

Composer + PHPUnit is exactly our stack, so there is no new toolchain. The only decision point is the runner: PHPUnit directly, artisan test, or Pest. Pick one as the canonical CI entrypoint before adopting, because the extension's behaviour is defined relative to that invocation.

Migration path

Treat this as an observability change first and a policy change second. Adopt in report-only mode, capture the current shape as a baseline, then ratchet: fail only on regression (e.g., unit share drops below today's number) rather than on the idealized pyramid. A hard pyramid gate on day one will either be immediately disabled or force a large, low-value test-refactor backlog.

Compatibility

Pin to an exact version in composer.json rather than a caret range, and pin PHPUnit alongside it. Verify on the oldest and newest PHP versions in the CI matrix, plus Windows if any developer runs natively. If Pest is in use, run a spike on a Pest-only branch before committing — do not assume.

Sequencing

1. Spike: one service, one branch, report-only, confirm output and exit behaviour under artisan test.
2. Confirm classification correctness by spot-checking 20–30 tests across unit/feature/browser.
3. Add a non-blocking CI job that publishes the shape as an artifact/PR comment; run for two to four weeks.
4. Set a regression-only threshold per repository and make that job required.
5. Document the policy in CONTRIBUTING.md so new tests land in the right bucket by convention.
6. Revisit standardization across repos only after one repo has run clean for a quarter.

Operational Impact

Maintenance

Ongoing cost is a pinned dev dependency and a config file. The real maintenance load is the PHPUnit upgrade cycle: every PHPUnit major becomes a blocking question ("does Pyrameter support it yet?") on an otherwise routine upgrade. Budget for the possibility of vendoring a fork or dropping the tool at that point.

Support

There is no vendor. Support is the issue tracker of a low-traffic repository. Internal ownership must be assigned to the platform/QA engineer who owns test tooling; it should not be orphaned inside a feature team. Fallback if abandoned: remove the extension (trivial) and lose the shape report (acceptable).

Scaling

Per-run overhead is negligible — classification is O(number of tests). The scaling problem is organizational: N repos means N configs and N thresholds that drift unless centralized. If it proves useful, keep the config in a shared template rather than copying XML between services. Sharded/parallel CI needs validation, since shape computed per shard is meaningless while shape computed per full run is what you actually want to gate on.

Failure modes

• Bootstrap failure after a PHPUnit bump — whole suite aborts; mitigate by running it as a separate, non-release-blocking job.
• False violation from misclassified tests — erodes trust fast; mitigate with explicit per-directory overrides.
• Silent no-op — extension loads but classifies everything into one bucket; mitigate by asserting the report exists and contains a sane distribution.
• Threshold gaming — engineers move tests into tests/Unit with the same database dependencies to satisfy the shape. Guard with code review, not the tool.

Ramp-up

Under a day for one engineer to instrument and validate a single repo. Near-zero for the rest of the team, since the output is a chart in CI logs. The genuine cost is cultural: someone must own the "stop adding feature tests without unit coverage" conversation that the tool merely makes visible.

Recommendation

Worth a bounded spike (≤2 days) on one representative Laravel service, report-only. Do not standardize platform-wide on current signals — 9 stars and 0 dependents means we would be the de facto maintainer of our own dependency. Re-evaluate after the report-only period if the shape data surfaces a real, actionable test-portfolio problem.