Phpunit Symfony Kernel Test Laravel Package

Getting Started

This package is a PHPUnit helper for booting a Symfony Kernel inside your test suite. It is aimed at projects (or packages) that need a real container + kernel rather than a plain unit test — typically bundle/extension code, compiler passes, or service-wiring integration tests. For a Laravel developer it is most useful when you maintain a package that touches Symfony components (or a bundle you also ship), or when you are porting/cross-testing Symfony-based code alongside a Laravel app.

Minimal steps:

1. composer require --dev tourze/phpunit-symfony-kernel-test:^2.0
2. Confirm the PHP and phpunit/phpunit constraints the new 2.0 tag requires — a major bump here almost always means the supported PHPUnit major changed. Check composer.json in the tag before upgrading.
3. Read src/ first, not just the README. The public surface is usually a single abstract test case plus a createKernel()/bootKernel() contract; the exact class name and namespace is the thing you need to pin down before writing any test.
4. First use case: create a tests/Kernel/ContainerSmokeTest.php that extends the package's base test case, boots the kernel, and asserts a known service resolves from the container. This proves the kernel/config wiring works before you invest in real assertions.

If you only need Laravel's Illuminate\Foundation\Testing\TestCase, you do not need this package — Laravel already boots an application kernel. Reach for this only when the code under test genuinely targets Symfony\Component\HttpKernel\KernelInterface.

Implementation Patterns

Extend the provided base case. The idiomatic usage is inheritance: your test class extends the package's abstract test case and implements/overrides the kernel factory. Keep a single project-level KernelTestCase base in your own test namespace that extends the package class, so a future major bump only touches one file.

Boot once per class, reset per test. Kernel boot is expensive. Cache the booted kernel statically at the class level (or in setUpBeforeClass) and only reset the container between tests when a test mutates services. Tests that assert on container state should call the shutdown/reboot hook in tearDown to avoid order-dependent failures.

Use it as a service-wiring assertion layer. The highest-value pattern day-to-day is: boot kernel → pull a service from the container → assert its collaborator graph. This catches missing service definitions, wrong tags, and broken autowiring that a pure unit test with mocks will happily hide.

Compose with your normal assertions. The package only handles the kernel lifecycle; keep your domain assertions in ordinary PHPUnit tests or in Laravel's TestCase for the app-side code. Don't try to run Laravel's HTTP test helpers through this kernel — they expect Laravel's application contract, not a raw Symfony kernel.

In CI, pair it with a real config environment. Point the kernel at a dedicated test environment with its own cache/log dirs. This is the pattern that keeps the helper stable; a kernel booting dev config will leak cache between runs and cause flaky results.

Migration path from 1.x. Treat 2.0 as a re-baseline: create the new base class, migrate one test, run it, then move the rest. Don't bulk-rewrite — the breaking surface is usually the abstract method signature, and letting the compiler point at each subclass is faster than guessing.

Gotchas and Tips

• The 2.0.0 notes are only a compare link. The changelog body is just compare/1.0.8...2.0.0, so there is no curated breaking-change list. Review the actual diff (or at minimum composer.json + src/) before upgrading; assume semver-major means a changed abstract method signature, a changed namespace/class name, or a dropped PHPUnit major.
• PHPUnit major alignment is the usual 2.0 breaker. If your suite is on PHPUnit 9 and the tag requires 10/11 (or vice versa), the failure shows up as an unrelated fatal in your base test class. Check the constraint first, not last.
• Kernel caching bites in long suites. A statically cached kernel keeps the container's compiled state; a service mutated in one test is visible in the next. Reboot on tearDown when in doubt — correctness over the few hundred milliseconds.
• Bootstrap failures are opaque. When the kernel won't boot, the useful error is usually buried under a RuntimeException from the cache dir. Delete the test cache dir and re-run before debugging anything else; stale compiled containers are the most common cause.
• Cache/log directories must be writable and per-environment. Point them somewhere under var/cache/test, and make sure CI has them writable — a read-only build checkout will fail at kernel boot, not at an obvious assertion.
• Extension point: the kernel factory is your seam. Anything environment-specific (extra bundles, container parameters) belongs in the createKernel()-style override in your project base class, not scattered across tests. That override is the only thing you should have to touch on the next major bump.
• Don't mix this with Laravel's RefreshDatabase. The database trait assumes Laravel's application container; using it in a Symfony-kernel test gives confusing connection/transaction behaviour. Keep the two test bases in separate directories with separate phpunit.xml testsuites if you need both.