# 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.