Configuring Testo (testo.php)

Testo's config is a real PHP file at the project root returning an ApplicationConfig. No XML, no JSON. This means: full IDE completion, refactoring, and conditional logic (e.g. CI-only suites).

Fetch https://php-testo.github.io/llms.txt before introducing new classes — the namespaces here are the most commonly drifted-on detail.

Bootstrap with init

If the project has no testo.php yet, prefer the built-in command over hand-writing the file:

vendor/bin/testo init
vendor/bin/testo init --path=app
vendor/bin/testo init --no-interaction

What it does, in order:

1. Ensures the base directory (--path, default .) exists. --path is treated as the project root — every subsequent lookup (src/, tests/, composer.json) and every path baked into the generated testo.php is resolved relative to it.
2. Resolves the source directory under --path:
   • if <path>/src exists, uses it;
   • otherwise in interactive mode prompts for a directory (default src, must exist under --path);
   • otherwise (non-interactive) fails — create <path>/src first or run interactively. The path is written into the config relative to testo.php, so a src entry resolves back to <path>/src at runtime, regardless of where vendor/bin/testo is invoked from.
3. Creates <path>/tests/ and scans it for known suite folders: Unit, Integration, Functional, Acceptance, Feature, E2E, Contract. Whatever exists is picked up; Unit is always added (and <path>/tests/Unit/ created if missing).
4. Writes scripts to the composer.json colocated with --path (so a monorepo sub-app updates its own composer.json, not the parent one). If no composer.json is present at that path the step is skipped silently.
   • composer test → vendor/bin/testo
   • composer test:unit, composer test:integration, … one per detected suite (vendor/bin/testo --suite=<Name>). Existing keys are preserved.
5. Generates <path>/testo.php from the stub, with src and one SuiteConfig per detected suite. If the file already exists: prompts to overwrite (interactive) or skips with a warning (non-interactive).

When to use init vs. hand-editing:

• New project / empty repo → run init first, then tune testo.php.
• Adding a suite to an existing project → create the directory (e.g. tests/Integration) and re-run init to get the matching composer script, or edit testo.php directly. init will not overwrite an existing config unless confirmed.
• Monorepo / sub-app layout (a self-contained app under app/, with its own src/, tests, and optionally composer.json) → vendor/bin/testo init --path=app. --path is the sub-app's project root: app/src/ must exist, and the generated app/testo.php references src and tests/<Suite> as paths relative to itself — so they resolve correctly regardless of where vendor/bin/testo is invoked from.

After init completes, re-read testo.php and adjust src, suite locations, and plugins to match the project (see sections below).

Minimal testo.php

<?php
declare(strict_types=1);

use Testo\Application\Config\ApplicationConfig;
use Testo\Application\Config\SuiteConfig;

return new ApplicationConfig(
    src: ['src'],
    suites: [
        new SuiteConfig(name: 'Unit', location: ['tests/Unit']),
    ],
);

Run it: vendor/bin/testo. The single suite Unit will be discovered under tests/Unit.

Anatomy

Suite is the plugin-scope boundary. A Test Suite is a named, configured collection of Test Cases (a Test Case = methods of one class or functions of one file). Different suites can carry different plugin sets — that's the whole reason SuiteConfig::$plugins and SuitePlugins::only(...) exist.

ApplicationConfig takes:

• src — directories (string[] or FinderConfig) holding production code. Used by coverage and inline tests.
• suites — array of SuiteConfig, one per logical test area.
• plugins — application-wide plugins (coverage, JUnit, anything cross-cutting).

SuiteConfig takes:

• name — string, must be unique. Selectable via --suite=<name>.
• location — directories or FinderConfig for the suite's test files.
• plugins — suite-specific plugins, or SuitePlugins::only(...) to override inherited application plugins.

FinderConfig(include, exclude) — when a flat array isn't enough (e.g. exclude module's own tests):

new FinderConfig(
    include: ['core', 'plugin', 'bridge'],
    exclude: ['plugin/assert/tests', 'plugin/codecov/tests'],
);

