449e6f8e03
- 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
73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
# Testing
|
|
|
|
## Workflow
|
|
|
|
When modifying or adding functions in `app/`, follow this sequence — **a task is not complete until all steps are done**:
|
|
|
|
1. **Write or update the code** in the relevant `app/*.php` file.
|
|
2. **Write tests** in `devel/tests/<module>/` matching the changed file (e.g. `app/content.php` → `devel/tests/content/`).
|
|
3. **Run the tests:** `cd devel && ./tests/run.sh`
|
|
4. **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](https://php.github.io/php-src/miscellaneous/writing-tests.html) ([lessons learned](https://wiki.php.net/qa/phptlessonslearned)). The runner is a minimal PHP script — no test framework, no Composer. Tests cover `app/` only.
|
|
|
|
### Running
|
|
|
|
```bash
|
|
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](https://github.com/pestphp/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.
|