Ruben 449e6f8e03 Update framework testing infrastructure and standards

- Add phpt test runner and suite for app functions
- Introduce testing workflow to AGENT.md
- Add tests for cache, content, context, helpers, hooks, plugins,
  rendering
- Mount tests directory in dev container

2026-03-17 12:51:07 +01:00

2.6 KiB

Raw Blame History

Testing

Workflow

When modifying or adding functions in app/, follow this sequence — a task is not complete until all steps are done:

Write or update the code in the relevant app/*.php file.
Write tests in devel/tests/<module>/ matching the changed file (e.g. app/content.php → devel/tests/content/).
Run the tests: cd devel && ./tests/run.sh
Fix any failures — do not consider the task done while tests are red.

When tests already exist for the changed function, update them to cover the new behaviour.

Not unit-testable (skip for these): router.php, static.php, template files, full HTTP flows.

Framework Tests (`app/`)

Unit tests live in devel/tests/ and use the phpt format (lessons learned). The runner is a minimal PHP script — no test framework, no Composer. Tests cover app/ only.

Running

cd devel

./tests/run.sh              # Run all tests
./tests/run.sh helpers      # Filter by subdir or filename substring

CONTAINER=my-container ./tests/run.sh to override the container name. Exit code 1 on any failure — CI-compatible. Container must be running (podman-compose up -d).

File Layout

devel/tests/
  run.php           # Runner — executed inside the container
  run.sh            # Host entry point (calls podman exec)
  helpers/          # Tests for app/helpers.php
  content/          # Tests for app/content.php
  config/           # Tests for app/config.php
  ...               # One subdir per app/ module

Writing Tests

App files are at /var/www/app/ inside the container. Require only what the function under test needs.

--TEST--
extractRawDateFromFolder: extracts YYYY-MM-DD from date-prefixed folder names
--FILE--
<?php
require '/var/www/app/helpers.php';
echo extractRawDateFromFolder('2024-01-15-my-post');
?>
--EXPECT--
2024-01-15

Filesystem tests: use sys_get_temp_dir() . '/phpt_' . getmypid() and clean up in --FILE--.

What to Test

Test	How
Pure functions	Direct call + echo
Filesystem functions	Temp dir, clean up after
Config merging, metadata parsing	Temp files or inline strings
Full HTTP flow	Browser or `perf.sh` — not unit-tested
Template rendering	Not unit-tested

Site Tests (`custom/`)

For sites built on top of the framework, Pest is a good fit — it supports browser testing via Playwright, useful for end-to-end testing of custom templates, plugins, and content. Pest is not used in this repo.

2.6 KiB Raw Blame History