Skip to content

Split wp-env into dedicated QA and PHPUnit instances - #395

Merged
epeicher merged 1 commit into
trunkfrom
fix/wp-env-tests-environment-split
Jul 23, 2026
Merged

Split wp-env into dedicated QA and PHPUnit instances#395
epeicher merged 1 commit into
trunkfrom
fix/wp-env-tests-environment-split

Conversation

@epeicher

@epeicher epeicher commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator

What it does

Silences wp-env 11's deprecation warning on every wp-env start by migrating off the deprecated dual-environment mode. npm run env:start now brings up only the manual-QA instance (port 8890, 3 containers instead of 6), and PHPUnit runs in a dedicated instance defined by the new .wp-env.tests.json (port 8891), started with npm run env:start:tests.

Rationale

wp-env 11 deprecated starting the dev and tests environments from one config:

⚠ Warning: wp-env starts both development and tests environments by default.
This behavior is deprecated and will be removed in a future version.

The suggested "testsEnvironment": false alone would have broken npm run test:php, which ran inside the tests-cli container that flag removes. The upstream-recommended replacement is a separate config file per environment via the --config flag, which is what this PR does. As a bonus, QA state and test runs no longer share anything, and each stack is half the containers.

Implementation

  • .wp-env.json sets "testsEnvironment": false and drops testsPort; it is now purely the QA instance.
  • New .wp-env.tests.json defines the PHPUnit instance. It mirrors the old tests environment's WP_DEBUG/SCRIPT_DEBUG false defaults; without that, WordPress 7.0's wp_trigger_error() in wp_update_plugins() fires a notice under the dev-instance default of WP_DEBUG: true that the strict PHPUnit config turns into a test error (caught in pluginsWindowRegistration.php while verifying this migration).
  • test:php / test:php:install target the tests instance via wp-env run --config=.wp-env.tests.json cli; its cli container has WP_TESTS_DIR and a generated wp-tests-config.php just like tests-cli did. New env:start:tests / env:stop:tests / env:destroy:tests scripts manage it.
  • bin/setup-wp-env.sh drops the tests-cli Gutenberg setup. PHPUnit never needed it (the guidelines test registers its own stub surface), so the tests instance starts with no afterStart at all.
  • CI: the php job starts only the tests instance; the generated .wp-env.plugin-check.json also gets "testsEnvironment": false.
  • Docs (AGENTS.md, docs/DEVELOPMENT.md, tests/phpunit/bootstrap.php header) updated to the new flow. WP_ENV_TESTS_PORT is obsolete; worktrees now override each instance's port with WP_ENV_PORT per command, or via git-ignored .wp-env.override.json / .wp-env.tests.override.json.

Testing instructions

npm install               # needs @wordpress/env 11.x from the lockfile
npm run env:start:tests   # no deprecation warning, 3 containers
npm run test:php:install
npm run test:php          # 1329 tests, 3496 assertions, green
npm run env:start         # QA instance on :8890, also warning-free

Note: instances created by the old config keep their now-orphaned tests-* containers until you wp-env destroy them once.

Open WordPress Playground Preview

wp-env 11 deprecates starting the dev and tests environments from one
config and warns on every start. Set testsEnvironment: false in
.wp-env.json (QA, port 8890) and move PHPUnit to a dedicated instance
defined by .wp-env.tests.json (port 8891), targeted by the test:php*
scripts via --config. The tests config mirrors the old tests
environment's WP_DEBUG/SCRIPT_DEBUG=false defaults so wp_trigger_error()
notices don't fail the strict PHPUnit suite.
@epeicher
epeicher enabled auto-merge (squash) July 23, 2026 10:11
@epeicher
epeicher merged commit e723fd5 into trunk Jul 23, 2026
5 checks passed
@epeicher
epeicher deleted the fix/wp-env-tests-environment-split branch July 23, 2026 10:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants