Integration testing

Unit tests tell you your classes do what you think. Integration tests tell you they still do it once a real database, a real web server and a real file system get involved, which is usually where the interesting bugs live. MicroUnit treats this as a first-class job: named fixtures that set up and tear down resources, suite-wide setup for the expensive stuff, and a small toolkit (Database, HttpServer, Http, TemporaryDirectory) that covers the common cases without pulling in a single package. Services that aren’t available skip the test instead of turning the whole run red.

If you’re testing a Laravel, Symfony or CodeIgniter app, start with Laravel, Symfony and CodeIgniter. Everything on this page works there too.

Fixtures: resources with a name

A fixture is a named resource. Declare it once per suite with fixture(), and every test with a parameter of that name receives it:

use MicroUnit\Assertion\Assert;
use MicroUnit\Setup\TestSetup;
use MicroUnit\Toolkit\Database;

$tester = TestSetup::getTester('ProductRepository');

$tester->fixture('db', fn() => Database::sqlite(__DIR__ . '/schema.sql'));

$tester->define('stores_a_product', function (Database $db) {
    $repository = new ProductRepository($db->pdo);
    $repository->add('Hub', price: 25);

    Assert::exact(1, $db->count('products'));
});

The matching is by parameter name, not type. $db gets the db fixture. Parameters that don’t match a fixture are filled with the usual positional values, so fixtures mix freely with setUp() results and data sets.

Fixtures are lazy. One is created the first time a test (or setUp(), or another fixture) asks for it, and a test that doesn’t ask doesn’t pay for it.

Cleanup

Pass a cleanup callable and it runs after the test, whether the test passed or failed:

$tester->fixture(
    'db',
    fn() => Database::connect(getenv('DB_DSN'), 'app', 'secret')->beginTransaction(),
    cleanup: fn(Database $db) => $db->rollBack(),
);

Cleanups run in reverse creation order, so a fixture is torn down before the fixtures it was built from. Every cleanup runs even if one of them throws. If a cleanup fails, an otherwise passing test fails with Cleanup of fixture 'db' failed: ...; a test that already failed keeps its original failure as the reported cause.

Fixtures that use fixtures

A fixture factory can ask for other fixtures the same way a test does:

$tester->fixture('db', fn() => Database::sqlite(__DIR__ . '/schema.sql'));
$tester->fixture('repository', fn(Database $db) => new ProductRepository($db->pdo));

$tester->define('finds_products_by_name', function (ProductRepository $repository, Database $db) {
    $db->insert('products', ['name' => 'Hub', 'price' => 25]);

    Assert::notNull($repository->findByName('Hub'));
});

Within one test, both get the same Database instance. Fixtures that depend on each other in a circle are reported as such instead of recursing forever.

Shared fixtures for expensive resources

By default every test gets a fresh instance. That’s what you want for a database you mutate, and exactly what you don’t want for a web server that takes half a second to boot. shared: true creates the fixture once for the whole suite and cleans it up after the suite’s last test:

$tester->fixture('app', fn() => HttpServer::start('public/index.php'), shared: true);

Shared fixtures play well with parallel runs: MicroUnit distributes whole suites to workers, so a suite’s shared fixtures never get split across processes. A failing cleanup of a shared fixture is printed to stderr, since there’s no single test left to blame; tearDownOnce() still runs afterwards.

setUpOnce and tearDownOnce

For suite-wide setup that isn’t naturally “one named thing”, there’s setUpOnce(). It runs once before the suite’s first test, and tearDownOnce() runs once after the last one and receives the same value:

$tester->setUpOnce(fn() => Database::connect('mysql:host=127.0.0.1;dbname=shop_test', 'shop', 'secret'));
$tester->tearDownOnce(fn(Database $db) => $db->execute('DELETE FROM products'));

$tester->define('reads_products', function (Database $db) {
    Assert::notEmpty($db->select('SELECT * FROM products'));
});

The value goes to setUp() if the suite has one; otherwise each test receives it as its first argument. If setUpOnce() throws, every test of the suite fails with setUpOnce() of suite '...' failed: .... If it skips (see below), every test of the suite is skipped with that reason.

Need to share more than one thing? Return a ValueBundle: a small bag of named values with property access. Values set with readonly: true can’t be overwritten by accident.

use MicroUnit\Toolkit\ValueBundle;

$tester->setUpOnce(function (): ValueBundle {
    $shared = new ValueBundle();
    $shared->set('app', HttpServer::start('public/index.php'), readonly: true);
    $shared->set('db', Database::sqlite(__DIR__ . '/schema.sql'), readonly: true);

    return $shared;
});

$tester->tearDownOnce(fn(ValueBundle $shared) => $shared->app->stop());

My rule of thumb: reach for named fixtures first. They read better in the test signature, they’re lazy, and they clean up on their own. setUpOnce() is for the odd case where the setup is a procedure rather than a resource.

Database

MicroUnit\Toolkit\Database is a thin PDO wrapper for tests. The underlying PDO is public ($db->pdo) so you can pass it into the code you’re testing. Errors throw exceptions (PDO::ERRMODE_EXCEPTION).

