Testing and CI

Testing & CI

The suite is the contract: 386 tests / 1286 assertions run against every combination of PHP version and artifact, and several tests are the architecture documentation (no-eval/no-globals scan, engine independence, security containment).

Running tests

php8.3 tests/run.php                          # source tree (default)
php8.5 tests/run.php                          # source tree, newest PHP
php8.3 tests/run.php --lib=php83/html.php     # against the 8.3 bundle
php8.5 tests/run.php --lib=php85/html.php     # against the 8.5 bundle
php8.5 tests/run.php --filter=ssi --verbose   # filtered
php8.3 tests/run.php --list                   # inventory
bash tools/run-matrix.sh                      # whole matrix: 14 combos, both intl
                                              # modes; drift-checks bundles first,
                                              # never rewrites them (--build to opt in);
                                              # hard error when a PHP version is missing

Exit codes: 0 green · 1 failures · 2 harness error. Two tests skip in bundle mode (the per-file architecture scans) — everything else is artifact-independent.

The matrix

Every combination runs twice: with ext-intl and with it disabled (mbstring, :intl in CI, -d disable_functions=transliterator_transliterate locally) — 14 CI jobs. The suite is extension-independent by design (Str::slugify is deterministic); the two legs exist to keep it that way.

	src	php83 bundle	php85 bundle
PHP 8.3	✅ 386	✅ 384 (+2 skip)	— (parse error by design)
PHP 8.4	✅ 386	✅ 384 (+2 skip)	—
PHP 8.5	✅ 386	✅ 384 (+2 skip)	✅ 384 (+2 skip)

Identical numbers with intl on and off.

What's covered (15 case files)

01 config/container/scope/request · 02 support/io/pathguard · 03 escaper/cleaner · 04 cache/log/events · 05 SSI core · 06 SSI conditionals/exec · 07 substitution/filters · 08 structure tags · 09 i18n (incl. binary MO built in-test) · 10 render API/cache/stats · 11 linter · 12 WordPress (bridge/adapters/toolkit/CLI/admin/plugin files against a 60-function WP stub set) · 13 security (containment, budgets, token-level no-eval/no-globals scan, strict-types scan) · 14 CLI · 15 v5 expressions & math (inline %{= …}, index/get() containment, INF/NAN guards, AST-memo bound, infinite-generator budgets, linter codes) (subprocess exit codes).

Determinism: UTC pinned, FrozenClock injection, fixture tree under tests/tmp/ (auto-cleaned), per-test $GLOBALS/superglobal snapshot-restore, no network.

Writing tests

<?php
// tests/cases/15_my_feature.test.php
declare(strict_types=1);

group('My feature');

test('does the thing', function (): void {
    $engine = test_engine(['syntax' => ['auto_escape' => false]]);  // bootstrap helper
    assertSame('x', $engine->renderString('%{v}', ['v' => 'x']));
});

Runner API: group() test() assertSame/True/False/Null assertContains/ NotContains assertMatches assertThrows assertInstanceOf skip/skipIf fail. Helpers from tests/bootstrap.php: test_engine(array $config, ?FrozenClock), test_request(), test_options(), fixture_write/path/dir, run_isolated_php(), ssi() (in 05).

Rules of the house:

1. New behaviour ⇒ new assertions in the matching case file (or a new one).
2. Security-relevant change ⇒ a 13_security case proving the guard.
3. Bundle-visible change ⇒ run tools/build.php + both --lib legs.
4. WordPress-touching change ⇒ must pass against tests/wp-stubs.php (extend the stubs rather than skipping).

Continuous integration

.github/workflows/ci.yml:

flowchart LR
    PR[push / PR] --> T["tests job ×9\nPHP 8.3·8.4·8.5 × src·php83·php85\n(8.5 bundle excluded below 8.5)"]
    PR --> B[build bundles] --> C["build.php --check\n(drift gate)"] --> T
    PR --> S["PHPStan level 6 — mandatory\n(empty baseline, WP layer included)"]
    PR --> F["PHP-CS-Fixer — mandatory\n(pinned, dry run)"]
    PR --> W["wiki links\n(tools/check-wiki-links.php)"]

Loading

• Drift gate: bundles are rebuilt in CI and compared byte-for-byte with the committed ones — a PR that edits src/ without rebuilding fails.
• PHPStan: level 6 over the full src/ tree — the WordPress layer is analysed against the project's own WP stubs (bootstrapFiles), no exclusions. phpstan-baseline.neon is empty by policy (fix findings in code, never baseline them) and reportUnmatchedIgnoredErrors: true. The phar is version-pinned in CI (PHPSTAN_VERSION).
• CS: PER-CS2.x + strict types + alpha imports via .php-cs-fixer.dist.php; the fixer version is pinned in CI (PHP_CS_FIXER_VERSION) and the dry-run is a hard gate — run php-cs-fixer fix locally before pushing.
• Smoke: tests/smoke.php (end-to-end public-API tour) runs as its own job on PHP 8.3 and 8.5 (composer run smoke locally).
• Wiki links: tools/check-wiki-links.php validates every internal link and heading anchor of the wiki repository (cloned at check time).

Static analysis & style locally

# PHPStan (phar, no install)
curl -sSLo phpstan.phar https://github.com/phpstan/phpstan/releases/latest/download/phpstan.phar
php8.3 phpstan.phar analyse -c phpstan.neon --memory-limit=1G

# PHP-CS-Fixer
PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix --dry-run --diff

Benchmarks

php8.3 tools/bench.php 2000
# render (loops+ssi+i18n)   ~0.72 ms/op  · ~1.4k ops/s
# renderString (small)      ~0.014 ms/op · ~69k ops/s
# processSsi (5 directives) ~0.018 ms/op · ~54k ops/s
# t() with catalogue        ~0.002 ms/op · ~626k ops/s

Reference box: 2-vCPU container, PHP 8.3, opcache CLI off. A CI perf gate (±10 % regression fail) is on the ROADMAP.

Releasing

1. php tools/build.php && php tools/build.php --check
2. bash tools/run-matrix.sh (install 8.4 locally or let CI cover it)
3. Bump src/Version.php (+ src-8.5/Version.php), CHANGELOG.md, README badges, plugin header/readme.txt.
4. Tag v4.x.y; attach both bundles to the GitHub release (shared-hosting users download, not clone).
5. Publish wiki sync: bash tools/publish-wiki.sh --push.