test(php): run PHPUnit in a separate wp-env config

.claude/skills/scaffold/SKILL.md

@@ -203,9 +203,9 @@ Then report:
 
 **Test env (`wp-env`):**
 - Always use `npx wp-env` (or `node_modules/.bin/wp-env`), never bare `wp-env`.
-- 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:<port> -sTCP:LISTEN`).
-- `wp-env start` can flake on a transient image pull (TLS timeout); one retry is allowed, and exit 0 does not mean "up" - confirm `WordPress test site started` appears in the output.
-- `pretest:php` skips `composer install` when `vendor/` is already mounted; if `npm run test:php` still fails on it, run PHPUnit directly: `npx wp-env run tests-cli --env-cwd=wp-content/plugins/$(basename "$PWD") -- vendor/bin/phpunit -c phpunit.xml.dist`.
+- 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 in `.wp-env.tests.json` (find a free port with `lsof -nP -iTCP:<port> -sTCP:LISTEN`).
+- `wp-env start` can flake on a transient image pull (TLS timeout); one retry is allowed, and exit 0 does not mean "up" - confirm `WordPress development site started` appears in the output.
+- `pretest:php` skips `composer install` when `vendor/` is already mounted; if `npm run test:php` still fails on it, run PHPUnit directly: `npx wp-env run --config=.wp-env.tests.json cli --env-cwd=wp-content/plugins/$(basename "$PWD") -- vendor/bin/phpunit -c phpunit.xml.dist`.
 
 **Generated-code quirks (write the code right up front; these survive `composer format`):**
 - **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 format` force-qualifies `WP_Error` (Slevomat `FullyQualifiedExceptions` treats `*Error` as an exception) and then strips the now-unused imports, including docblock-only ones like `WP_REST_Request` (`UnusedUses` runs without `searchAnnotations`); PHPStan (scanning `inc/`) then reports `class.notFound` / `return.type` for `<Namespace>\WP_Error`. Writing them fully-qualified avoids the format -> phpstan round-trip.

.gitignore

@@ -37,6 +37,7 @@ assets/build/
 
 # WP ENV
 /.wp-env.override.json
+/.wp-env.tests.override.json
 
 # Tests & Coverage
 /coverage/

.wp-env.json

@@ -1,21 +1,7 @@
 {
   "core": null,
-  "env": {
-    "development": {
-      "plugins": [
-        "."
-      ]
-    },
-    "tests": {
-      "config": {
-        "WP_DEBUG": true
-      },
-      "themes": [
-        "https://downloads.wordpress.org/theme/twentytwentytwo.zip"
-      ],
-      "plugins": [
-        "."
-      ]
-    }
-  }
+  "plugins": [
+    "."
+  ],
+  "testsEnvironment": false
 }

.wp-env.tests.json

@@ -0,0 +1,14 @@
+{
+  "core": null,
+  "port": 8889,
+  "plugins": [
+    "."
+  ],
+  "themes": [
+    "https://downloads.wordpress.org/theme/twentytwentytwo.zip"
+  ],
+  "testsEnvironment": false,
+  "config": {
+    "WP_DEBUG": true
+  }
+}

docs/local-development.md

@@ -12,11 +12,11 @@ npm run wp-env run cli -- wp plugin activate acme-content-features
 | Site | URL | Used for |
 | --- | --- | --- |
 | Development | `http://localhost:8888` (`admin` / `password`) | Manual testing |
-| Tests | `http://localhost:8889` | The PHPUnit suite (`tests-cli` container) |
+| Tests | `http://localhost:8889` | The PHPUnit suite, in its own environment ([`.wp-env.tests.json`](../.wp-env.tests.json)); `npm run test:php` starts it |
 
-Both mount this directory as a plugin (see [`.wp-env.json`](../.wp-env.json)). Activation uses the **folder name**, not the plugin display name. Stop the environment with `npm run wp-env stop`.
+Both mount this directory as a plugin (see [`.wp-env.json`](../.wp-env.json) and [`.wp-env.tests.json`](../.wp-env.tests.json)), each with its own database. Activation uses the **folder name**, not the plugin display name. Stop the environments with `npm run wp-env stop` and `npm run wp-env -- stop --config=.wp-env.tests.json`.
 
-If those ports are taken, start on a free pair: `WP_ENV_PORT=8890 WP_ENV_TESTS_PORT=8891 npm run wp-env start`.
+If those ports are taken, set `WP_ENV_PORT`: `WP_ENV_PORT=8890 npm run wp-env start`, or `WP_ENV_PORT=8891 npm run test:php` for the test environment.
 
 For an existing WordPress installation (LocalWP, Lando, a site repository), use its own startup and activation, set `WP_HOST` in `.env.local` for live reload, and run the plugin-local commands below from this directory.
 