Creating one

// SQLite in memory, initialised from a schema file
$db = Database::sqlite(__DIR__ . '/schema.sql');

// SQLite in a file
$db = Database::sqlite(__DIR__ . '/schema.sql', path: __DIR__ . '/test.sqlite');

// Any PDO database
$db = Database::connect('pgsql:host=127.0.0.1;dbname=shop_test', 'shop', 'secret');

sqlite() skips the test when the pdo_sqlite extension is missing. connect() skips the test when the connection fails, whether the server is down or the PDO driver isn’t installed, with the error in the reason:

[-] stores_orders skipped: Database not reachable (pgsql:host=127.0.0.1;dbname=shop_test): could not find driver

Relative file paths are resolved against the current working directory, so __DIR__ is the safer choice.

Working with it

Method Returns What it does
runFile(string $sqlFile) Database Runs every statement in an SQL file (schema, seeds).
execute(string $sql, array $parameters = []) int Runs a statement, returns the affected row count.
select(string $sql, array $parameters = []) list<array> All rows as associative arrays.
selectOne(string $sql, array $parameters = []) ?array The first row, or null.
insert(string $table, array $row) string Inserts column => value, returns the new id.
count(string $table) int Number of rows in the table.
beginTransaction() Database Opens a transaction.
rollBack() void Rolls back the open transaction; does nothing if there is none.

Statements are prepared, so parameters can be positional (?) or named (:name):

$id = $db->insert('products', ['name' => 'Hub', 'price' => 25]);

$db->execute('UPDATE products SET price = :price WHERE id = :id', ['price' => 30, 'id' => $id]);

Assert::exact(['name' => 'Hub', 'price' => 30], $db->selectOne('SELECT name, price FROM products WHERE id = ?', [$id]));

One transaction per test

Against a real database server, recreating the schema for every test gets slow. Open a transaction in the fixture and roll it back in the cleanup: every test sees the same starting data, and nothing it writes survives.

