Skip to content

Add wp-env for local development#2917

Merged
donnchawp merged 20 commits intotrunkfrom
add/wp-env-local-dev
Mar 19, 2026
Merged

Add wp-env for local development#2917
donnchawp merged 20 commits intotrunkfrom
add/wp-env-local-dev

Conversation

@donnchawp
Copy link
Contributor

@donnchawp donnchawp commented Feb 24, 2026

Summary

  • Adds @wordpress/env as the local development environment for running WordPress and PHPUnit tests
  • Adds a Makefile wrapping wp-env and existing tooling (make install, make up, make test, make help)
  • Uses a separate wp-env config for the test environment to avoid deprecation — make up starts both a dev site (localhost:8888) and an isolated test site (localhost:8889)
  • Adds a blueprint.json for WordPress Playground demos
  • Updates tests/README.md, docs/CONTRIBUTING.md, and README.md with new workflow
  • Excludes dev config files from release builds

No changes to CI workflows, test bootstrap, or phpunit.xml.dist.

Test plan

  • Upgrade Node to 20+ (@wordpress/env 11.x requirement). Verify with node --version.
  • make install && make up — verify dev site at localhost:8888 and test site at localhost:8889
  • make test — verify PHPUnit runs in wp-env test container
  • make help — verify all targets listed
  • make build — verify .wp-env.json, blueprint.json, Makefile excluded from zip
  • Click Playground link above — verify plugin loads in browser

Plugin build for 43afc6a
📦 Download plugin zip
▶️ Open in playground

- Note make start prerequisite in make test help text
- Add .wp-env/ to .gitignore
- Exclude dev files from rsync in build script
- Pin @wordpress/env to exact version
* Add plugin name to Docker containers
Exits with an error if Node 20+ is not installed, preventing
confusing failures from wp-env.
- Add `make install` target that checks Node 20+ and runs npm install
- Disable testsEnvironment in .wp-env.json
- Add `make install` target that checks Node 20+ and runs npm install
- Disable testsEnvironment in .wp-env.json
Split the test environment into its own .wp-env.tests.json config
file with a dedicated port (8889), replacing the deprecated inline
env.tests approach. make up/down now manage both environments.
@donnchawp donnchawp self-assigned this Mar 19, 2026
@donnchawp donnchawp marked this pull request as ready for review March 19, 2026 11:26
@stephdau
Copy link
Member

I've updated the PR description to explain why there are two sites being spawned: port 8888 vs port 8889.

The plan (docs/plans/2026-02-24-wp-env-local-dev.md) specifies
`composer install` as part of the quick-start flow, but it was
missing from the Makefile install target. Without it, `make test`
fails because vendor/bin/phpunit is not available in the container.
@stephdau
Copy link
Member

TIL about zipinfo, while checking the zip out.

@stephdau
Copy link
Member

stephdau commented Mar 19, 2026

I've added composer install to the make install target.

With that in place, I was able to verify all of the test plan's items.

Copy link
Member

@stephdau stephdau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested the full test plan — all items pass (after one fix in bc2c901). A few issues found during review.

stephdau and others added 3 commits March 19, 2026 13:42
…ssing rsync exclude

- docs/CONTRIBUTING.md: make start → make install && make up
- tests/README.md: make start/stop → make up/down, use make install
- Makefile: destroy now tears down both dev and test instances
- build-plugin.sh: add .wp-env.tests.json to rsync excludes
- Use exclude.lst as single source for rsync and zip exclusions
- Add missing .husky, .psalm, .claude to exclude.lst
- Keep vendor excluded from rsync only (needed in final zip)
- Add node >=20.0.0 to package.json engines
- Add check_node to make up target
- Add .claude/ to .gitignore
- Fix tests/README.md to reference make test-up
@donnchawp donnchawp merged commit eaf25e2 into trunk Mar 19, 2026
11 checks passed
@donnchawp donnchawp deleted the add/wp-env-local-dev branch March 19, 2026 15:36
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