Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/doc/development/testing_guide/contract/consumer_tests.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/testing_guide/contract/consumer_tests.md')
-rw-r--r--doc/development/testing_guide/contract/consumer_tests.md113
1 files changed, 60 insertions, 53 deletions
diff --git a/doc/development/testing_guide/contract/consumer_tests.md b/doc/development/testing_guide/contract/consumer_tests.md
index df7c9ee0abd..46f4f446ad9 100644
--- a/doc/development/testing_guide/contract/consumer_tests.md
+++ b/doc/development/testing_guide/contract/consumer_tests.md
@@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Writing consumer tests
-This tutorial guides you through writing a consumer test from scratch. To start, the consumer tests are written using [`jest-pact`](https://github.com/pact-foundation/jest-pact) that builds on top of [`pact-js`](https://github.com/pact-foundation/pact-js). This tutorial shows you how to write a consumer test for the `/discussions.json` endpoint, which is actually `/:namespace_name/:project_name/-/merge_requests/:id/discussions.json`.
+This tutorial guides you through writing a consumer test from scratch. To start, the consumer tests are written using [`jest-pact`](https://github.com/pact-foundation/jest-pact) that builds on top of [`pact-js`](https://github.com/pact-foundation/pact-js). This tutorial shows you how to write a consumer test for the `/discussions.json` REST API endpoint, which is actually `/:namespace_name/:project_name/-/merge_requests/:id/discussions.json`. For an example of a GraphQL consumer test, see [`spec/contracts/consumer/specs/project/pipeline/show.spec.js`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/consumer/specs/project/pipeline/show.spec.js).
## Create the skeleton
@@ -24,7 +24,7 @@ To learn more about how the contract test directory is structured, see the contr
The Pact consumer test is defined through the `pactWith` function that takes `PactOptions` and the `PactFn`.
```javascript
-const { pactWith } = require('jest-pact');
+import { pactWith } from 'jest-pact';
pactWith(PactOptions, PactFn);
```
@@ -34,7 +34,7 @@ pactWith(PactOptions, PactFn);
`PactOptions` with `jest-pact` introduces [additional options](https://github.com/pact-foundation/jest-pact/blob/dce370c1ab4b7cb5dff12c4b62246dc229c53d0e/README.md#defaults) that build on top of the ones [provided in `pact-js`](https://github.com/pact-foundation/pact-js#constructor). In most cases, you define the `consumer`, `provider`, `log`, and `dir` options for these tests.
```javascript
-const { pactWith } = require('jest-pact');
+import { pactWith } from 'jest-pact';
pactWith(
{
@@ -54,7 +54,7 @@ To learn more about how to name the consumers and providers, see contract testin
The `PactFn` is where your tests are defined. This is where you set up the mock provider and where you can use the standard Jest methods like [`Jest.describe`](https://jestjs.io/docs/api#describename-fn), [`Jest.beforeEach`](https://jestjs.io/docs/api#beforeeachfn-timeout), and [`Jest.it`](https://jestjs.io/docs/api#testname-fn-timeout). For more information, see [https://jestjs.io/docs/api](https://jestjs.io/docs/api).
```javascript
-const { pactWith } = require('jest-pact');
+import { pactWith } from 'jest-pact';
pactWith(
{
@@ -70,7 +70,7 @@ pactWith(
});
- it('return a successful body', () => {
+ it('return a successful body', async () => {
});
});
@@ -92,8 +92,8 @@ For this tutorial, define four attributes for the `Interaction`:
After you define the `Interaction`, add that interaction to the mock provider by calling `addInteraction`.
```javascript
-const { pactWith } = require('jest-pact');
-const { Matchers } = require('@pact-foundation/pact');
+import { pactWith } from 'jest-pact';
+import { Matchers } from '@pact-foundation/pact';
pactWith(
{
@@ -132,7 +132,7 @@ pactWith(
provider.addInteraction(interaction);
});
- it('return a successful body', () => {
+ it('return a successful body', async () => {
});
});
@@ -142,38 +142,36 @@ pactWith(
### Response body `Matchers`
-Notice how we use `Matchers` in the `body` of the expected response. This allows us to be flexible enough to accept different values but still be strict enough to distinguish between valid and invalid values. We must ensure that we have a tight definition that is neither too strict nor too lax. Read more about the [different types of `Matchers`](https://github.com/pact-foundation/pact-js#using-the-v3-matching-rules).
+Notice how we use `Matchers` in the `body` of the expected response. This allows us to be flexible enough to accept different values but still be strict enough to distinguish between valid and invalid values. We must ensure that we have a tight definition that is neither too strict nor too lax. Read more about the [different types of `Matchers`](https://github.com/pact-foundation/pact-js/blob/master/docs/matching.md). We are currently using the V2 matching rules.
## Write the test
After the mock provider is set up, you can write the test. For this test, you make a request and expect a particular response.
-First, set up the client that makes the API request. To do that, create `spec/contracts/consumer/endpoints/project/merge_requests.js` and add the following API request.
+First, set up the client that makes the API request. To do that, create `spec/contracts/consumer/resources/api/project/merge_requests.js` and add the following API request. If the endpoint is a GraphQL, then we create it under `spec/contracts/consumer/resources/graphql` instead.
```javascript
-const axios = require('axios');
-
-exports.getDiscussions = (endpoint) => {
- const url = endpoint.url;
-
- return axios
- .request({
- method: 'GET',
- baseURL: url,
- url: '/gitlab-org/gitlab-qa/-/merge_requests/1/discussions.json',
- headers: { Accept: '*/*' },
- })
- .then((response) => response.data);
-};
+import axios from 'axios';
+
+export async function getDiscussions(endpoint) {
+ const { url } = endpoint;
+
+ return axios({
+ method: 'GET',
+ baseURL: url,
+ url: '/gitlab-org/gitlab-qa/-/merge_requests/1/discussions.json',
+ headers: { Accept: '*/*' },
+ })
+}
```
After that's set up, import it to the test file and call it to make the request. Then, you can make the request and define your expectations.
```javascript
-const { pactWith } = require('jest-pact');
-const { Matchers } = require('@pact-foundation/pact');
+import { pactWith } from 'jest-pact';
+import { Matchers } from '@pact-foundation/pact';
-const { getDiscussions } = require('../endpoints/project/merge_requests');
+import { getDiscussions } from '../../../resources/api/project/merge_requests';
pactWith(
{
@@ -211,17 +209,17 @@ pactWith(
};
});
- it('return a successful body', () => {
- return getDiscussions({
+ it('return a successful body', async () => {
+ const discussions = await getDiscussions({
url: provider.mockService.baseUrl,
- }).then((discussions) => {
- expect(discussions).toEqual(Matchers.eachLike({
- id: 'fd73763cbcbf7b29eb8765d969a38f7d735e222a',
- project_id: 6954442,
- ...
- resolved: true
- }));
});
+
+ expect(discussions).toEqual(Matchers.eachLike({
+ id: 'fd73763cbcbf7b29eb8765d969a38f7d735e222a',
+ project_id: 6954442,
+ ...
+ resolved: true
+ }));
});
});
},
@@ -237,7 +235,7 @@ As you may have noticed, the request and response definitions can get large. Thi
Create a file under `spec/contracts/consumer/fixtures/project/merge_request` called `discussions.fixture.js` where you will place the `request` and `response` definitions.
```javascript
-const { Matchers } = require('@pact-foundation/pact');
+import { Matchers } from '@pact-foundation/pact';
const body = Matchers.eachLike({
id: Matchers.string('fd73763cbcbf7b29eb8765d969a38f7d735e222a'),
@@ -254,11 +252,15 @@ const Discussions = {
headers: {
'Content-Type': 'application/json; charset=utf-8',
},
- body: body,
+ body,
},
- request: {
+ scenario: {
+ state: 'a merge request with discussions exists',
uponReceiving: 'a request for discussions',
+ },
+
+ request: {
withRequest: {
method: 'GET',
path: '/gitlab-org/gitlab-qa/-/merge_requests/1/discussions.json',
@@ -275,36 +277,41 @@ exports.Discussions = Discussions;
With all of that moved to the `fixture`, you can simplify the test to the following:
```javascript
-const { pactWith } = require('jest-pact');
+import { pactWith } from 'jest-pact';
+
+import { Discussions } from '../../../fixtures/project/merge_request/discussions.fixture';
+import { getDiscussions } from '../../../resources/api/project/merge_requests';
-const { Discussions } = require('../fixtures/discussions.fixture');
-const { getDiscussions } = require('../endpoints/project/merge_requests');
+const CONSUMER_NAME = 'MergeRequest#show';
+const PROVIDER_NAME = 'Merge Request Discussions Endpoint';
+const CONSUMER_LOG = '../logs/consumer.log';
+const CONTRACT_DIR = '../contracts/project/merge_request/show';
pactWith(
{
- consumer: 'MergeRequest#show',
- provider: 'Merge Request Discussions Endpoint',
- log: '../logs/consumer.log',
- dir: '../contracts/project/merge_request/show',
+ consumer: CONSUMER_NAME,
+ provider: PROVIDER_NAME,
+ log: CONSUMER_LOG,
+ dir: CONTRACT_DIR,
},
(provider) => {
- describe('Merge Request Discussions Endpoint', () => {
+ describe(PROVIDER_NAME, () => {
beforeEach(() => {
const interaction = {
- state: 'a merge request with discussions exists',
+ ...Discussions.scenario,
...Discussions.request,
willRespondWith: Discussions.success,
};
- return provider.addInteraction(interaction);
+ provider.addInteraction(interaction);
});
- it('return a successful body', () => {
- return getDiscussions({
+ it('return a successful body', async () => {
+ const discussions = await getDiscussions({
url: provider.mockService.baseUrl,
- }).then((discussions) => {
- expect(discussions).toEqual(Discussions.body);
});
+
+ expect(discussions).toEqual(Discussions.body);
});
});
},
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-14 04:52:09 +0300