$tester->fixture(
    'db',
    fn() => Database::connect(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASSWORD'))->beginTransaction(),
    cleanup: fn(Database $db) => $db->rollBack(),
);

rollBack() is a no-op without an open transaction, so it’s safe as a cleanup even when the test committed or rolled back on its own.

HttpServer

HttpServer::start() runs your application with PHP’s built-in web server (php -S) on a free port, waits until it accepts connections, and returns a handle:

use MicroUnit\Toolkit\HttpServer;

$tester->fixture('app', fn() => HttpServer::start('public/index.php'), shared: true);

The argument is either a document root directory or a router script like public/index.php (then its directory becomes the document root). It’s resolved against the current working directory. Two optional arguments: environment (extra environment variables for the application process) and host (default 127.0.0.1).

HttpServer::start('public/index.php', environment: ['APP_ENV' => 'testing', 'DB_DSN' => 'sqlite::memory:']);
Member What it gives you
url(string $path = '/') An absolute URL on the server: $app->url('/orders?page=2').
log() Everything the server process logged: requests and PHP errors. Gold when a request returns 500.
stop() Stops the server. Also happens automatically when the object is destroyed.
host, port Where it listens.

If the server doesn’t come up within 10 seconds, start() throws with the server’s log in the message, so a typo in the router path or a fatal error in your bootstrap shows up right there.

Http and HttpResponse

MicroUnit\Toolkit\Http is a tiny HTTP client built on PHP’s stream wrappers, so it needs no cURL. Two decisions make it good for tests: redirects are not followed (you want to assert them), and 4xx/5xx responses are returned, not thrown.

use MicroUnit\Toolkit\Http;

$response = Http::get($app->url('/products'));
$response = Http::get($app->url('/me'), headers: ['Authorization' => 'Bearer secret']);
$response = Http::post($app->url('/orders'), json: ['sku' => 'A1', 'quantity' => 2]);
$response = Http::put($app->url('/orders/1'), body: 'raw body', headers: ['Content-Type' => 'text/plain']);
$response = Http::patch($app->url('/orders/1'), json: ['quantity' => 3]);
$response = Http::delete($app->url('/orders/1'));
$response = Http::request('OPTIONS', $app->url('/orders'));

json: encodes the array and sets Content-Type and Accept to application/json (unless you set them yourself). If the server can’t be reached at all, a RuntimeException says so. The timeout is 30 seconds.

Every call returns an HttpResponse:

$response->status;               // 201
$response->body;                 // the raw body
$response->headers;              // ['location' => ['/orders/1'], ...], names lower-cased
$response->header('Location');   // '/orders/1', case-insensitive, first value or null
$response->json();               // decoded body as arrays, throws on invalid JSON

AssertResponse

AssertResponse is a fluent assertion for HTTP responses. It accepts MicroUnit’s HttpResponse, PSR-7 responses, Symfony responses, Laravel’s TestResponse and CodeIgniter’s TestResponse, so the same assertions work whether the response came from a real server or a framework’s test client.

use MicroUnit\Assertion\AssertResponse;

$tester->define('creating_an_order_returns_its_location', function (HttpServer $app) {
    $response = Http::post($app->url('/orders'), json: ['sku' => 'A1']);

    AssertResponse::begin($response)
        ->statusIs(201)
        ->headerIs('Location', '/orders/1')
        ->jsonPathEquals('data.sku', 'A1');
});
Method Passes when
statusIs(int $expected) The status is exactly $expected.
isOk() The status is any 2xx.
isNotFound() The status is 404.
isRedirect(?string $location = null) The status is 3xx, and the Location header equals $location if given.
headerIs(string $name, string $expected) The header equals $expected.
headerContains(string $name, string $needle) The header contains $needle.
bodyContains(string $needle) The body contains $needle.
bodyEquals(string $expected) The body is exactly $expected.
jsonEquals(mixed $expected) The decoded JSON equals $expected (loose ==, so key order in objects doesn’t matter).
jsonPathEquals(string $path, mixed $expected) The value at a dot path is identical (===) to $expected: 'data.items.0.id'.
jsonHasPath(string $path) The dot path exists in the JSON body.

Every method takes an optional $message as its last argument. Failures include an excerpt of the response body, which is usually all you need to see why:

[✖] the_product_page_loads (1.37ms)
    Failed asserting that the response is successful (2xx).
    Response body: {"error":"not found"}
    Expected: '2xx' (string)
    Actual  : 404 (int)

TemporaryDirectory

Tests that write files should write them somewhere fresh and throw it away afterwards. TemporaryDirectory::create() makes a uniquely named directory under the system temp directory (the optional argument is the name prefix, default microunit):

use MicroUnit\Toolkit\TemporaryDirectory;

$tester->fixture('dir', fn() => TemporaryDirectory::create(), cleanup: fn(TemporaryDirectory $dir) => $dir->delete());

$tester->define('exports_a_csv_report', function (TemporaryDirectory $dir) {
    new ReportExporter()->export($dir->path('reports/march.csv'));

    Assert::isTrue($dir->exists('reports/march.csv'));
    Assert::stringStartsWith('date,revenue', $dir->read('reports/march.csv'));
});
Method What it does
path(string $relativePath = '') Absolute path inside the directory (the root itself without an argument). Also available as $dir->root.
write(string $relativePath, string $contents) Writes a file, creating parent directories, and returns its absolute path.
read(string $relativePath) The file’s contents; throws if it doesn’t exist.
exists(string $relativePath) Whether the file or directory exists.
delete() Removes the directory and everything in it.

Assert::eventually: for things that become true later

Queues, background workers, file watchers, a server that’s still warming up: some results don’t exist at the moment you check. Sleeping for a fixed time makes tests slow when the system is fast and flaky when it’s slow. Assert::eventually() retries a check until it passes or the timeout runs out, then reports the last failure:

$tester->define('the_worker_sends_the_confirmation', function (Database $db) {
    dispatchOrder($db, sku: 'A1');

    $mail = Assert::eventually(function () use ($db) {
        $mail = $db->selectOne('SELECT * FROM outbox WHERE subject = ?', ['Order confirmed']);
        Assert::notNull($mail);

        return $mail;
    }, timeoutInSeconds: 3);

    Assert::stringContains('A1', $mail['body']);
});

The check passes when no assertion inside it fails, nothing throws, and it doesn’t return false. eventually() then returns whatever the check returned. Note that returning null counts as passing, so assert on the value (as above) instead of just returning it.

The signature is eventually(callable $check, float $timeoutInSeconds = 5.0, float $intervalInSeconds = 0.1, string $message = ''). When time runs out, the failure tells you how many attempts were made and what went wrong on the last one:

Failed asserting that the check passes within 3 s (31 attempts). Last failure:
  Failed asserting that value is not null.

Skipping when a service is missing

A test that needs Redis shouldn’t fail on a laptop without Redis. It should say “skipped, here’s why” and get out of the way. Database::sqlite() and Database::connect() do this for you. For everything else:

use MicroUnit\Assertion\Assert;

$tester->define('caches_the_price_list', function () {
    Assert::skipIf(!extension_loaded('redis'), 'The redis extension is not installed.');
    // ...
});

$tester->define('uploads_to_s3', function () {
    if (getenv('S3_BUCKET') === false) {
        Assert::skip('S3_BUCKET is not set.');
    }
    // ...
});

Skips work anywhere in the chain: in the test, in setUp(), in a fixture factory, and in setUpOnce(), where they skip the whole suite. Skipped tests don’t fail the run, and every report lists them with their reason.

In CI, where the services are supposed to exist, skips can hide a broken setup. Glance at the skipped list in your reports now and then, or provide the service so the tests actually run (see CI/CD).

Keeping integration tests separate

Integration tests are slower, and you don’t always want them. Put them in their own test group:

return MicroUnitConfigBuilder::create()
    ->withTestGroup('unit', 'tests/Unit')
    ->withTestGroup('integration', 'tests/Integration')
    ->build();

microunit --group=unit runs the fast ones while you work, and a plain microunit runs everything. See Configuration and Command line.

Edit this page on GitHub MicroUnit 1.0