Testing and CI

Testing & CI

The suite is the contract: 329 tests / 966 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                      # the whole matrix + rebuild

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

	src	php83 bundle	php85 bundle
PHP 8.3	✅ 329	✅ 327	— (parse error by design)
PHP 8.4	✅	✅	—
PHP 8.5	✅ 329	✅ 327	✅ 327

What's covered (14 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 (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\n(+baseline)"]
    PR --> F["PHP-CS-Fixer\n(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, [OK] No errors with an 8-entry baseline (phpstan-baseline.neon, all literal-type-inference cosmetics). Baseline entries may shrink, never grow, without review.
• CS: PER-CS2.0 + strict types + alpha imports via .php-cs-fixer.dist.php (dry-run in CI; run it locally before pushing).

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.