GuideTesting

Guide

Testing

Render an App in PHPUnit and assert on the parsed YAML - environment differences, subscribers and wiring, with no cluster.

Half the case for manifests as code is that code can be tested: a change to the infrastructure gets the same CI safety net as a change to the product. The pattern is short: boot the kernel, render an App, parse the YAML, assert on fields.

Two properties make such tests pleasant:

  • Rendering is deterministic. The same code, configuration and environment give the same bytes. No cluster, no network, no clock.
  • Rendering is complete. A render test runs your classes and every subscriber, configuration file and framework rule at once: it tests what will be applied, not a unit apart from it.

A render test

A Klass8s project is a Symfony application, so its tests are KernelTestCases. AppManager::generateManifests() renders Apps exactly as k8s:render:apps does:

tests/K8S/ShopRenderTest.phntests/K8S/ShopRenderTest.php
testApiDeployment(): void {
    $deployment = self::find(self::render('shop'), 'Deployment', 'shop-api');

    self::assertNotNull($deployment, 'no Deployment shop-api in the output');
    self::assertSame(2, self::at($deployment, 'spec.replicas'));
    self::assertSame('registry.example.com/acme/shop-api:1.0.0', self::at($deployment, 'spec.template.spec.containers.0.image'));
    self::assertNotNull(
        self::at($deployment, 'spec.template.metadata.annotations.klass8s\.dev/env-sources-checksum'),
        'no checksum: a configuration change would not restart the pods',
    );
}
public function testApiDeployment(): void
{
    $deployment = self::find(self::render('shop'), 'Deployment', 'shop-api');

    self::assertNotNull($deployment, 'no Deployment shop-api in the output');
    self::assertSame(2, self::at($deployment, 'spec.replicas'));
    self::assertSame('registry.example.com/acme/shop-api:1.0.0', self::at($deployment, 'spec.template.spec.containers.0.image'));
    self::assertNotNull(
        self::at($deployment, 'spec.template.metadata.annotations.klass8s\.dev/env-sources-checksum'),
        'no checksum: a configuration change would not restart the pods',
    );
}

The helpers render, parse and find; at() reads a value by its path, which keeps the assertions short in a typed test:

tests/K8S/ShopRenderTest.phntests/K8S/ShopRenderTest.php
/** The documents an App renders in an environment, parsed: what k8s:render:apps prints. */
private static render(string $app, string $environment = 'test'): list<array<mixed>> {
    self::ensureKernelShutdown();
    self::bootKernel(['environment' => $environment]);
    $manager = self::getContainer()->get(AppManager::class);
    assert($manager instanceof AppManager);

    $documents = [];
    foreach (explode("\n---\n", $manager->generateManifests($app)->render()->toString()) as $text) {
        $document = Yaml::parse($text); // the "# File:" line is a YAML comment
        if (is_array($document) && is_string($document['kind'] ?? null)) {
            $documents[] = $document;
        }
    }

    return $documents;
}

/** @param list<array<mixed>> $documents */
private static find(list<array<mixed>> $documents, string $kind, string $name): ?array<mixed> {
    foreach ($documents as $document) {
        if ($kind === $document['kind'] && $name === self::at($document, 'metadata.name')) {
            return $document;
        }
    }

    return null;
}

/** The value at a dotted path ("spec.template.spec"; "\." for a dot in a key), or null. */
private static at(mixed $value, string $path): mixed {
    foreach (preg_split('/(?<!\\\\)\./', $path) ?: [] as $key) {
        $key = str_replace('\.', '.', $key);
        if (!is_array($value) || !array_key_exists($key, $value)) {
            return null;
        }
        $value = $value[$key];
    }

    return $value;
}
/**
 * The documents an App renders in an environment, parsed: what k8s:render:apps prints.
 * @return list<array<mixed>>
 */
private static function render(string $app, string $environment = 'test'): array
{
    self::ensureKernelShutdown();
    self::bootKernel(['environment' => $environment]);
    $manager = self::getContainer()->get(AppManager::class);
    assert($manager instanceof AppManager);

    $documents = [];
    foreach (explode("\n---\n", $manager->generateManifests($app)->render()->toString()) as $text) {
        $document = Yaml::parse($text); // the "# File:" line is a YAML comment
        if (is_array($document) && is_string($document['kind'] ?? null)) {
            $documents[] = $document;
        }
    }

    return $documents;
}

/**
 * @param list<array<mixed>> $documents
 * @return ?array<mixed>
 */
private static function find(array $documents, string $kind, string $name): ?array
{
    foreach ($documents as $document) {
        if ($kind === $document['kind'] && $name === self::at($document, 'metadata.name')) {
            return $document;
        }
    }

    return null;
}

/** The value at a dotted path ("spec.template.spec"; "\." for a dot in a key), or null. */
private static function at(mixed $value, string $path): mixed
{
    foreach (preg_split('/(?<!\\\\)\./', $path) ?: [] as $key) {
        $key = str_replace('\.', '.', $key);
        if (!is_array($value) || !array_key_exists($key, $value)) {
            return null;
        }
        $value = $value[$key];
    }

    return $value;
}

Parse, then assert on fields: not string matching, which breaks on formatting, and not snapshots, which assert everything and so explain nothing when they fail. Your Apps and manifests are services of your own kernel, so no fixture wiring is needed. Point PHPUnit at the kernel with KERNEL_CLASS in phpunit.dist.xml, as for any Symfony test.

Environment differences

The claims most worth a test are those that differ per environment, because those are the ones nobody sees in development:

tests/K8S/ShopRenderTest.phntests/K8S/ShopRenderTest.php
testProductionSize(): void {
    $deployment = self::find(self::render('shop', 'prod'), 'Deployment', 'shop-api');

    self::assertSame(6, self::at($deployment, 'spec.replicas'), 'replicasProd() not applied');
    self::assertSame('1Gi', self::at($deployment, 'spec.template.spec.containers.0.resources.limits.memory'));
}
public function testProductionSize(): void
{
    $deployment = self::find(self::render('shop', 'prod'), 'Deployment', 'shop-api');

    self::assertSame(6, self::at($deployment, 'spec.replicas'), 'replicasProd() not applied');
    self::assertSame('1Gi', self::at($deployment, 'spec.template.spec.containers.0.resources.limits.memory'));
}

Booting the kernel in an environment covers environment methods, decorators, #[EnabledForEnvs] and per-environment configuration with one style of assertion. A development-only manifest is one assertNull(self::find(…)) under the prod kernel away from being proven development-only.

Rules

Subscribers are where a mistake repeats across every service, so they repay testing most:

  • A default: render an App whose manifest sets no ServiceAccount and assert that the subscriber filled in spec.template.spec.serviceAccountName.
  • An enforced rule: a subscriber that throws (memory limits in production) is tested with expectException() around a render of a manifest that breaks it. Proving that the render fails is the point of an enforcing rule.

Smoke tests

Symfony's lint:container compiles the whole container (every manifest, subscriber and compiler pass) and fails on wiring mistakes; bin/console lint:container in CI, or a CommandTester in a test, runs it. The same CommandTester can run k8s:render:apps end to end.

What to test

Test your decisions: environment differences, subscribers, references across Apps, checksums on workloads that read configuration, the field you set through configure<Kind>(). Do not re-prove the framework: one test per project that every document of an App carries the identity labels and klass8s.dev/* annotations is enough.

And bin/console k8s:render:apps | kubectl diff -f - against a cluster answers a different question, "what would change?", where a test answers "is this still true?". CI wants both: render tests on every pull request, a diff when deploying.