Merge pull request #29399 from woocommerce/fix/29277

Update E2E readme files for release
This commit is contained in:
Ron Rennick 2021-03-24 16:09:34 -03:00 committed by GitHub
commit 6efa5b7ba4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 188 additions and 44 deletions

View File

@ -55,7 +55,7 @@ This section explains how e2e tests are working behind the scenes. These are not
### Test Environment
We recommend using Docker for running tests locally in order for the test environment to match the setup on Travis CI (where Docker is also used for running tests). [An official WordPress Docker image](https://github.com/docker-library/docs/blob/master/wordpress/README.md) is used to build the site. Once the site using the WP Docker image is built, the current WooCommerce dev branch is mapped into the `plugins` folder of that newly built test site.
We recommend using Docker for running tests locally in order for the test environment to match the setup on Github CI (where Docker is also used for running tests). [An official WordPress Docker image](https://github.com/docker-library/docs/blob/master/wordpress/README.md) is used to build the site. Once the site using the WP Docker image is built, the current WooCommerce dev branch is mapped into the `plugins` folder of that newly built test site.
### Test Variables
@ -77,13 +77,13 @@ The jest test sequencer uses the following test variables:
}
```
If you need to modify the port for your local test environment (eg. port is already in use), copy `tests/e2e/env/config/default.json` to `tests/e2e/config/default.json` and edit that copy. Only edit this file while your test container is `down`.
If you need to modify the port for your local test environment (eg. port is already in use), edit `tests/e2e/config/default.json`. Only edit this file while your test container is `down`.
### Jest test sequencer
[Jest](https://jestjs.io/) is being used to run e2e tests. Jest sequencer introduces tools that can be used to specify the order in which the tests are being run. In our case, they are being run in alphabetical order of the directories where tests are located. This way, tests in the new directory `activate-and-setup` will run first. By default, jest runs tests ordered by the time it takes to run the test (the test that takes longer to run will be run first, the test that takes less time to run will run last).
[Jest](https://jestjs.io/) is being used to run e2e tests. Jest sequencer introduces tools that can be used to specify the order in which the tests are being run. In our case, they are being run in alphabetical order of the directories where tests are located. This way, tests in the directory `activate-and-setup` will run first. By default, jest runs tests ordered by the time it takes to run the test (the test that takes longer to run will be run first, the test that takes less time to run will run last).
The Setup Wizard e2e test (located in `activate-and-setup` directory) will run first. This ensures that WooCommerce is active and the setup wizard has been completed. This is necessary because `docker:up` creates a brand new install of WordPress and WooCommerce.
The Setup Wizard e2e test runs first to ensure that WooCommerce is active and that the setup wizard has been completed. This is necessary because `docker:up` creates a brand new install of WordPress and WooCommerce.
### Chromium Download
@ -99,23 +99,25 @@ Puppeteer will still automatically download Chromium when needed.
### Prep work for running tests
Run the following in a terminal/command line window
- `cd` to the WooCommerce plugin folder
- `git checkout trunk` or checkout the branch where you need to run tests
- `git checkout trunk` (or the branch where you need to run tests)
- Run `nvm use`
- `nvm use`
- Run `npm install`
- `npm install`
- Run `composer install --no-dev`
- `composer install --no-dev`
- Run `npm run build:assets`
- `npm run build:assets`
- Run `npm install jest --global` (this only needs to be done once)
- `npm install jest --global` (this only needs to be done once)
- Run `npx wc-e2e docker:up` - it will build the test site using Docker.
- `npx wc-e2e docker:up` (this will build the test site using Docker)
- Run `docker ps` - to confirm that the Docker containers are running. You should see the log that looks similar to below indicating that everything had been built as expected:
- Use `docker ps` to confirm that the Docker containers are running. You should see a log similar to one below indicating that everything had been built as expected:
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
@ -305,7 +307,7 @@ describe( 'Merchant can create virtual product', () => {
} );
```
Next, you can start filling up each section with relevant functions (test building blocks). Note, that we have the `@woocommerce/e2e-utils` package where many reusable helper functions can be found for writing tests. For example, `flows.js` of `@woocommerce/e2e-utils` package contains `merchant` object that has `login` method. As a result, in the test it can be used as `await merchant.login();` so the first `it()` section of the test will become:
Next, you can start filling up each section with relevant functions (test building blocks). Note, that we have the `@woocommerce/e2e-utils` package where many reusable helper functions can be found for writing tests. For example, `merchant.js` of `@woocommerce/e2e-utils` package contains `merchant` object that has `login` method. As a result, in the test it can be used as `await merchant.login();` so the first `it()` section of the test will become:
```
it( 'merchant can log in', async () => {
@ -327,7 +329,7 @@ it( 'merchant can create virtual product', async () => {
You would then continue writing the test using utilities where possible.
Make sure to utilize the functions of the `@automattic/puppeteer-utils` package where possible. For example, if you need to wait for certain element to be ready to be clicked on and then click on it, you can use `waitAndClick()` function:
Make sure to utilize the functions of the `@automattic/puppeteer-utils` package where possible. For example, if you need to wait for a certain element to be ready to be clicked on and then click on it, you can use `waitAndClick()` function:
```
await waitAndClick( page, '#selector' );
@ -351,4 +353,6 @@ In the example above, you can see that `allows customer to see downloads` part o
## Debugging tests
The test sequencer (`npx wc-e2e test:e2e`) includes support for saving [screenshots on test errors](https://github.com/woocommerce/woocommerce/tree/trunk/tests/e2e/env#test-screenshots) which can be sent to a Slack channel via a [Slackbot](https://github.com/woocommerce/woocommerce/tree/trunk/tests/e2e/env#slackbot-setup).
For Puppeteer debugging, follow [Google's documentation](https://developers.google.com/web/tools/puppeteer/debugging).

View File

@ -49,11 +49,19 @@ httpClient.get( '/wc/v3/products' ).then( ( response ) => {
### Repositories
As a convenience utility we've created repositories for core data types that can simplify interacting with the API.
As a convenience utility we've created repositories for core data types that can simplify interacting with the API:
- `SimpleProduct`
- `ExternalProduct`
- `GroupedProduct`
- `VariableProduct`
- `ProductVariation`
- `Coupon`
These repositories provide CRUD methods for ease-of-use:
```javascript
import { SimpleProduct } from '@woocommerce/api';
import { HTTPClientFactory, SimpleProduct } from '@woocommerce/api';
// Prepare the HTTP client that will be consumed by the repository.
// This is necessary so that it can make requests to the REST API.
@ -68,5 +76,86 @@ const product = repository.create( { name: 'Simple Product', regularPrice: '9.99
// The response will be one of the models with structured properties and TypeScript support.
product.id;
```
#### Repository Methods
The following methods are available on all repositories:
- `create( {...properties} )` - Create a single object of the model type
- `delete( objectId )` - Delete a single object of the model type
- `list` - Retrieve a list of the existing objects of that model type
- `read( objectId )` - Read a single object of the model type
- `update( objectId, {...properties} )` - Update a single object of the model type
#### Child Repositories
`ProductVariation` is a child model repository. In child model repositories, each method requires the `parentId` as the first parameter:
```javascript
import { HTTPClientFactory, VariableProduct, ProductVariation } from '@woocommerce/api';
const httpClient = HTTPClientFactory.build( 'https://example.com' )
.withBasicAuth( 'username', 'password' )
.withIndexPermalinks()
.create();
const productRepository = VariableProduct.restRepository( httpClient );
const variationRepository = ProductVariation.restRepository( httpClient );
const product = await productRepository.create({
"name": "Variable Product with Three Attributes",
"defaultAttributes": [
{
"id": 0,
"name": "Size",
"option": "Medium"
},
{
"id": 0,
"name": "Colour",
"option": "Blue"
}
],
"attributes": [
{
"id": 0,
"name": "Colour",
"isVisibleOnProductPage": true,
"isForVariations": true,
"options": [
"Red",
"Green",
"Blue"
],
"sortOrder": 0
},
{
"id": 0,
"name": "Size",
"isVisibleOnProductPage": true,
"isForVariations": true,
"options": [
"Small",
"Medium",
"Large"
],
"sortOrder": 0
}
]
});
const variation = await variationRepository.create( product.id, {
"regularPrice": "19.99",
"attributes": [
{
"name": "Size",
"option": "Large"
},
{
"name": "Colour",
"option": "Red"
}
]
});
```

View File

@ -45,21 +45,22 @@ The functions to access the core tests are:
### Merchant
- `runMerchantTests` - Run all merchant tests
- `runCreateCouponTest` - Merchant can create coupon
- `runCreateOrderTest` - Merchant can create order
- `runAddNewShippingZoneTest` - Merchant can create shipping zones and let shopper test them
- `runAddSimpleProductTest` - Merchant can create a simple product
- `runAddVariableProductTest` - Merchant can create a variable product
- `runUpdateGeneralSettingsTest` - Merchant can update general settings
- `runProductSettingsTest` - Merchant can update product settings
- `runTaxSettingsTest` - Merchant can update tax settings
- `runCreateCouponTest` - Merchant can create coupon
- `runCreateOrderTest` - Merchant can create order
- `runMerchantOrdersCustomerPaymentPage` - Merchant can visit the customer payment page
- `runMerchantOrderEmailsTest` - Merchant can receive order emails and resend emails by Order Actions
- `runOrderStatusFilterTest` - Merchant can filter orders by order status
- `runOrderRefundTest` - Merchant can refund an order
- `runOrderApplyCouponTest` - Merchant can apply a coupon to an order
- `runOrderSearchingTest` - Merchant can search for order via different terms
- `runProductEditDetailsTest` - Merchant can edit an existing product
- `runProductSearchTest` - Merchant can search for a product and view it
- `runMerchantOrdersCustomerPaymentPage` - Merchant can visit the customer payment page
- `runOrderSearchingTest` - Merchant can search for order via different terms
- `runAddNewShippingZoneTest` - Merchant can create shipping zones and let shopper test them
- `runProductSettingsTest` - Merchant can update product settings
- `runTaxSettingsTest` - Merchant can update tax settings
- `runUpdateGeneralSettingsTest` - Merchant can update general settings
- `runMerchantOrderEmailsTest` - Merchant can receive order emails and resend emails by Order Actions
### Shopper
@ -70,13 +71,20 @@ The functions to access the core tests are:
- `runCheckoutApplyCouponsTest` - Shopper can use coupons on checkout
- `runCheckoutPageTest` - Shopper can complete checkout
- `runMyAccountPageTest` - Shopper can access my account page
- `runSingleProductPageTest` - Shopper can view single product page in many variations (simple, variable, grouped)
- `runMyAccountPayOrderTest` - Shopper can pay for his order in My Account
- `runCartApplyCouponsTest` - Shopper can apply coupons in the cart
- `runCheckoutApplyCouponsTest` - Shopper can apply coupons in the checkout
- `runMyAccountPayOrderTest` - Shopper can pay for their order in My Account
- `runProductBrowseSearchSortTest` - Shopper can browse, search & sort products
- `runSingleProductPageTest` - Shopper can view single product page in many variations (simple, variable, grouped)
- `runVariableProductUpdateTest` - Shopper can view and update variations on a variable product
### REST API
- `runApiTests` - Run all API tests
- `runExternalProductAPITest` - Can create, read, and delete an external product
- `runGroupedProductAPITest` - Can create, read, and delete a grouped product
- `runVariableProductAPITest` - Can create, read, and delete a variable product and its variations
- `runCouponApiTest` - Can create, read, and delete a coupon
## Contributing a new test
- In your branch create a new `example-test-name.test.js` under the `tests/e2e/core-tests/specs` folder.

View File

@ -2,13 +2,16 @@
echo "Initializing WooCommerce E2E"
wp plugin install woocommerce --activate
wp plugin activate woocommerce
wp theme install twentynineteen --activate
wp user create customer customer@woocommercecoree2etestsuite.com --user_pass=password --role=customer --path=/var/www/html
# we cannot create API keys for the API, so we using basic auth, this plugin allows that.
wp plugin install https://github.com/WP-API/Basic-Auth/archive/master.zip --activate
# install the WP Mail Logging plugin to test emails
wp plugin install wp-mail-logging --activate
echo "Updating to WordPress Nightly Point Release"
wp plugin install wordpress-beta-tester --activate

View File

@ -11,7 +11,7 @@ npm install jest --global
## Configuration
The `@woocommerce/e2e-environment` package exports configuration objects that can be consumed in JavaScript config files in your project. Additionally, it includes a hosting container for running tests and includes instructions for creating your Travis CI setup.
The `@woocommerce/e2e-environment` package exports configuration objects that can be consumed in JavaScript config files in your project. Additionally, it includes a basic hosting container for running tests and includes instructions for creating your Travis CI setup.
### Babel Config
@ -56,7 +56,7 @@ module.exports = useE2EEsLintConfig( {
### Jest Config
The E2E environment uses Jest as a test runner. Extending the base config is needed in order for Jest to run your project's test files.
The E2E environment uses Jest as a test runner. Extending the base config is necessary in order for Jest to run your project's test files.
```js
const path = require( 'path' );
@ -69,7 +69,7 @@ const jestConfig = useE2EJestConfig( {
module.exports = jestConfig;
```
**NOTE:** Your project's Jest config file is expected to be: `tests/e2e/config/jest.config.js`.
**NOTE:** Your project's Jest config file is: `tests/e2e/config/jest.config.js`.
#### Test Screenshots
@ -79,7 +79,7 @@ The test sequencer provides a screenshot function for test failures. To enable s
WC_E2E_SCREENSHOTS=1 npx wc-e2e test:e2e
```
Screenshots will be saved to `tests/e2e/screenshots`
Screenshots will be saved to `tests/e2e/screenshots`. This folder is cleared at the beginning of each test run.
### Jest Puppeteer Config
@ -125,11 +125,11 @@ module.exports = puppeteerConfig;
### Jest Setup
Jest provides setup and teardown functions similar to PHPUnit. The default setup and teardown is in [`tests/e2e/env/src/setup/jest.setup.js`](src/setup/jest.setup.js). Additional setup and teardown functions can be added to [`tests/e2e/config/jest.setup.js`](../config/jest.setup.js)
Jest provides [setup and teardown functions](https://jestjs.io/docs/setup-teardown) similar to PHPUnit. The default setup and teardown is in [`tests/e2e/env/src/setup/jest.setup.js`](src/setup/jest.setup.js). Additional setup and teardown functions can be added to [`tests/e2e/config/jest.setup.js`](../config/jest.setup.js)
### Container Setup
Depending on the project and testing scenario, the built in testing environment container might not be the best solution for testing. This could be local testing where there is already a testing container, a repository that isn't a plugin or theme and there are multiple folders mapped into the container, or similar. The `e2e-environment` container supports using either the built in container or an external container. See the the appropriate readme for details:
Depending on the project and testing scenario, the built in testing environment container might not be the best solution for testing. This could be local testing where there is already a testing container, a repository that isn't a plugin or theme and there are multiple folders mapped into the container, or similar. The `e2e-environment` test runner supports using either the built in container or an external container. See the appropriate readme for details:
- [Built In Container](https://github.com/woocommerce/woocommerce/tree/trunk/tests/e2e/env/builtin.md)
- [External Container](https://github.com/woocommerce/woocommerce/tree/trunk/tests/e2e/env/external.md)

View File

@ -34,6 +34,35 @@ echo "Initializing WooCommerce E2E"
wp plugin activate woocommerce
wp theme install twentynineteen --activate
```
### Adhoc Initialization
The container build script supports an initialization script parameter
```shell script
npx wc-e2e docker:up tests/e2e/docker/init-wp-beta.sh
```
This script updates WordPress to the latest nightly point release
```shell script
#!/bin/bash
echo "Initializing WooCommerce E2E"
wp plugin install woocommerce --activate
wp theme install twentynineteen --activate
wp user create customer customer@woocommercecoree2etestsuite.com --user_pass=password --role=customer --path=/var/www/html
# we cannot create API keys for the API, so we using basic auth, this plugin allows that.
wp plugin install https://github.com/WP-API/Basic-Auth/archive/master.zip --activate
echo "Updating to WordPress Nightly Point Release"
wp plugin install wordpress-beta-tester --activate
wp core check-update
```
### Container Configuration

View File

@ -66,7 +66,7 @@ version: ~> 1.0
script:
- npm install jest --global
# add your initialization script here
- npm explore @woocommerce/e2e-environment -- npm run test:e2e
- npx wc-e2e test:e2e
....

View File

@ -21,9 +21,7 @@ import {
describe( 'Cart page', () => {
beforeAll( async () => {
await merchant.login();
await createSimpleProduct();
await merchant.logout();
} );
it( 'should display no item in the cart', async () => {
@ -85,20 +83,33 @@ describe( 'Cart page', () => {
| Function | Parameters | Description |
|----------|------------|-------------|
| `addProductToOrder` | `orderId, productName` | adds a product to an order using the product search |
| `applyCoupon` | `couponName` | helper method which applies a coupon in cart or checkout |
| `clearAndFillInput` | `selector, value` | Replace the contents of an input with the passed value |
| `clickFilter` | `selector` | helper method that clicks on a list page filter |
| `clickTab` | `tabName` | Click on a WooCommerce -> Settings tab |
| `createCoupon` | `couponAmount` | creates a basic coupon. Default amount is 5. Returns the generated coupon code. |
| `clickUpdateOrder` | `noticeText`, `waitForSave` | Helper method to click the Update button on the order details page |
| `completeOnboardingWizard` | | completes the onboarding wizard with some default settings |
| `createCoupon` | `couponAmount`, `couponType` | creates a basic coupon. Default amount is 5. Default coupon type is fixed discount. Returns the generated coupon code. |
| `createGroupedProduct` | | creates a grouped product for the grouped product tests. Returns the product id. |
| `createSimpleOrder` | `status` | creates a basic order with the provided status string |
| `createSimpleProduct` | | creates the simple product configured in default.json. Returns the product id. |
| `createSimpleProductWithCategory` | `name`, `price`,`categoryName` | creates a simple product used passed values. Returns the product id. |
| `createVariableProduct` | | creates a variable product for the variable product tests. Returns the product id. |
| `deleteAllEmailLogs` | | deletes the emails generated by WP Mail Logging plugin |
| `evalAndClick` | `selector` | helper method that clicks an element inserted in the DOM by a script |
| `moveAllItemsToTrash` | | helper method that checks every item in a list page and moves them to the trash |
| `settingsPageSaveChanges` | | Save the current WooCommerce settings page |
| `permalinkSettingsPageSaveChanges` | | Save the current Permalink settings |
| `removeCoupon` | | helper method that removes a single coupon within cart or checkout |
| `selectOptionInSelect2` | `selector, value` | helper method that searchs for select2 type fields and select plus insert value inside |
| `selectOrderAction` | `action` | Helper method to select an order action in the `Order Actions` postbox |
| `setCheckbox` | `selector` | Check a checkbox |
| `unsetCheckbox` | `selector` | Uncheck a checkbox |
| `settingsPageSaveChanges` | | Save the current WooCommerce settings page |
| `uiUnblocked` | | Wait until the page is unblocked |
| `verifyPublishAndTrash` | `button, publishNotice, publishVerification, trashVerification` | Verify that an item can be published and trashed |
| `unsetCheckbox` | `selector` | Uncheck a checkbox |
| `verifyAndPublish` | `noticeText` | Verify that an item can be published |
| `verifyCheckboxIsSet` | `selector` | Verify that a checkbox is checked |
| `verifyCheckboxIsUnset` | `selector` | Verify that a checkbox is unchecked |
| `verifyPublishAndTrash` | `button, publishNotice, publishVerification, trashVerification` | Verify that an item can be published and trashed |
| `verifyValueOfInputField` | `selector, value` | Verify an input contains the passed value |
| `clickFilter` | `selector` | Click on a list page filter |
| `moveAllItemsToTrash` | | Moves all items in a list view to the Trash |
@ -113,4 +124,4 @@ describe( 'Cart page', () => {
### Test Utilities
As of version 0.1.2, all test utilities from [`@wordpress/e2e-test-utils`](https://www.npmjs.com/package/@wordpress/e2e-test-utils) are available through this package.
As of version 0.1.3, all test utilities from [`@wordpress/e2e-test-utils`](https://www.npmjs.com/package/@wordpress/e2e-test-utils) are available through this package.