Weave Code
📐 PHPUnit extension that measures the shape of your test suite
Frequently asked questions about Pyrameter
- How do I install Pyrameter in a Laravel application?
- Install it as a Composer dev dependency with composer require --dev boundwize/pyrameter, then register the extension in your phpunit.xml under the extensions element. After that you add a target shape configuration and run your suite as usual, and Pyrameter prints the shape chart alongside normal PHPUnit output. Because it is a dev dependency it never ships to production images when you deploy with composer install --no-dev. There is no service provider to register and no config file to publish.
- How does Pyrameter decide whether a test is unit, functional, integration, or e2e?
- Pyrameter classifies executed tests based on the code they use, so the bucket depends on what a test actually touches rather than only on its directory or namespace. That is a meaningful distinction in Laravel projects, where tests/Feature can contain both fast mocked tests and full RefreshDatabase integration tests. Because a misclassification produces a plausible but misleading chart, spot-check 20 to 30 tests across your unit, feature, and browser suites after the first run and confirm the buckets match your expectations. Check the README for whether per-test or per-directory overrides exist in your version.
- Does Pyrameter work with Pest and php artisan test?
- Pyrameter is a PHPUnit extension, so it is defined relative to the PHPUnit invocation. php artisan test shells out to PHPUnit, so the extension output should appear, but verify exit-code semantics and output interleaving in your own project rather than assuming they behave identically to vendor/bin/phpunit. Pest builds on PHPUnit but its classification inputs may differ, and Pest support is not documented in the README excerpt, so run a spike on a Pest-only branch before adopting. Pick one canonical CI entrypoint and stick to it, since the extension's behaviour is relative to that runner.
- Can Pyrameter fail my CI build, or can it run in report-only mode?
- Pyrameter compares actual test distribution against your configured target and reports the suite as violated when it deviates, which can turn the run into a non-zero exit. Treat it as an observability change first: adopt it in report-only fashion, record your current shape as a baseline, then ratchet to fail only on regression rather than against an idealized pyramid. A hard pyramid gate on day one tends to either get disabled immediately or spawn a large, low-value test-refactoring backlog. Confirm the exact exit-code behaviour under your chosen runner before wiring it into a blocking job.
- Which PHPUnit and PHP versions does Pyrameter support?
- The README badges show an active CI build, PHPStan at max level, and support for Windows, macOS, and Linux, but a specific PHPUnit and PHP version matrix is not spelled out in the excerpt. PHPUnit extension APIs and event classes changed materially across PHPUnit 10, 11, and 12, so a PHPUnit upgrade can break the extension's bootstrap rather than failing an assertion. Pin Pyrameter to an exact version in composer.json, pin PHPUnit alongside it, and run your CI matrix against the oldest and newest PHP versions you support. Check the repository's CI workflow for the versions it actually tests.
- Does Pyrameter affect production performance or runtime behaviour?
- No. Pyrameter is a dev-only PHPUnit extension that lives entirely inside the test harness, with no service provider and no runtime coupling to your application. With composer install --no-dev it is simply absent from production images. The worst-case failure is a red build from a policy tool, not a production incident.
- Does Pyrameter account for --testsuite filtering, ParaTest, or sharded runs?
- Pyrameter reports on executed tests, so a partial run reflects the subset you actually executed rather than the declared full suite. That matters when you run per-directory test jobs, use --testsuite filters, or split work across ParaTest and sharded CI jobs, because each shard would see a different shape. Decide whether you want the shape gate on a single full-suite job rather than on every shard, and verify behaviour under ParaTest in a spike before gating on it.
- What are the alternatives to Pyrameter for measuring test pyramid shape?
- You can write a custom PHPUnit extension or event subscriber yourself and count tests by directory, namespace, or attribute, but you would also have to build the reporting and threshold logic. Static approaches such as grouping by tests/Unit versus tests/Feature directory are far cheaper but ignore what a test actually touches, which is precisely the gap Pyrameter targets. Code coverage reports and per-suite timings can hint at integration heaviness but do not produce a share-based pyramid. Pyrameter's value is the classification plus the ASCII chart and threshold table in one dev dependency.
- Is Pyrameter actively maintained and safe to depend on?
- It is a single-maintainer package with a small ecosystem footprint: roughly 9 stars, 0 dependents, and one release line, so treat maintenance as a real risk. The blast radius is low because it is a dev-only tool, so a stale version costs you a broken build rather than a broken application. Before adopting, check the repository for a stated policy on PHPUnit major upgrades and whether newer PHPUnit versions are covered in CI. Pinning an exact version and keeping PHPUnit pinned alongside it limits the surprise factor.
- What should I watch out for when upgrading PHPUnit with Pyrameter installed?
- PHPUnit's extension and event APIs changed significantly between major versions, so a PHPUnit bump can break Pyrameter's bootstrap and abort the entire test run rather than just failing one assertion. That is worse than a normal failing test because you lose all test signal in that job. Upgrade PHPUnit and Pyrameter together in a branch, confirm the extension still registers, and keep the PHPUnit constraint pinned so an unrelated composer update cannot shift it. Run the check on both the oldest and newest PHP versions in your CI matrix.
Weaver
How can I help you explore Laravel packages today?