diff --git a/.claude/skills/scaffold/SKILL.md b/.claude/skills/scaffold/SKILL.md index ea6ddac4..71d9e1c5 100644 --- a/.claude/skills/scaffold/SKILL.md +++ b/.claude/skills/scaffold/SKILL.md @@ -202,9 +202,9 @@ Then report: **Test env + linters (`wp-env`):** - Always use `npx wp-env` (or `node_modules/.bin/wp-env`), never bare `wp-env`. - **Run PHP linters inside wp-env (PHP 8.2).** The host PHP may be newer than the pinned `wp-coding-standards/wpcs` supports, which makes the sniffs throw deprecation errors and abort. Run e.g. `npx wp-env run cli --env-cwd=/var/www/html/wp-content/themes/$(basename "$PWD") -- vendor/bin/phpcs ` (PHPStan tolerates newer PHP, so `composer phpstan` is fine on the host). -- If `wp-env start` reports a port already allocated, start on free alternates: `WP_ENV_PORT=8890 WP_ENV_TESTS_PORT=8891 npm run wp-env start` (find a free pair with `lsof -nP -iTCP: -sTCP:LISTEN`). The theme's default ports are 5890 (dev) / 5891 (tests). +- If `wp-env start` reports a port already allocated, start on a free alternate: `WP_ENV_PORT=8890 npm run wp-env start`, or `WP_ENV_PORT=8891 npm run test:php` for the test environment (find a free port with `lsof -nP -iTCP: -sTCP:LISTEN`). The theme's default ports are 5890 (dev, `.wp-env.json`) and 5891 (tests, `.wp-env.tests.json`). - `wp-env start` can flake on a transient image pull (TLS timeout); one retry is allowed, and exit 0 does not mean "up" - confirm the start output reports success. -- `pretest:php` runs `composer install --no-interaction --no-scripts` in `tests-cli`. Resolve installation errors before testing; see [Local development](../../../docs/local-development.md#check-a-change) for the tested commands. +- `pretest:php` starts the test environment and runs `composer install --no-interaction --no-scripts` in its `cli` container. Resolve installation errors before testing; see [Local development](../../../docs/local-development.md#check-a-change) for the tested commands. **Generated-code quirks (write the code right up front; these survive `composer phpcs:fix`):** - **Fully-qualify WP global classes** (`\WP_Error`, `\WP_REST_Request`, `\WP_REST_Response`) everywhere they appear - in code AND docblocks - with NO `use` statement for them. Reason: `composer phpcs:fix` force-qualifies `WP_Error` (Slevomat `FullyQualifiedExceptions` treats `*Error` as an exception) and then strips the now-unused imports, including docblock-only ones; PHPStan (scanning `inc/`) then reports `class.notFound`. Writing them fully-qualified avoids the fix -> phpstan round-trip. diff --git a/.gitignore b/.gitignore index 9bb53012..2e5c4dd8 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,7 @@ .env .env.local .wp-env.override.json +.wp-env.tests.override.json # Build assets/build/ diff --git a/.wp-env.json b/.wp-env.json index b5b64b6c..fe818e7e 100644 --- a/.wp-env.json +++ b/.wp-env.json @@ -3,12 +3,5 @@ "phpVersion": "8.2", "themes": [ "." ], "port": 5890, - "env": { - "tests": { - "port": 5891, - "config": { - "WP_DEBUG": true - } - } - } + "testsEnvironment": false } diff --git a/.wp-env.tests.json b/.wp-env.tests.json new file mode 100644 index 00000000..6ad6952f --- /dev/null +++ b/.wp-env.tests.json @@ -0,0 +1,10 @@ +{ + "core": null, + "phpVersion": "8.2", + "themes": [ "." ], + "port": 5891, + "testsEnvironment": false, + "config": { + "WP_DEBUG": true + } +} diff --git a/docs/internal/maintenance.md b/docs/internal/maintenance.md index 2c5edd74..d69b496b 100644 --- a/docs/internal/maintenance.md +++ b/docs/internal/maintenance.md @@ -35,7 +35,6 @@ Status recorded on **2026-09-15** for theme baseline `27860f1`, framework `v1.0. | Active procedure | Why it is needed | Retire when | | --- | --- | --- | | Run the explicit commands under [Checks](#checks). | The aggregate scripts include watch, fix, or recursive commands. | Both aggregates terminate and run only their intended checks without modifying files. | -| Apply the [test-only `WP_DEBUG` override](../local-development.md#check-a-change). | Logger tests require debug mode, which wp-env disables in its test environment. | The maintained test setup passes the logger tests without a per-project override. | | Log diagnostics instead of displaying them when checking login. | Early feature-description translation notices can interrupt login headers. | Translation timing is fixed and login succeeds with diagnostics displayed. | ### Record validation results diff --git a/docs/local-development.md b/docs/local-development.md index a70250fc..8166544d 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -9,10 +9,11 @@ npm run wp-env start npm run wp-env run cli -- wp theme activate acme-blog ``` -The development site is `http://localhost:5890`; the separate test site uses `http://localhost:5891`. Activation uses the mounted **folder name**, not the theme display name or text domain. When you finish, stop the environment with: +The development site is `http://localhost:5890`. PHP tests use a separate environment, defined in `.wp-env.tests.json`, on `http://localhost:5891` with its own database; `npm run test:php` starts it when needed. Activation uses the mounted **folder name**, not the theme display name or text domain. When you finish, stop the environments with: ```bash npm run wp-env stop +npm run wp-env -- stop --config=.wp-env.tests.json ``` For an existing local WordPress installation, use its normal startup and activation process instead, then run the theme-local commands from this directory. @@ -77,28 +78,16 @@ Use PHP compatible with the project's installed checks (PHP 8.2 is the wp-env ba npm run wp-env -- run cli --env-cwd=/var/www/html/wp-content/themes/acme-blog -- vendor/bin/phpcs ``` -With wp-env running, the theme's PHP test command runs inside `tests-cli`; its pretest hook installs Composer dependencies there without scripts. - -The wp-env test environment keeps `WP_DEBUG` disabled by default. The logger tests require it, so merge this test-only setting into `.wp-env.override.json` before running PHP tests: - -```json -{ - "env": { - "tests": { - "config": { "WP_DEBUG": true } - } - } -} -``` +The theme's PHP test command runs inside the test environment's `cli` container; its pretest hook starts that environment and installs Composer dependencies there without scripts. The test environment has `WP_DEBUG` on, which the logger tests need. ```bash npm run test:php ``` -For a focused PHP test after that setup: +For a focused PHP test: ```bash -npm run wp-env -- run tests-cli --env-cwd=/var/www/html/wp-content/themes/acme-blog -- vendor/bin/phpunit --filter AuthorBioTest +npm run wp-env -- run --config=.wp-env.tests.json cli --env-cwd=/var/www/html/wp-content/themes/acme-blog -- vendor/bin/phpunit --filter AuthorBioTest ``` Use the relevant test name if the example was removed. Keep smoke projects outside this repository so Jest does not discover another project's tests. Use the explicit commands above for a terminating review check; aggregate-script details belong in [maintenance](internal/maintenance.md#checks). @@ -117,10 +106,10 @@ Review visible behavior and checks before feature integration; make a separate f | Symptom | Check → next action | | --- | --- | -| wp-env cannot start | Run `docker info`; start Docker and retry if unavailable. For occupied ports, start with `WP_ENV_PORT=5892 WP_ENV_TESTS_PORT=5893 npm run wp-env start`. | +| wp-env cannot start | Run `docker info`; start Docker and retry if unavailable. For an occupied port, set `WP_ENV_PORT`, for example `WP_ENV_PORT=5892 npm run wp-env start` or `WP_ENV_PORT=5893 npm run test:php`. | | Frontend assets return 404 | Check `assets/build/`; run `npm run build:dev` and confirm the theme is active. | | CSS rebuilds but no live reload | Confirm local environment type, watcher, and BrowserSync port; see [HMR](hmr.md). | | HTTPS reload is blocked | Check that `WP_SSL_KEY` and `WP_SSL_CERT` point to trusted certificates for the site hostname; see [HMR](hmr.md). | | Site Editor ignores a template file edit | Check for a customized template saved in WordPress; review/reset that customization before testing the file version. | -| PHP tests cannot connect | Start wp-env and rerun `npm run test:php`; confirm the `tests-cli` environment is used. | +| PHP tests cannot connect | Start wp-env and rerun `npm run test:php`. | | New PHP feature does not load | Check namespace/path and `Main::CLASSES`; see [Development](../DEVELOPMENT.md#adding-a-new-class). | diff --git a/package.json b/package.json index 6c661bdd..9033317b 100644 --- a/package.json +++ b/package.json @@ -73,14 +73,14 @@ "lint:staged": "lint-staged", "pot": "composer run pot", "prepare": "npm run sync-ai", - "pretest:php": "wp-env run tests-cli --env-cwd=/var/www/html/wp-content/themes/${PWD##*/} composer install --no-interaction --no-scripts", + "pretest:php": "wp-env start --config=.wp-env.tests.json && wp-env run --config=.wp-env.tests.json cli --env-cwd=/var/www/html/wp-content/themes/${PWD##*/} composer install --no-interaction --no-scripts", "start": "npm-run-all --parallel start:assets start:blocks", "start:assets": "wp-scripts start --experimental-modules --config webpack.config.js", "start:blocks": "wp-scripts start --hot --experimental-modules --config ./webpack.blocks.config.js --webpack-src-dir=./src/blocks/ --output-path=./assets/build/blocks/", "test": "npm-run-all --parallel test:js test:php", "test:js": "wp-scripts test-unit-jest --config=tests/js/jest.config.js --passWithNoTests", "test:js:watch": "npm run test:js -- --watch", - "test:php": "wp-env run tests-cli --env-cwd=/var/www/html/wp-content/themes/${PWD##*/} composer exec 'phpunit --do-not-cache-result --verbose'", + "test:php": "wp-env run --config=.wp-env.tests.json cli --env-cwd=/var/www/html/wp-content/themes/${PWD##*/} composer exec 'phpunit --do-not-cache-result --verbose'", "wp-env": "wp-env" }, "overrides": { diff --git a/tests/js/dev-tools.test.js b/tests/js/dev-tools.test.js index 8aa8ea2e..b75ea662 100644 --- a/tests/js/dev-tools.test.js +++ b/tests/js/dev-tools.test.js @@ -39,7 +39,7 @@ const setup = (basePlugins, kind = 'theme') => { const root = fs.mkdtempSync(path.join(fixtures, 'dev-tools-')); const base = basePlugins ? { env: { development: { plugins: basePlugins } } } - : { core: null, themes: ['.'], env: { tests: { port: 5891 } } }; + : { core: null, themes: ['.'], port: 5890, testsEnvironment: false }; write(root, WP_ENV, `${JSON.stringify(base, null, '\t')}\n`); write(root, 'composer.json', '{\n\t"name": "acme/demo"\n}\n'); write(root, 'package.json', '{\n\t"name": "demo"\n}\n');