Skip to content

Test board setup

Jump to bottom
William Jacoby edited this page Oct 28, 2026 · 1 revision

Local test-board setup

  • git, php (with the sqlite3 extension), composer, curl, jq and openssl
  • Python 3 with venv
  • ImageMagick's convert, for the reassignthumbs feature check
  • Docker, for php-lint.sh

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

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.

Build the board

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.

Short Long Behavior
-d --dir DIR Required destination. Use a dedicated disposable directory.
-v --version VERSION Explicit phpBB release; otherwise current stable 3.3 from the version feed.
-f --force Replace the existing board; inspect the destination first.
-h --help Show usage.

The setup script clones the selected release and installs Composer dependencies. It creates local test credentials; keep board.env private. Never use a production board or expose this test service to a network.

Shared runtime options

smoke_test.py, feature_checks.py, screenshots.py and rename_upgrade.py take:

Option Behavior
-b, --board-dir DIR Explicit board location; otherwise PHPBB_TEST_BOARD.
-p, --port PORT Temporary PHP server port, default 8083.
-w, --with PATH[@REF] Repeatable dependency checkout, enabled before the target. Default dependency ref HEAD.
-h, --help Usage and tool-specific guidance.

Do not run tools concurrently against the same board: they restore the database and manipulate installed project files. Use separate board directories and ports for independent work. A different port alone does not isolate database resets.

Reset behavior

  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.

The board is for phpBB 3.3 runtime testing. Selecting master in the separate PHPUnit runner does not turn this disposable board into a phpBB 4 runtime environment.

Clone this wiki locally