Testing Laravel Package

Getting Started

Begin by installing the package via Composer: composer require --dev spiral/testing. Then create your first test by extending Spiral\Tests\FrameworkTestCase (or KernelTestCase depending on version), which automatically bootstraps the Spiral kernel and injects a ready-to-use container. Your first use case will likely be testing a service class: call $this->get(ContainerInterface::class)->get(MyService::class) and assert behavior—no manual app bootstrap needed.

Implementation Patterns

• Service-level tests: Use self::bootKernel() to load the full container and resolve dependencies via $this->get(Service::class). Ideal for unit/integration hybrid tests where wiring matters.
• Controller/Route tests: Leverage $this->getRouteTester() (if available in version) or manually dispatch requests through the kernel with $this->kernel->handle($request), verifying responses and side effects.
• Database-aware tests: Enable test databases via config (e.g., spiral/database-test.php) and use self::withTransaction() to wrap test methods in a transaction that rolls back automatically.
• State isolation: Encapsulate test setup in setUp() and rely on tearDown()—the framework provides base implementations that clear caches, reset containers, and reset static state.
• Mocking dependencies: Use $this->mock(SomeInterface::class, $overrides) to safely override bindings in the container for test-specific behavior without affecting other tests.

Gotchas and Tips

• Persistent state leaks: Even with tearDown(), remember to clear global singletons (e.g., static caches in services like Config or Logger) manually if they’re not registered as Scopes::SINGLETON—check service definitions for SingletonInterface.
• Config overrides: Use self::overrideConfig() in tests to inject test-specific config (e.g., database.connection = 'test') without modifying real config files. Always scope overrides to the current test context.
• Kernel reuse: Avoid calling bootKernel() multiple times in one test method—bootstrap once in setUp() or via before() (pest) to prevent container conflicts.
• Mocking vs. binding: Prefer $this->bind(SomeInterface::class, $mock) over $this->mock() when you need to replace a non-singleton shared dependency across multiple instantiations.
• Performance tuning: For large test suites, run phpspiral test:clean (if CLI tool exists) to clear precompiled caches—this package caches bootsrap artifacts to speed up repeated test runs, but stale caches can cause subtle failures after refactors.