Multi-suite layout

A typical real-world testo.php:

<?php
declare(strict_types=1);

use Testo\Application\Config\ApplicationConfig;
use Testo\Application\Config\FinderConfig;
use Testo\Application\Config\SuiteConfig;
use Testo\Application\Config\Plugin\SuitePlugins;
use Testo\Codecov\CodecovPlugin;
use Testo\Codecov\Config\CoverageLevel;
use Testo\Codecov\Report\CloverReport;
use Testo\Inline\InlineTestPlugin;

return new ApplicationConfig(
    src: ['src'],
    suites: [
        new SuiteConfig(name: 'Unit',        location: ['tests/Unit']),
        new SuiteConfig(name: 'Integration', location: ['tests/Integration']),
        new SuiteConfig(
            name: 'Sources',
            location: ['src'],
            plugins: SuitePlugins::only(new InlineTestPlugin()),
        ),
    ],
    plugins: [
        new CodecovPlugin(
            level: CoverageLevel::Line,
            reports: [
                new CloverReport(__DIR__ . '/runtime/clover.xml', 'MyProject'),
            ],
        ),
    ],
);

Notes on the example:

• Sources scans the production tree to pick up #[TestInline] cases; SuitePlugins::only ensures only InlineTestPlugin runs for that suite.
• CodecovPlugin is application-wide → it applies to every suite.
• Names are arbitrary; keep them short — they appear in CI logs and in --suite=.

Reports on every run

Output plugins are application-wide. Add them to plugins: when a report should be produced by every run rather than only when a flag asks for it:

use Testo\Output\Html\HtmlPlugin;
use Testo\Output\JUnit\JUnitPlugin;

plugins: [
    // runtime/report/index.html; a path ending in .html inlines everything into that one file instead
    new HtmlPlugin(),
    new JUnitPlugin(__DIR__ . '/build/junit.xml'),
],

HtmlPlugin takes a second path for the report's own JSON document (new HtmlPlugin('runtime/report', 'runtime/report.json')) — the HTML is a view over that document, and CI or external tooling can consume it on its own. The HTML report opens over file:// with no server and reaches no network.

Conditional / dynamic config

Because testo.php is real PHP, conditional logic is fine:

$ciOnly = \filter_var(\getenv('CI'), FILTER_VALIDATE_BOOLEAN);

return new ApplicationConfig(
    src: ['src'],
    suites: \array_merge(
        [new SuiteConfig(name: 'Unit', location: ['tests/Unit'])],
        $ciOnly ? [] : [new SuiteConfig(name: 'Sandbox', location: ['tests/Sandbox'])],
    ),
);

Keep it readable — if the logic gets long, extract a helper, don't pile up ternaries.

CLI cheat-sheet

vendor/bin/testo init                          # bootstrap testo.php + composer scripts
vendor/bin/testo init --path=app               # bootstrap inside a subdirectory
vendor/bin/testo --config=path/to/testo.php    # run with a config outside the project root

Running and filtering (--json, --suite, --filter, --path, --group, --type, report outputs) are covered by the testo-run-tests skill; coverage flags by the testo-coverage skill.

Pitfalls

• src must include production code only, not tests. Otherwise inline tests will run against test fixtures and coverage will count test files.
• SuitePlugins::only(...) replaces inherited plugins. If the suite still needs coverage, add CodecovPlugin to the only() list too.
• Don't name two suites the same. The first one wins silently in some builds — keep names unique.
• Don't shell out to composer dump-autoload from testo.php. Composer's autoloader is already booted by the CLI entry. Avoid side-effects in config.
• Don't read environment variables without a fallback. \getenv('FOO') ?: 'default' — CI dropouts otherwise silently change which suites run.
• testo.php is required. If a project doesn't have one, run vendor/bin/testo init (see Bootstrap with init) or, for full control, write the minimal version above by hand.
• An empty run is not a success. Zero discovered tests → status risky, non-zero exit (details in the testo-run-tests skill). On the config side the usual causes are a suite location pointing at the wrong directory or an empty suite.