Add a README for phpbb-test-board

README.md

@@ -1,6 +1,6 @@
 # phpbb-release-tools
 
-Tools for phpBB packages: Bash scripts that build release ZIPs and publish them as GitHub Releases, and a local test board for smoke-testing extensions (`phpbb-test-board/`).
+Tools for phpBB packages: Bash scripts that build release ZIPs and publish them as GitHub Releases, and a local test board for testing extensions and styles and taking their documentation screenshots (`phpbb-test-board/`).
 
 ## Tools
 
@@ -22,7 +22,7 @@ The scripts share their GitHub release code in [`lib/github-release.sh`](lib/git
 - `git-release-langpack.sh`: `git`, `curl`, `jq`, `unzip`, `zip`. For `--check` also `php`, `composer` and `sha256sum`.
 - `git-release-api.sh`: `git`, `jq`, `zip`, and GNU coreutils (`timeout`, `mktemp`, `stat`).
 - `--gh-release` and `git-release-api.sh` also need an authenticated GitHub CLI (`gh`), `jq` and `timeout`, with permission to create releases and upload assets.
-- `phpbb-test-board/`: `git`, `php` (with the `sqlite3` extension), `composer`, `curl`, `jq`, `openssl`, Python 3 with `venv`, and ImageMagick's `convert` for the reassignthumbs feature check. The Python scripts create and use their own virtualenv (`phpbb-test-board/.venv`) on first run.
+- `phpbb-test-board/`: see [its README](phpbb-test-board/README.md#requirements).
 
 ## Usage
 
@@ -87,30 +87,17 @@ A version ending in `-dev` is a rolling prerelease. The first release creates it
 
 The tag is reserved at the pinned commit before the release is created. A failure after tag creation may leave that tag without a release. The release stays a draft until its asset upload is confirmed. If uploading or publishing fails, the script reports the release URL and exits with an error. Inspect the remote state before retrying. For stable, alpha, beta, and RC versions a retry stops when it finds the existing tag or release. For a `-dev` version a retry reuses the leftover tag or draft release and finishes the update. A publication timeout may mean publication succeeded but could not be confirmed. Requests have finite timeouts and remote write requests are not retried automatically.
 
-### Testing extensions: `phpbb-test-board/`
+### Testing extensions and styles: `phpbb-test-board/`
 
-Builds a local phpBB board on SQLite and runs an extension on it with PHP error logging on, to catch problems that validation and syntax checks miss, such as pages that crash at runtime, forms that can never submit, or an extension that can't be enabled on a fresh board. For local testing only; never expose the board to a network.
+Builds a local phpBB 3.3 board on SQLite and tests extensions on it: `smoke_test.py` checks that an extension doesn't break any page, `feature_checks.py` exercises its main feature, and `screenshots.py` takes documentation screenshots of extensions and styles. For local testing only.
 
 ```bash
 phpbb-test-board/setup-board.sh -d ~/phpbb-test-board
 export PHPBB_TEST_BOARD=~/phpbb-test-board
 phpbb-test-board/smoke_test.py path/to/extension --ref origin/main
-phpbb-test-board/feature_checks.py path/to/extension@origin/main
-phpbb-test-board/screenshots.py path/to/extension@origin/main -o path/to/extension/docs/images
 ```
 
-For an extension that needs another one, pass the other extension's checkout with `--with` (repeat it for several, in the order they must be enabled):
-
-```bash
-phpbb-test-board/smoke_test.py path/to/sfscompanion --with path/to/stopforumspam
-```
-
-- `setup-board.sh` installs the current phpBB 3.3 release (or `--version`) with no extensions, and keeps a clean copy of the database so every test starts from the same state. The admin password is generated and stored only in `board.env`.
-- `smoke_test.py` installs the extension from git, loads board pages as a guest and as the admin, the extension's routes, ACP/MCP/UCP modules and cron tasks, then disables, deletes data and re-enables it. It reports any server error, empty page, phpBB debug notice or PHP error-log entry.
-- `feature_checks.py` exercises the main feature of the phpbbmodders extensions listed in its `--help` (for example: a moderator can't warn a user in an unticked group). Add a check for a new extension in its `CHECKS` table.
-- `screenshots.py` saves PNG screenshots of an extension's or a style's pages for its documentation, using [Playwright](https://playwright.dev/python/) with Chromium on a board named "Example board" (English). An extension is shown in prosilver, with its board and ACP pages; a checkout with a `style.cfg` is installed as a style and made every user's style. The pages are listed per project in its `SHOTS` table. `--seed SCRIPT` fills the board with forums, topics and users first, for example with [seed-forum](https://github.com/phpbbmodders/seed-forum)'s `bin/seed-standard-fixtures.php`. The first run downloads Playwright's Chromium. phpbbmodders/documentation also needs `--build DIR`, a phpbbdocs-hugo build to serve.
-- The board is restored after each run. Each script has `--help`.
-- `--with` extensions are installed and enabled before the extension under test and stay enabled; only the extension under test goes through the disable and delete data round trip. `feature_checks.py` installs a `--with` extension only for the extensions whose `composer.json` requires it. If `composer.json` requires a package you didn't supply, the scripts print a note naming it.
+See [`phpbb-test-board/README.md`](phpbb-test-board/README.md) for every script and option.
 
 ## Tests
 

phpbb-test-board/README.md

@@ -0,0 +1,111 @@
+# phpbb-test-board
+
+Tools for testing phpBB extensions and styles on a local phpBB 3.3 board, and for taking their documentation screenshots.
+
+They build a board on SQLite and run an extension on it with PHP error logging on. This catches problems that validation and syntax checks miss, such as pages that crash at runtime, forms that can never submit, or an extension that can't be enabled on a fresh board.
+
+**For local testing only.** Never expose the board to a network: its admin account and test users exist only for testing.
+
+## Requirements
+
+- `git`, `php` (with the `sqlite3` extension), `composer`, `curl`, `jq` and `openssl`
+- Python 3 with `venv`
+- ImageMagick's `convert`, for the reassignthumbs feature check
+
+The Python scripts create their own virtualenv (`.venv` in this folder) on first run and install `requirements.txt` into it; nothing needs installing or activating by hand. `screenshots.py` also downloads Playwright's Chromium on its first run.
+
+## Quick start
+
+```bash
+phpbb-test-board/setup-board.sh -d ~/phpbb-test-board
+export PHPBB_TEST_BOARD=~/phpbb-test-board
+phpbb-test-board/smoke_test.py path/to/extension --ref origin/main
+phpbb-test-board/feature_checks.py path/to/extension@origin/main
+```
+
+Instead of setting `PHPBB_TEST_BOARD`, each script also takes `--board-dir DIR`. Every script has `--help`.
+
+## The scripts
+
+### `setup-board.sh`: build the board
+
+```bash
+phpbb-test-board/setup-board.sh -d DIR [-v VERSION] [-f]
+```
+
+Installs the current stable phpBB 3.3 release, or `--version`, with no extensions enabled. It writes:
+
+| File | What it is |
+|---|---|
+| `DIR/phpbb/` | the board |
+| `DIR/board.sqlite3` | its database |
+| `DIR/board.clean.sqlite3` | a copy of the fresh database, so every run starts from the same state |
+| `DIR/board.env` | the board's paths and the generated admin password (mode 600; the password is never printed) |
+
+`--force` replaces an existing board in `DIR`.
+
+### `smoke_test.py`: does the extension break anything?
+
+```bash
+phpbb-test-board/smoke_test.py path/to/extension [--ref REF]
+```
+
+Installs the extension from git and loads, as a guest and as the admin:
+- the main board pages;
+- the extension's routes;
+- its ACP, MCP and UCP modules in every mode;
+- its cron tasks.
+
+It then disables the extension, deletes its data and enables it again. It reports any server error, empty page, phpBB debug notice or PHP error-log entry.
+
+### `feature_checks.py`: does the extension's main feature work?
+
+```bash
+phpbb-test-board/feature_checks.py path/to/extension[@REF] [more extensions...]
+```
+
+Exercises the main feature of each phpbbmodders extension that has a check. One example: a moderator can't warn a user in a group that isn't ticked. `--help` lists the extensions with checks. To add one, write a `check_<name>()` function and add it to the `CHECKS` table, keyed by the extension's composer name.
+
+### `screenshots.py`: documentation screenshots
+
+```bash
+phpbb-test-board/screenshots.py path/to/project[@REF] -o path/to/project/docs/images [--seed SCRIPT]
+```
+
+Saves PNG screenshots of an extension's or style's pages with [Playwright](https://playwright.dev/python/) and Chromium. The board is named "Example board" and uses English.
+- **Extensions** are shown in prosilver, with their board and ACP pages.
+- **Styles** are recognised by their `style.cfg`. The style is installed and made every user's style.
+
+`--help` lists the projects with screenshots. To add one, write a `shots_<name>()` function and add it to the `SHOTS` table, keyed by the extension's composer name or the style's name from `style.cfg`.
+
+**Options:**
+- `--seed SCRIPT` runs a PHP script that fills the board with forums, topics and users first, as `php SCRIPT BOARD_ROOT`. Use it for styles and for any pages that need real content; a fresh board has one forum and one post. [seed-forum](https://github.com/phpbbmodders/seed-forum)'s `bin/seed-standard-fixtures.php` works well.
+- `--build DIR` is for phpbbmodders/documentation only: the phpbbdocs-hugo build to serve.
+
+For example, ProMinoDeux's screenshots:
+
+```bash
+phpbb-test-board/screenshots.py path/to/ProMinoDeux -o path/to/ProMinoDeux/docs/images \
+  --seed path/to/seed-forum/bin/seed-standard-fixtures.php
+```
+
+## Extensions that need another extension
+
+Pass the other extension's checkout with `--with`. Repeat it for several, in the order they must be enabled:
+
+```bash
+phpbb-test-board/smoke_test.py path/to/sfscompanion --with path/to/stopforumspam
+```
+
+- **Install order:** `--with` extensions are installed and enabled first and stay enabled. Only the extension under test goes through `smoke_test.py`'s disable and delete-data round trip.
+- **In `feature_checks.py`:** a `--with` extension is installed only for the extensions whose `composer.json` requires it.
+- **Missing packages:** if `composer.json` requires a package you didn't supply, the scripts print a note naming it.
+
+## How a run works
+
+1. **Clean start:** the board's database is restored from `board.clean.sqlite3`.
+2. **Install:** the extension or style is copied from the given git ref, so uncommitted changes aren't tested.
+3. **Serve:** PHP's built-in server serves the board on port 8083 (`--port`) with opcache off and PHP errors logged to `DIR/php-errors.log`.
+4. **Restore:** afterwards, the extension or style is removed and the database restored again.
+
+Files written outside the extension's own directory, for example under `store/`, are not reset automatically. `screenshots.py` removes the documentation build it copies there afterwards; `feature_checks.py` empties that build directory before its documentation check.

phpbb-test-board/setup-board.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/bash
 # setup-board.sh
 #
-# Builds a local phpBB test board for smoke_test.py and feature_checks.py.
+# Builds a local phpBB test board for smoke_test.py, feature_checks.py and
+# screenshots.py.
 #
 # Clones a phpBB release (default: the current stable 3.3 release from
 # https://version.phpbb.com/phpbb/versions.json), installs its Composer
@@ -24,7 +25,8 @@ usage() {
   cat <<'EOF'
 Usage: setup-board.sh -d DIR [-v VERSION] [-f]
 
-Build a local phpBB test board for smoke_test.py and feature_checks.py.
+Build a local phpBB test board for smoke_test.py, feature_checks.py and
+screenshots.py.
 
 Options:
   -d, --dir DIR          directory to build the board in (required)