@@ -49,7 +49,7 @@ Copy `.env.local.example` to `.env.local` (gitignored) and set `WP_HOST` to your
 Run the focused test first, then the full set before opening a pull request.
 
 ```bash
-# PHP tests — run inside the wp-env tests container.
+# PHP tests — run inside the wp-env test environment (started on demand).
 npm run test:php -- --filter ShortcodesTest   # one test class
 npm run test:php                              # the whole suite
 
@@ -143,7 +143,7 @@ Run each with `-- --help` for the options your installed revision supports.
 
 | Symptom | Check and next action |
 | --- | --- |
-| `wp-env start` reports a port in use | Another site or the block dev server holds 8888/8889. Stop it or use `WP_ENV_PORT` / `WP_ENV_TESTS_PORT`. |
+| `wp-env start` reports a port in use | Another site or the block dev server holds 8888/8889. Stop it or set `WP_ENV_PORT` for the environment you start. |
 | `localhost:8888` shows a webpack 404 page instead of WordPress | `BLOCKS_DEV_SERVER_PORT` in `.env.local` is set to 8888, the `wp-env` site's port. Set it back to 8886 (or another free port) and restart `npm start`. |
 | `npm start` fails with `EADDRINUSE` | Another dev server already holds the block dev server's port; stop it or set `BLOCKS_DEV_SERVER_PORT` in `.env.local`. |
 | `npm run test:php` cannot connect | The environment is not running. Run `npm run wp-env start` and retry. |

package.json

@@ -97,10 +97,10 @@
     "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",
-    "pretest:php": "wp-env run tests-cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- sh -c 'test -f vendor/autoload.php || composer install --no-interaction'",
-    "test:php": "wp-env run tests-cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- vendor/bin/phpunit -c phpunit.xml.dist",
-    "pretest:php:coverage": "echo \"\\e[1m\\e[32mMake sure you have run npm run wp-env start -- --xdebug=coverage before using this command\\e[0m\" && wp-env run tests-cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- sh -c 'test -f vendor/autoload.php || composer install --no-interaction'",
-    "test:php:coverage": "wp-env run tests-cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- vendor/bin/phpunit -c phpunit.xml.dist --coverage-html coverage",
+    "pretest:php": "wp-env start --config=.wp-env.tests.json && wp-env run --config=.wp-env.tests.json cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- sh -c 'test -f vendor/autoload.php || composer install --no-interaction'",
+    "test:php": "wp-env run --config=.wp-env.tests.json cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- vendor/bin/phpunit -c phpunit.xml.dist",
+    "pretest:php:coverage": "echo \"\\e[1m\\e[32mMake sure you have run npm run wp-env start -- --config=.wp-env.tests.json --xdebug=coverage before using this command\\e[0m\" && wp-env run --config=.wp-env.tests.json cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- sh -c 'test -f vendor/autoload.php || composer install --no-interaction'",
+    "test:php:coverage": "wp-env run --config=.wp-env.tests.json cli --env-cwd=wp-content/plugins/$(basename \"$PWD\") -- vendor/bin/phpunit -c phpunit.xml.dist --coverage-html coverage",
     "posttest:php:coverage": "echo \"\\e[1m\\e[32mIf you have run this command with xdbug coverage enabled, you can view the coverage report at /coverage path\\e[0m\"",
     "wp-env": "wp-env",
     "pot": "composer run pot"

tests/js/scaffold-config.test.js

@@ -132,6 +132,28 @@ describe( 'dev-tools feature', () => {
 			expect( readJson( root, OVERRIDE ).env.tests ).toBeUndefined();
 		} );
 
+		it( 'reads a top-level plugins list from the committed config', () => {
+			write(
+				root,
+				WP_ENV,
+				`${ JSON.stringify(
+					{
+						core: null,
+						plugins: [ '.', 'team-plugin.zip' ],
+						testsEnvironment: false,
+					},
+					null,
+					'\t'
+				) }\n`
+			);
+
+			feature.onEnable( api );
+
+			expect(
+				readJson( root, OVERRIDE ).env.development.plugins
+			).toEqual( [ '.', 'team-plugin.zip', QM, ADAPTER ] );
+		} );
+
 		it( 'is idempotent -- no duplicate repository or plugin entries', () => {
 			feature.onEnable( api );
 			const composer = fs.readFileSync(