Psalm Tester Laravel Package

Product Decisions This Supports

• Psalm upgrade and plugin-bump decisions become measurable. With fixture-level assertions on inferred types (.phpt --EXPECT-- / --EXPECTF--), a Psalm or psalm-plugin-laravel upgrade produces an expected-vs-actual diff of type inference changes — missing issues, unexpected issues, and CheckType mismatches — before anything merges. That converts "should we take this upgrade?" from a vibe call into a reviewed diff.
• Build vs buy for static-analysis test harnesses. PsalmPhptTestCase supplies php-src-style .phpt discovery, --SKIPIF-- handling, one batched Psalm run per argument group, and PHPUnit --filter narrowing. In-house you would be writing a fixture parser, a batched process runner, issue diffing, and per-run cache isolation — real weeks of work with zero product differentiation. Adopt, don't build.
• A defensible quality gate for framework type glue. The reference workload (psalm-plugin-laravel's 758-fixture type suite, reported ~28.6s → ~10s wall time, ~4.6s filtered to one test) is the artifact to point at when someone asks "how do we know our Laravel type stubs are right?" The answer is a green fixture suite, not a code review opinion.
• CI reliability as a roadmap line, not an afterthought. withConcurrency(), withTimeout() (kills the Psalm process and its children; Windows: Psalm only), withWorkingDirectory(), withEnv(), and per-run cache directories make analysis bounded and deterministic. A hung worker errors the affected tests instead of stalling the pipeline — that is a pipeline-reliability decision with a cost attached.
• Known-bad expectations get an expiry signal. --XFAIL-- reports an expected failure as incomplete and, critically, as a failure once it passes. Teams can land fixtures for upstream Psalm bugs or pending refactors without creating a silently rotting skip.
• Safe parallel scale-out. --CONFLICTS-- (php-src semantics) isolates conflicting fixtures into their own Psalm run, prevents runs sharing a key from overlapping, and makes all run alone — the mechanism that lets you raise concurrency without flaky analysis.
• Reporting and dashboards are integration work, not parsing work. PsalmTester::create() + with*() methods and run()/runOne() return a Result with Outcome, formatted output, and structured Issues. Trend collection and gating hang off a typed API. Caveat: the old human-facing progress output is gone; the only console signal is one STDERR start line (psalm-tester: N phpt files (S skipped), G Psalm runs).
• Migration cost is a real line item. 0.4.0 is breaking: progress output removed, --EXPECT_EXTERNAL--/--EXPECTF_EXTERNAL-- rejected, --ARGS-- now appends to configured arguments instead of replacing them, withArguments() takes one argument per parameter (no shell), and repeated sections throw. Budget an upgrade pass against UPGRADING.md; do not treat it as a drop-in.

When to Consider This Package

Adopt if:

• You maintain a Psalm plugin, stub set, or type-heavy Laravel integration and need assertions on inferred types, not just "Psalm exited 0."
• You want type behavior enforced inside PHPUnit, so static-analysis regressions fail the same build, the same way, as unit regressions — including --filter to a single fixture for fast local iteration.
• You need bounded, deterministic CI: concurrency caps, timeouts with process-tree cleanup, isolated cache dirs, and explicit failure (not silent pass) when Psalm crashes, exits unexpectedly, prints a non-issue-list, or reports issues in other files.
• You have known-bad or pending expectations and want --XFAIL-- semantics that flip to failure when the underlying issue is fixed.
• You run stateful or conflicting fixtures that cannot share a Psalm process and want --CONFLICTS-- scheduling instead of hand-split test groups.
• You intend to automate on results (gating, trend lines, PR annotations) and want the structured Result/Outcome/Issue API rather than regexing console output.

Look elsewhere — or plan to fork — if:

• You are on PHPStan. This is Psalm-only; the fixture format and result plumbing do not transfer.
• You need vendor SLAs or a support contract. This is a single-maintainer, MIT, dev-only package with 1 star, 0 dependents, and no external adopters to learn from. Low blast radius (dev dependency, no production runtime), but you are an early adopter: expect to read the source, pin exact versions, and accept that a breaking 0.4.x→0.5.x may land on the maintainer's schedule, not yours.
• Your team won't own the fixtures. The harness is cheap; the .phpt corpus is the asset and the maintenance burden. Without a named owner, fixture drift becomes noise and the suite gets skipped.
• Your analysis needs are shallow. If Psalm at a fixed level in CI already catches what you care about, the added fixture layer is overhead.
• You need a stable API surface now. Pre-1.0 with a 0.3→0.4 breaking release and a rewritten public API means churn is the default assumption. Budget a fork-and-vendor contingency (MIT permits it) and pin composer.lock.

Adoption prerequisites to confirm before committing: maintenance health of the upstream repo (release cadence, issue responsiveness), that the released version actually matches the changelog you're reading (verify tag provenance — some metadata in this evaluation looks anomalous), and a spike that ports ~10 existing type expectations to .phpt to measure real authoring cost.

How to Pitch It (Stakeholders)

To executives (one paragraph): We maintain Laravel-specific type information that our static analysis depends on, and today we have no way to prove a Psalm or plugin upgrade didn't silently change what the analyzer infers. alies-dev/psalm-tester lets us assert inferred types as ordinary PHPUnit tests — so an upgrade that changes type inference fails the build with a precise expected-vs-actual diff instead of surfacing as confusing errors weeks later. It is a dev-only, MIT-licensed dependency with no production runtime footprint, so the downside is bounded to engineering time. The trade-off is maturity: it is a young, single-maintainer package with essentially no external adoption, so we should pin versions and treat the option to fork as part of the plan. Estimated cost is a short adoption spike plus an upgrade pass for the 0.4 breaking changes; the return is a repeatable, auditable quality gate on the type layer our tooling is built on.

To engineering (the ask):

• Spike: port ~10 representative type expectations to .phpt, wire PsalmPhptTestCase, measure authoring time and suite runtime.
• Success criteria: fixture suite runs in CI under a stated wall-time budget, honors --filter locally, fails loudly on Psalm crashes/timeouts, and one real Psalm upgrade is diagnosed from its diff.
• Non-goals: replacing PHPUnit coverage or Psalm's own CI level checks; this is a regression harness for inference behavior.
• Risks we accept: pre-1.0 API churn (mitigate by pinning + UPGRADING.md review per bump), fixture maintenance ownership (name an owner), and single-maintainer bus factor (mitigate with MIT fork contingency).
• Decision requested: approve the spike and, contingent on the runtime numbers, adopt as a dev dependency behind an exact version pin.