README

Test kernel orchestration for the Meritum ecosystem — boots and tears down the app kernels under test, applies service overrides and mocks before boot, and manages the test-support dependencies (e.g. a database connection for model factories) needed alongside them.

Requirements

• PHP 8.4+
• georgeff/kernel ^1.10
• mockery/mockery ^1.6

Installation

composer require meritum/testing

Usage

Managing kernels

TestingKernel is a plain Georgeff\Kernel\Kernel that takes custody of one or more already-built, unbooted app kernels via manages(). Booting the testing kernel boots itself first, then boots every managed kernel:

use Georgeff\Kernel\Environment;
use Meritum\Testing\TestingKernel;

$kernel = new TestingKernel(Environment::Testing);

$kernel->manages($httpKernel, 'http');
$kernel->manages($cliKernel, 'cli');

$kernel->boot();

$httpKernel = $kernel->get('http');

manages() requires an id — there's no optional/anonymous form — so a managed kernel can always be looked up later by the same string, regardless of how many kernels are involved. Convention is to key it by the kernel's own contract (e.g. an interface FQCN) rather than an arbitrary label, so anything built on top of meritum/testing has a stable name to resolve against. Both manages() and boot() throw a Georgeff\Kernel\KernelException if the testing kernel has already booted.

Overriding services

instance() and factory() stage a replacement for a service id, applied to every managed kernel when the testing kernel boots:

$queue = new MemoryQueue();

$kernel->instance(QueueInterface::class, $queue);

instance() takes an already-built object — the closure it registers always returns that exact instance, so identity is guaranteed regardless of container caching, which matters for anything a test wants to assert against later (e.g. messages published to $queue). factory() takes a callable instead, for cases that don't need a captured reference back:

$kernel->factory(ClockInterface::class, fn() => new FrozenClock('2026-01-01'));

Both throw if the testing kernel is already booted.

By default an override applies to every managed kernel. Pass one or more managed-kernel ids to scope it to just those:

$kernel->instance(QueueInterface::class, $queue, 'http');

Targeting an id that isn't actually managed throws a KernelException as soon as boot() runs, before any managed kernel starts booting.

Mocking

mock() builds a Mockery mock, registers it as an instance override, and returns it so expectations can be set before boot:

$repository = $kernel->mock(RepositoryInterface::class);
$repository->shouldReceive('find')->once()->andReturn($model);

$kernel->boot();

The class to mock defaults to the id itself, so mock(RepositoryInterface::class) is equivalent to mock(RepositoryInterface::class, RepositoryInterface::class). shutdown() calls Mockery::close() automatically, verifying expectations without needing the MockeryPHPUnitIntegration trait on your own test case.

Environment variables

setEnv() stages a variable to be applied via putenv() when the testing kernel boots:

$kernel->setEnv('DB_DATABASE', 'file::memory:?cache=shared');

shutdown() restores whatever the variable was set to beforehand, or unsets it entirely if it didn't exist before — so environment changes never leak into the next test.

Shutdown

shutdown() shuts down every managed kernel, then itself, then closes Mockery and forces gc_collect_cycles():

$kernel->shutdown();

It's a no-op if the testing kernel was never booted, so it's always safe to call unconditionally in a test's teardown.

The base test case

Meritum\Testing\TestCase extends PHPUnit\Framework\TestCase and constructs a fresh TestingKernel in setUp(), available as $this->kernel. It does not call boot() automatically — that stays an explicit call, so a test can register manages()/instance()/mock() right up until it's actually ready, including inline in a test method body:

use Meritum\Testing\TestCase;

final class ExampleTest extends TestCase
{
    protected function modules(): array
    {
        return [new DatabaseModule()];
    }

    protected function environment(): array
    {
        return ['DB_DATABASE' => 'file::memory:?cache=shared'];
    }

    public function test_something(): void
    {
        $this->kernel->manages($httpKernel, 'http');
        $this->kernel->mock(QueueInterface::class);

        $this->kernel->boot();

        // ...
    }
}

Override modules()/environment() to configure the testing kernel's own dependencies (not the managed app kernels' — those are built and configured independently, then handed to manages()). tearDown() calls $this->kernel->shutdown() automatically. onTeardown(callable $callback) is a shortcut for $this->kernel->onShutdown($callback).