Codeception Psalm Module Laravel Package

Getting Started

1. Install the module via Composer: composer require --dev weirdan/codeception-pselm-module.
2. Enable it in your Codeception suite config (suite.yml):

   modules:
       enabled:
           - Psalm
   

3. Ensure Psalm is available: Either install vimeo/psalm globally/locally, or rely on the module’s auto-bootstrapping if Psalm is in require-dev.
4. First use case: Add Psalm reporting to your existing Acceptance or Unit suite to catch type-related bugs during test runs—no extra CLI commands needed.

Start by checking the tests/ directory for Psalm output—failures will appear inline in Codeception’s test output.

Implementation Patterns

• Run alongside tests: Use the module in Unit suites to validate types used in application code as tested. For example, run Psalm when testing domain logic to catch mismatches between expected types and runtime assumptions.
• CI gatekeeping: Configure the module to fail the build on any Psalm error (errorLevel: 1 or stricter in psalm.xml), enforcing quality in CI without manual intervention.
• Shared config: Leverage your existing psalm.xml—the module reads from it by default (place it in project root). Use <projectFiles> to scope analysis to relevant namespaces (e.g., src/).
• Selective runs: Combine with skip: or groups in Codeception to only run Psalm on critical suites (e.g., api but not step Definitions suite).
• Local dev feedback: Run ./vendor/bin/codecept run Unit locally to get static analysis + test results in one flow—ideal for pre-commit checks.

Gotchas and Tips

• Outdated: Last release was Dec 2022—verify compatibility with newer Codeception (v5+) and Psalm (v5+) versions; check for forks or community forks if active maintenance matters.
• Output noise: By default, Psalm reports all findings; use --no-progress or suppress non-critical issues via psalm.xml to avoid overwhelming logs.
• Performance: Psalm can slow suite runs significantly—run it only in CI or in targeted local suites (e.g., not on every Unit run). Use processUncoveredFilesOnly: false in psalm.xml to speed up.
• Debugging: Enable verbose: true in the Psalm module config to see exact Psalm CLI invocation—useful for reproducing locally.
• Extension points: Override Psalm config per suite by specifying config_file: path/to/psalm.local.xml in module options.
• PHP version mismatch: Ensure Psalm’s PHP version (e.g., via phpVersion in psalm.xml) matches your CI/PHP runtime to avoid false positives.