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 2 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
2 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
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
22 changes: 22 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,28 @@ nodejs --version
npm --version
```

### Why Node.js is needed

The PHPUnit tests are written in PHP, but `prepare.php` needs Node.js and npm to prepare the WordPress checkout before the tests can run.

The tests load WordPress from `src/` (`ABSPATH` in `wp-tests-config.php`). Some files that WordPress loads from there are not in version control: they were removed in [changeset 61438](https://core.trac.wordpress.org/changeset/61438), and the build creates them.

`prepare.php` runs `npm install && npm run build`. For the tests, the important part is the Gutenberg step (`build:gutenberg` in the [Gruntfile](https://github.com/WordPress/wordpress-develop/blob/trunk/Gruntfile.js)):

1. It uses the Gutenberg version that WordPress pins in `package.json` (`gutenberg.sha`).
2. It downloads the pre-built Gutenberg artifact for that version from GitHub Container Registry (`ghcr.io`). The server must be able to connect to `ghcr.io`.
3. It copies the block editor PHP files, routes, blocks, scripts, styles and `theme.json` into `src/`.

If this step does not run, the tests fail while WordPress loads, for example on a missing `src/wp-includes/build/routes.php` ([#292](https://github.com/WordPress/phpunit-test-runner/issues/292)). This is why Node.js and npm are requirements, even though the tests are PHP.

Versions:

- Use the Node.js and npm versions in the `engines` field of `wordpress-develop/package.json`. Its `.npmrc` sets `engine-strict = true`, and `devEngines` also requires the npm version, so `npm install` stops on older versions.

Extra work:

- `npm run build` does more than PHPUnit needs. It also makes the production build in `build/` and minifies JavaScript and CSS. The tests do not use these files. WordPress Core runs its own PHPUnit workflow after `npm ci` and `npm run build:dev`. [#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