woocommerce/packages/js/api-core-tests/README.md

163 lines
6.0 KiB
Markdown

# WooCommerce Core API Test Suite
This package contains automated API tests for WooCommerce.
## Environment variables
Before running the tests, the following environment variables need to be configured as shown in `.env.example`:
```
# Your site's base URL, not including a trailing slash
BASE_URL="https://mysite.com"
# The admin user's username or generated consumer key
USER_KEY=""
# The admin user's password or generated consumer secret
USER_SECRET=""
```
For local setup, create a `.env` file in this folder with the three required values described above.
Alternatively, these values can be passed in via the command line. For example:
```shell
BASE_URL=http://localhost:8086 USER_KEY=admin USER_SECRET=password npm run e2e:api
```
When using a username and password combination instead of a consumer secret and consumer key, make sure to have the [JSON Basic Authentication plugin](https://github.com/WP-API/Basic-Auth) installed and activated on the test site.
For more information about authentication with the WooCommerce API, please see the [Authentication](https://woocommerce.github.io/woocommerce-rest-api-docs/?javascript#authentication) section in the WooCommerce REST API documentation.
### Optional variables
The following optional variables can be set in your local `.env` file:
* `VERBOSE`: determine whether each individual test should be reported during the run.
* `USE_INDEX_PERMALINKS`: determine whether to use index permalinks (`?p=123`) for the API route.
## Running tests
### Test API connection
To verify that everything is configured correctly, the following test script is available:
```shell
npm run e2e:hello
```
This tests connectivity to the API by validating connection to the following:
* A non-authenticated endpoint: [Index](https://woocommerce.github.io/woocommerce-rest-api-docs/?javascript#index)
* An endpoint requiring authentication: [System status properties](https://woocommerce.github.io/woocommerce-rest-api-docs/?javascript#system-status-properties)
### Run all tests
To run all of the API tests, you can use the following command:
```shell
npm run e2e:api
```
### Running groups of tests
To run a specific group of tests, you can use the `npm test -- --group=` command and pass in the group's name you want to run.
For example, if you wanted to only run the orders API tests, you can use the following:
```shell
npm e2e -- --group=orders
```
Alternatively, you can use `jest` to run test groups:
```shell
jest --group=api
```
## Writing tests
### Conventions
1. All tests should be placed in the `tests` directory.
1. Always provide a JS doc in all tests, and tag them with `@group`. See the [Test groups](#test-groups) section for more info on grouping tests.
1. Use functions in the `data` folder when generating test data instead of constructing them from scratch within the test.
1. Use functions in the `endpoints` folder to send requests instead of directly using SuperTest's `request()` function.
1. Use `describe.each()` or `it.each()` when writing repetitive tests.
1. Always clean up all test data generated by the tests.
### Test groups
This package makes use of the `jest-runner-groups` package, which allows grouping tests together around semantic groups (such as `orders` API calls, or `coupons` API calls) to make running test suites more granular.
Before the `describe()` statement, add in a doc block containing the desired groups:
```javascript
/**
* Tests for the WooCommerce API.
*
* @group api
* @group endpoint
*
*/
describe('', () => {
it('', async () => {});
});
```
The `api` group should be included on all tests that should be run with the rest of the test suite. Groups can also contain a path, such as `orders/delete`.
For more information on how groups work, please refer to the [`jest-runner-groups` documentation](https://www.npmjs.com/package/jest-runner-groups).
## Using query strings
For tests that use query strings, these can be passed into the `getRequest()` method using an object of one or more key value pairs:
```javascript
const { getRequest } = require('./utils/request');
const queryString = {
dates_are_gmt: true,
after: '2021-05-13T19:00:00',
before: '2021-05-13T22:00:00'
};
const response = await getRequest('/orders', queryString);
```
## Creating test data
Most of the time, test data would be in the form of a request payload. Instead of building them from scratch inside the test, create a test data file inside the `data` directory. Create a model of the request payload within that file, and export it as an object or a function that generates this object.
Afterwards, make sure to add the test data file to the `data/index.js` file.
This way, the test data would be decoupled from the test itself, allowing for easier test data management, and more readable tests.
## Creating endpoint functions
All functions for sending requests to endpoints should be placed in the `endpoints` directory.
Newly created files should be added to the `endpoints/index.js` file.
## Debugging tests
You can make use of the REST API log plugin to see how requests are being made, and check the request payload, response, and more.
[REST API Log](https://wordpress.org/plugins/wp-rest-api-log/)
## Generate a Postman Collection
This package also allows generating a `collection.json` file using the test data in this package. This file can be imported into Postman and other REST clients that support the Postman v2 collection. To generate this file, run:
```
npm run make:collection
```
This will output a `collection.json` file in this directory.
## Resources
This package makes use of the [SuperTest HTTP assertion package](https://www.npmjs.com/package/supertest). For more information on the `response` properties that are available can be found in the [SuperAgent documentation](https://visionmedia.github.io/superagent/#response-properties).
For the list of WooCommerce API endpoints, expected responses, and more, please see the [WooCommerce REST API Documentation](https://woocommerce.github.io/woocommerce-rest-api-docs/).