Contents
Introduction
This section is intended to walk you through the process of setting up a basic local environment in your project that you can use for running unit tests and end-to-end tests. It assumes that you have a pre-existing project under version control, so certain foundational steps such as installing general prerequisites will not be a part of this guide. If you need help setting up a basic development environment for WooCommerce, take a look at the Getting Started section of the WooCommerce Extension Developer Guide.
Installing Testing Dependencies
Unit Testing
WooComWooCommerce uses PHPUnit for unit testing PHP. If you are using Composer to manage your project’s PHP dependencies, you can add PHPUnit as a development dependency by running the following command from your project root:
composer require --dev phpunit/phpunit ^7.5
Unit testing may also require a dedicated testing database. There are several different approaches, depending on your project’s structure and needs, but one option is to use the WP-CLI plugin integration test scaffolder, which will handle multiple tasks for you, including the setup for your database, unit test directory, and continuous integration (CI).
For JavaScript testing, Jest and React Testing Library are typically used in React-based WooCommerce projects like WooCommerce Admin. These can be installed in the normal way using those project’s documentation.
End-to-end Testing
There are several dedicated packages for end-to-end testing in WooCommerce that you can take advantage of in your extension. Below are instructions for adding these packages as development dependencies in your project, along with a brief explanation of what purpose each package serves.
Note: The WooCommerce End-to-end testing packages rely on Docker. Depending on your development workflow, this may or may not already be installed. If it isn’t, you can download the latest release from the Docker website.
Jest is a test sequencer that the subsequent dependencies will use for running end-to-end tests.
npm install --save-dev jest
WooCommerce E2E Environment is a reusable, Docker-based testing environment that you can use to run browser-based tests.
npm install --save-dev @woocommerce/e2e-environment
WooCommerce API is a package for interacting with WooCommerce installations. It includes an Axios API client as well as built-in repositories for interacting with core data types via CRUD operations.
npm install --save-dev @woocommerce/api
WooCommerce E2E Utils is a collection of utilities that simplify the process of writing test cases for end-to-end testing by encapsulating common browsing flows and API requests. It requires the @woocommerce/api package above as a peer dependency, so be sure to install both packages.
npm install --save-dev @woocommerce/e2e-utils
WooCommerce Core E2E Tests contains end-to-end tests for WooCommerce core’s critical flows. Running these tests will help ensure your extension doesn’t cause any unexpected issues with the core shopper and merchant experience in WooCommerce.
npm install --save-dev @woocommerce/e2e-core-tests
Note: Because it’s possible to have multiple concurrent installations of Node, WooCommerce and its supporting packages make use of .nvmrc files to explicitly specify which version of Node should be active when working with them. If your project doesn’t have one yet, you should create one now at your project root.
echo "v12" > .nvmrc
You can see which versions of Node are installed by running:
nvm ls
If version 12 is not installed, you can install it by running:
nvm install 12
Establishing a testing architecture
Once you have the underlying development dependencies added to your project, you should make sure your project architecture is set up to make the most of them.
As a general rule, your tests should live in a tests/ directory that sits at the root of your project. If you used the WP-CLI scaffolder above, it should have set up this directory for you already. If not, go ahead and create one now.
mkdir tests
It’s also a best practice to keep the types of tests in your tests/ directory organized according to their type. At a minimum, you should create directories for unit testing and end-to-end testing.
mkdir tests/unit && mkdir tests/e2e
You may find it helpful to further subdivide your high-level directories into more specific directories to help manage each type of testing. For instance, in addition to the tests themselves, your e2e directory may need to include additional files for managing the configuration of the Docker container that runs your test site or additional settings for Jest.
You can take a look at the WooCommerce End-to-End Boilerplate for an example of how to structure your end-to-end test directory. For an example of how you might organize unit tests, take a look at the tests/php directory in the WooCommerce Core repository.
Productivity Tip: You can also use the boilerplate repository in its entirety as a springboard for end-to-end testing in your project. There are instructions in its README file for adding it to an extension.
Typical Testing Workflows
Unit testing
Once you have test cases written and organized into the appropriate directories, you’ll typically run your extension’s suite of unit tests using PHPUnit’s Command-line Test Runner. Depending on the complexity of your testing needs, you may find it beneficial to use an XML configuration file to provide granular instructions to PHPUnit. You can take a look at WooCommerce Core’s phpunit.xml file to see an example of how you might set your own configuration up.
If you’re using a configuration file with PHPUnit, you’ll typically launch your unit test suite with the following command:
./vendor/bin/phpunit -c ./phpunit.xml
End-to-end Testing
The WooCommerce packages for end-to-end testing provide lots of helpful utilities for managing the Docker container where your tests run as well as running the tests themselves. As with unit testing, you’ll usually initiate your local environment’s end-to-end tests from the command line.
You can start and stop the Docker containers with the following commands:
npx wc-e2e docker:up npx wc-e2e docker:down
To run your end-to-end tests, you’ll use the following command:
npx wc-e2e test:e2e
These are just a few of the most commonly used commands that these packages provide. You can see a list of available commands by running:
npx wc-e2e
Productivity Tip: Use the scripts object in your extension’s package.json file to create aliases for frequently used testing commands. Take a look at WooCommerce Core’s scripts object for an example of what all is possible. You can read more about how NPM handles the scripts field in the NPM documentation.
Next Steps
Once you have your testing environment up and running in your extension, you can start writing your test cases. You may want to have a look at the different types of testing to get a better idea of what types of functionality each suite should test.
←
Back: Debugging Tools
→
Next: Critical Flows