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

# 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:8084 USER_KEY=admin USER_SECRET=password npm run test: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 test: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 test: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 test -- --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/).