Skip to content

Document why NodeJS is needed to run the tests #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mindctrl merged 10 commits into from
Oct 23, 2026
Merged

Document why NodeJS is needed to run the tests #347

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f234090
Document why NodeJS is needed to run the tests
iarif4u Oct 2, 2026
3632464
Rework the Node.js section after review
iarif4u Oct 2, 2026
148566c
Use the reviewed wording for the Node.js section
iarif4u Oct 6, 2026
4814a42
Name the ghcr.io download redirect domain
iarif4u Oct 7, 2026
3a9c1e6
Restore files deleted by mistake in 4814a42
iarif4u Oct 7, 2026
98bb2a5
Describe routes.php as a past case
iarif4u Oct 7, 2026
47af3de
Describe the development build that prepare.php runs now
iarif4u Oct 10, 2026
0340f74
Merge branch 'master' into docs/why-nodejs
kittenkamala Oct 14, 2026
3455650
Say that the development build still minifies
iarif4u Oct 15, 2026
3698405
Merge branch 'master' into docs/why-nodejs
kittenkamala Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,31 @@ nodejs --version
npm --version
```

### Why Node.js is needed

The PHPUnit test suite itself is written in PHP, but Node.js is required to prepare the WordPress source code before the tests can run.

The test runner uses `prepare.php` to set up a WordPress checkout and prepare it for PHPUnit. As part of this process, it runs the WordPress build tasks (`npm install && npm run build:dev`), including the Gutenberg build step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)). This is necessary because some files used by WordPress Core are generated or assembled as part of the build process rather than being available directly in the `wordpress-develop` checkout. These files were removed from version control in [changeset 61438](https://core.trac.wordpress.org/changeset/61438).

The Gutenberg build step:

1. Uses the Gutenberg version pinned by WordPress Core (`gutenberg.sha` in `package.json`).
2. Downloads the corresponding pre-built Gutenberg artifact from GitHub Container Registry (`ghcr.io`). The download redirects to `pkg-containers.githubusercontent.com`, so the server must be able to connect to both domains.
3. Copies the required Gutenberg files into the WordPress `src/` directory.
4. Makes those files available to the WordPress installation that PHPUnit loads during the test run.

The PHPUnit test suite loads WordPress from the `src/` directory. Therefore, these build steps must complete successfully before the tests can run. If the Gutenberg files have not been prepared, the test suite can fail while loading WordPress because required files are missing, as happened with `src/wp-includes/build/routes.php` in [#292](https://github.com/WordPress/phpunit-test-runner/issues/292).

This is why Node.js and npm are requirements for the test runner even though the tests themselves are written in PHP.

#### Versions

The Node.js and npm versions must be compatible with the versions specified in the `engines` and `devEngines` fields of `wordpress-develop/package.json`. Because of these fields and the repository's `engine-strict` npm setting, using an unsupported Node.js or npm version causes `npm install` to fail, for example with `npm error code EBADDEVENGINES`.

#### Development build

`prepare.php` runs the development build (`npm run build:dev`), the same build that WordPress Core's own PHPUnit workflow runs. It writes the built files into `src/`, which the tests load, and skips the production `build/` directory. [#244](https://github.com/WordPress/phpunit-test-runner/issues/244) tracks ways to make this step smaller.

### PHP Composer

_This is a simple example for Debian / Ubuntu._
Expand Down