JavaScript Testing <!-- omit in toc -->

Table of contents <!-- omit in toc -->

• How to run JavaScript unit tests
• How to run end-to-end tests
  • Debugging e2e tests using generated reports
  • WordPress versions and end-to-end tests suites

Tests for JavaScript in the Blocks plugin are powered by Jest. The Blocks plugin follows the same patterns as Gutenberg, therefore for instructions on writing tests you can refer to this page in the Gutenberg Handbook.

We have two kinds of JavaScript tests:

• JavaScript unit tests - test APIs, hooks, library functionality that we use to build blocks or expose to plugin authors.
• End-to-end (e2e) tests - test blocks from the user interface.

These tests are all run automatically on open PRs by Travis CI.

All the following tests require that the dependencies are installed (npm install composer install). Ensure you've followed the Getting Started Guide to set up node and other dependencies before running any tests.

How to run JavaScript unit tests

Unit tests are implemented near the code they test, in *.test.js files.

Use the following command to run the unit tests:

npm run test

The test scripts use wp-scripts to run jest for component and unit testing.

Additionally,

• test:update updates the snapshot tests for components, used if you change a component that has tests attached.
• test:watch keeps watch of files and automatically re-runs tests when things change.

How to run end-to-end tests

The Blocks end-to-end tests were merged into the WooCommerce Core e2e suite. They now live at plugins/woocommerce/tests/e2e/tests/blocks/ and run through the shared Playwright config (tests/e2e/playwright.config.ts, project blocks-chromium).

From plugins/woocommerce:

# Start wp-env, run the Blocks test-env setup, and install the browser
pnpm env:start:blocks

# Run the Blocks e2e suite
pnpm test:e2e:blocks

For the full setup and available environments, see the core e2e documentation.

Debugging e2e tests using generated reports

When e2e test suites are run in a GitHub automation, a report is generated automatically for every suite that failed. This can be a useful tool to debug failing tests, as it provides a visual way to inspect the tests that failed and, additionally, it includes some screenshots.

To access the reports, you should go to the Details of a failed e2e test suite:

From there, you can open the Summary of the e2e test jobs:

From the Summary page, if you scroll down, you can download the report of each test suite that failed:

That will download a ZIP that you can open in your browser locally.

WordPress versions and end-to-end tests suites

Currently, we only run e2e tests with the most recent version of WordPress. We also have the infrastructure in place to run e2e tests with the most recent version of WordPress with Gutenberg installed, but it's currently disabled.

When preparing for a new version of WordPress, it's a good practice to search for conditions in our tests that check for specific WP versions (with the variable WP_VERSION).

We're hiring! Come work with us!

🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.