On Thursday, I hosted a little walkthrough on how to write a simple end-to-end test to make sure a specific piece of editor functionality that had broken in the past wouldn’t break again.

As GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ grows, the project sometimes experiences regressions: Features that used to work suddenly don’t anymore. In order to prevent these regressions from happening, contributors can write end-to-end (e2e) tests that cover a given piece of functionality and alert us when that functionality is broken. Combined with a Continuous Integration system such as GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ Actions, this is a very powerful tool, since it can notify a PR author that their PR might break something before they even merge that PR.

I’ve recently tried to keep more track of such regressions, and have started filing issues requesting e2e tests to cover them. In the hangout, I’ve picked one of these issues and demonstrated how to write an e2e test for it.

Some Implemenation Tips

Our e2e tests live in the packages/e2e-tests/ directory (corresponding to the @wordpress/e2e-tests npm package). The actual test flows are in the specs/ subdirectory. Note in particular the specs/editor/ directory, which contains end-to-end tests for the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor, grouped into blocks/, plugins/, and various/.

There is a number of useful high-level helper functions (such as createNewPost or openGlobalBlockInserter) in the @wordpress/e2e-test-utils package. Other than that, our e2e tests are based on the Jest JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. testing framework, and the Puppeteer browser automation suite (which basically allows us to control Chrome to run Gutenberg in it). The Puppeteer docs come in particularly handy when writing an end-to-end test and trying to implement a certain behavior.

To run the entire end-to-end test suite locally, use

npm run test-e2e

When working on an existing test, or developing a new one, it makes more sense to only run that test. E.g.:

npm run test-e2e -- packages/e2e-tests/specs/editor/blocks/gallery.test.js

(Note the double dash after test-e2e.)

Those commands will run Puppeteer in headless mode — you won’t see what’s actually happening in the browser. When working on a test, it is however handy to see what’s going on. You can run Puppeteer in interactive mode to that end:

npm run test-e2e -- packages/e2e-tests/specs/editor/blocks/gallery.test.js --puppeteer-interactive

In the hangout, I used the above tools and commands to write a basic test to make sure block preview was visible upon focusing a block in the block inserter. The resulting PR is https://github.com/WordPress/gutenberg/pull/29117.

Contribute!

Curious to write an end-to-end test yourself? Awesome! Why not pick an issue from the list and give it a try? If you get stuck or have any questions, don’t hesitate to ask in the #core-editor channel in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/..

If you’re less comfortable writing code, you can still help! If you see any PR or issue for a regressionregression A software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. that was discovered by a human rather than by an automated test, you can file an issue to request an end-to-end test for it. (See the aforementioned list for examples.)

#e2e-tests, #end-to-end-tests, #gutenberg, #hallwayhangout