The purpose of e2e (end to end) testing is to simulate the real user scenario and validate the different flows. In concrete, running an e2e test involves setting up a production-like environment, opening a browser and interacting with the application as it was a real user manipulating the interface. This is one of the best testing methodologies to avoid regressions.
Gutenberg has been successfully using this kind of tests for some time now. Reusable packages to setup and run e2e tests have been built in the repository. Starting today, this setup was brought into WordPress and included in our CI pipeline.
Local Environment
The e2e tests require a production-like environment to run. The current setup relies on Docker to provide a built-in environment.
You can run the environment locally on your own WordPress Core clone.
First, make sure you have Docker installed (instructions on this link).
Then, you should be able to run the environment by running these commands on your own WordPress repository clone.
npm install
npm run env:start
This command will make sure you have the right node/npm versions installed, triggers docker containers for your web and mysql servers and installs WordPress using the build folder.
You can also reset the environment with a testing website using:
npm run env:reset-site
You should be able to access your environment on http://localhost:8889. The default username is admin and the password is password.
Running the e2e tests
Once your environment ready, you can launch the e2e tests suite by running:
npm run test:e2e
This will run the test suite using a headless browser. For debugging purpose, you might want to follow the test visually. You can do so by running the tests in an interactive mode.
npm run test:e2e -- --puppeteer-interactive
you can also run a given test file separately
npm run test:e2e tests/e2e/specs/hello.test.js
Writing e2e tests
The e2e tests live in the tests/e2e/specs folder and should be follow the following naming format my-file.test.js.
The e2e tests use Jest as a testing/asserting framework, and rely on Puppeteer to communicate with the browser.
A typical e2e test looks like that:
// Load utilities from the e2e-test-utils package.
import { visitAdminPage } from '@wordpress/e2e-test-utils';
// Name of the test suite.
describe( 'Hello World', () => {
// Flow being tested.
// Ideally each flow is independent and can be run separately.
it( 'Should load properly', async () => {
// Navigate the admin and performs tasks
// Use Puppeteer APIs to interacte with mouse, keyboard...
await visitAdminPage( '/' );
// Assertions
const nodes = await page.$x(
'//h2[contains(text(), "Welcome to WordPress!")]'
);
expect( nodes.length ).not.toEqual( 0 );
} );
} );
e2e test utilities
When writing e2e test, you’ll notice that some actions are repeated across tests. Things like:
- Login into the dashboard
- Go to a page
- Activate/Deactivate a plugin
- Create a new post
- Create a dummy page
A number of these utilities is already available in the @wordpress/e2e-test-utils package, in the Gutenberg repository. You’re encouraged to use and share reusable utilities across tests.
In addition to these utilities, you can checkout the Puppeteer API Docs to manipulate the browser.
We need you
Please give it a try, the more we add tests, the more stable our releases will be. If you need support, ask in the #core-js Slack channel.
#core-editor, #core-js, #testing
