Phpunit Extensions Laravel Package

Product Decisions This Supports

• Accelerate Test-Driven Development (TDD) for Symfony/Laravel: Adopting this package enables rapid development of Symfony-based (or Laravel-compatible) applications by reducing boilerplate in unit/integration tests. The AbstractControllerTestCase and AbstractConstraintValidatorTestCase abstract away repetitive mocking of Symfony services (e.g., Security, Form, Validator), cutting test setup time by 30–50% for teams heavily using Symfony components.

• Future-Proof Migration Paths: The withConsecutive compatibility layer ensures zero-breaking changes when upgrading PHPUnit (e.g., from v9 to v10+), aligning with Laravel’s long-term support (LTS) roadmap. This avoids costly refactoring during major PHPUnit/Symfony version bumps.

• Build vs. Buy for Test Utilities: Buy: This package is a low-risk, high-reward alternative to building custom test utilities. It’s battle-tested by 50+ developers at 123inkt (a Digital Revolution company) and covers niche but critical use cases (e.g., PDF/image diffing, time manipulation, PDF-library abstraction). Build: Only consider custom solutions if your stack requires domain-specific assertions (e.g., proprietary validation rules) not covered here.

• Reduced Vendor Lock-In at the Test Layer (new in v1.14.0): PdfTestTrait now supports TcLibPdf alongside the previously supported PDF engine(s). This matters as a product decision, not just a testing convenience: PDF generation libraries are a common swap-out point (licensing costs, rendering fidelity, HTML-to-PDF vendor changes, PHP version support). Because visual regression coverage no longer forces a specific PDF engine, a future "replace our PDF library" initiative can be evaluated on cost/output quality rather than blocked by "we'd lose our regression tests." It also de-risks incremental engine migrations, since old and new output can be diffed under the same trait.

• Key Use Cases:

  • Symfony Controllers: Mock Security, Form, and Router interactions without manual stubbing.
  • Validation Logic: Test ConstraintValidators with fluent assertion chaining (e.g., expectBuildViolation()->expectAtPath()).
  • Time-Sensitive Tests: Freeze time globally with ClockTestTrait (useful for scheduled jobs or time-based logic).
  • Visual Regression: Compare PDFs/images (e.g., generated invoices/reports) with ImageTestTrait/PdfTestTrait; PDF rendering is supported across multiple engines, now including TcLibPdf (v1.14.0).
  • API/Response Testing: Assert JSON/XML responses with ResponseAssertions (e.g., assertJsonResponse(200, ['key' => 'value'])).

When to Consider This Package

Adopt if:

• Your stack is Symfony 6/7/8 or Laravel with Symfony components (e.g., validation, security, forms).
• You write >50 unit tests/month and spend >20% of test time on mocking Symfony services.
• You need visual regression testing for PDFs/images (e.g., marketing assets, dynamic reports).
• You generate PDFs with TcLibPdf — as of v1.14.0 this is a first-class, supported engine in PdfTestTrait, so TcLibPdf-based document pipelines can adopt without upstream work or a custom trait.
• You are planning a PDF engine migration and want regression coverage that survives the switch (engine-agnostic trait surface lowers switching cost).
• Your team uses PHPUnit 10+ and wants backward compatibility for withConsecutive.
• You prioritize developer velocity over minimal dependencies (MIT license, ~10KB footprint).

Look elsewhere if:

• You’re not using Symfony/Laravel: This package is Symfony-centric; alternatives like phpunit/phpunit or mockery/mockery may suffice.
• Your tests are stateless (e.g., pure PHP logic): No need for Symfony-specific helpers.
• You require custom assertion logic not covered (e.g., GraphQL, custom validation rules).
• Your PDF engine isn’t supported: TcLibPdf is now covered, but if you render through a different or in-house engine, confirm coverage before committing — a new engine adapter is a small upstream contribution, not a config flag.
• Your team prefers zero dependencies: This package adds ~10 dependencies (though most are dev-only).
• You’re on PHP <8.1 or PHPUnit <10: Compatibility is limited to modern stacks.

How to Pitch It (Stakeholders)

For Executives: "This package cuts test development time by 30–50% for Symfony/Laravel teams by eliminating repetitive mocking of core services like Security, Forms, and Validators. For example, testing a controller’s access control now requires one line ($this->expectDenyAccessUnlessGranted()) instead of manually stubbing the Security component. It also enables visual regression testing for PDFs/images (critical for compliance reports or marketing assets) without reinventing the wheel — and the latest release (v1.14.0) adds TcLibPdf support, so our PDF-vendor choice is no longer dictated by what our test tooling can verify. That keeps the door open on a future PDF engine switch if licensing or output quality changes. The MIT license and active maintenance (latest release: v1.14.0, additive and non-breaking) make it a low-risk, high-ROI choice to accelerate QA and reduce technical debt."

For Engineering: *"This gives us Symfony-specific superpowers in PHPUnit:

• Controller Tests: Mock Security, Form, and Router interactions with fluent assertions (e.g., expectCreateForm()->expectSubmit()).
• Validator Tests: Chain expectations like expectBuildViolation()->expectAtPath() for complex constraints.
• Time Control: Freeze time globally with ClockTestTrait (no more DateTime::createFromFormat hacks).
• Visual Testing: Compare PDFs/images with ImageTestTrait/PdfTestTrait (generates diffs for CI debugging). v1.14.0 adds TcLibPdf to PdfTestTrait, so TcLibPdf-rendered documents are now covered — no private fork or bespoke trait needed.
• PHPUnit 10+ Compatibility: The withConsecutive polyfill lets us upgrade without rewriting tests.

Release status (v1.14.0): Purely additive single-PR change (PdfTestTrait + TcLibPdf). No breaking changes, no deprecations, no migration steps — a safe patch-level bump. If we're already on PdfTestTrait, upgrading is a no-op unless we adopt TcLibPdf.

Trade-offs:

• Adds ~10 dev dependencies (mostly Symfony tools).
• Symfony/Laravel-only (not a general PHPUnit utility).
• Requires PHP 8.1+.
• PDF engine coverage is a closed list — TcLibPdf is in, others require an upstream PR.

Next Steps:

1. Upgrade: Bump to v1.14.0 (non-breaking) and confirm CI is green.
2. Spike: Add to a single test suite (e.g., AbstractControllerTestCase) and measure setup time savings.
3. Adopt: Roll out to Symfony-heavy modules first (e.g., validation, security, PDF generation).
4. Extend: Contribute custom traits/engine adapters if we hit gaps (e.g., additional PDF libraries, Laravel-specific helpers).

Cost: Zero (MIT license). Risk: Low (used by 50+ devs at 123inkt; v1.14.0 is additive only)."*