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

Open
iarif4u wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Document why NodeJS is needed to run the tests #347

Changes from all commits
Commits
Show all changes
6 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
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 @@ -130,6 +130,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`), 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`.

#### Extra work

`npm run build` performs more work than is required by PHPUnit. The complete WordPress build also creates the production `build/` directory and performs tasks such as JavaScript and CSS minification. The PHPUnit tests primarily need the files prepared in `src/`. The additional build work is currently part of the preparation process. WordPress Core's own PHPUnit workflow runs `npm ci` and `npm run build:dev` instead, and [#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