diff options
Diffstat (limited to 'doc/development/testing_guide/contract')
| -rw-r--r-- | doc/development/testing_guide/contract/consumer_tests.md | 44 | ||||
| -rw-r--r-- | doc/development/testing_guide/contract/index.md | 26 | ||||
| -rw-r--r-- | doc/development/testing_guide/contract/provider_tests.md | 52 |
3 files changed, 68 insertions, 54 deletions
diff --git a/doc/development/testing_guide/contract/consumer_tests.md b/doc/development/testing_guide/contract/consumer_tests.md index 9c72e6835bd..39cc34d6153 100644 --- a/doc/development/testing_guide/contract/consumer_tests.md +++ b/doc/development/testing_guide/contract/consumer_tests.md @@ -6,11 +6,11 @@ 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` 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). +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 `/:namespace_name/:project_name/-/merge_requests/:id/discussions.json`, that is called in the `MergeRequests#show` page. For an example of a GraphQL consumer test, see [`spec/contracts/consumer/specs/project/pipelines/show.spec.js`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/consumer/specs/project/pipelines/show.spec.js). ## Create the skeleton -Start by creating the skeleton of a consumer test. Create a file under `spec/contracts/consumer/specs/project/merge_request` called `discussions.spec.js`. +Start by creating the skeleton of a consumer test. Since this is for a request in the `MergeRequests#show` page, under `spec/contracts/consumer/specs/project/merge_requests`, create a file called `show.spec.js`. Then, populate it with the following function and parameters: - [`pactWith`](#the-pactwith-function) @@ -38,10 +38,10 @@ import { pactWith } from 'jest-pact'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts/project/merge_request/show', + dir: '../contracts/project/merge_requests/show', }, PactFn ); @@ -58,14 +58,14 @@ import { pactWith } from 'jest-pact'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts', + dir: '../contracts/project/merge_requests/show', }, (provider) => { - describe('Merge Request Discussions Endpoint', () => { + describe('GET discussions', () => { beforeEach(() => { }); @@ -97,14 +97,14 @@ import { Matchers } from '@pact-foundation/pact'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts/project/merge_request/show', + dir: '../contracts/project/merge_requests/show', }, (provider) => { - describe('Merge Request Discussions Endpoint', () => { + describe('GET discussions', () => { beforeEach(() => { const interaction = { state: 'a merge request with discussions exists', @@ -175,14 +175,14 @@ import { getDiscussions } from '../../../resources/api/project/merge_requests'; pactWith( { - consumer: 'MergeRequest#show', - provider: 'Merge Request Discussions Endpoint', + consumer: 'MergeRequests#show', + provider: 'GET discussions', log: '../logs/consumer.log', - dir: '../contracts/project/merge_request/show', + dir: '../contracts/project/merge_requests/show', }, (provider) => { - describe('Merge Request Discussions Endpoint', () => { + describe('GET discussions', () => { beforeEach(() => { const interaction = { state: 'a merge request with discussions exists', @@ -232,7 +232,7 @@ There we have it! The consumer test is now set up. You can now try [running this As you may have noticed, the request and response definitions can get large. This results in the test being difficult to read, with a lot of scrolling to find what you want. You can make the test easier to read by extracting these out to a `fixture`. -Create a file under `spec/contracts/consumer/fixtures/project/merge_request` called `discussions.fixture.js` where you will place the `request` and `response` definitions. +Create a file under `spec/contracts/consumer/fixtures/project/merge_requests` called `discussions.fixture.js` where you will place the `request` and `response` definitions. ```javascript import { Matchers } from '@pact-foundation/pact'; @@ -279,13 +279,13 @@ With all of that moved to the `fixture`, you can simplify the test to the follow ```javascript import { pactWith } from 'jest-pact'; -import { Discussions } from '../../../fixtures/project/merge_request/discussions.fixture'; +import { Discussions } from '../../../fixtures/project/merge_requests/discussions.fixture'; import { getDiscussions } from '../../../resources/api/project/merge_requests'; -const CONSUMER_NAME = 'MergeRequest#show'; -const PROVIDER_NAME = 'Merge Request Discussions Endpoint'; +const CONSUMER_NAME = 'MergeRequests#show'; +const PROVIDER_NAME = 'GET discussions'; const CONSUMER_LOG = '../logs/consumer.log'; -const CONTRACT_DIR = '../contracts/project/merge_request/show'; +const CONTRACT_DIR = '../contracts/project/merge_requests/show'; pactWith( { diff --git a/doc/development/testing_guide/contract/index.md b/doc/development/testing_guide/contract/index.md index 08a21e58a52..31d68bb9f4f 100644 --- a/doc/development/testing_guide/contract/index.md +++ b/doc/development/testing_guide/contract/index.md @@ -24,7 +24,7 @@ The contracts themselves are stored in [`/spec/contracts/contracts`](https://git ### Run the consumer tests -Before running the consumer tests, go to `spec/contracts/consumer` and run `npm install`. To run all the consumer tests, you just need to run `npm test -- /specs`. Otherwise, to run a specific spec file, replace `/specs` with the specific spec filename. +Before running the consumer tests, go to `spec/contracts/consumer` and run `npm install`. To run all the consumer tests, you just need to run `npm run jest:contract -- /specs`. Otherwise, to run a specific spec file, replace `/specs` with the specific spec filename. Running the consumer test will create the contract that the provider test uses to verify the actual API behavior. You can also run tests from the root directory of the project, using the command `yarn jest:contract`. @@ -40,6 +40,14 @@ rake contracts:merge_requests:pact:verify:discussions rake contracts:merge_requests:test:merge_requests[contract_merge_requests] # Run all merge request contract tests ``` +#### Verify the contracts in Pact Broker + +By default, the Rake tasks will verify the locally stored contracts. In order to verify the contracts published in the Pact Broker, we need to set the `PACT_BROKER` environment variable to `true`. It is important to point out here that the file path and file name of the provider test is what is used to find the contract in the Pact Broker which is why it is important to make sure the [provider test naming conventions](#provider-naming) are followed. + +## Publish contracts to Pact Broker + +The contracts generated by the consumer test can be published to a hosted Pact Broker by going to `spec/contracts` and running the `publish-contracts.sh` script. + ## Test suite folder structure and naming conventions To keep the consumer and provider test suite organized and maintainable, it's important that tests are organized, also that consumers and providers are named consistently. Therefore, it's important to adhere to the following conventions. @@ -50,31 +58,33 @@ Having an organized and sensible folder structure for the test suite makes it ea #### Consumer tests -The consumer tests are grouped according to the different pages in the application. Each file contains various types of requests found in a page. As such, the consumer test files are named using the Rails standards of how pages are referenced. For example, the project pipelines page would be the `Project::Pipeline#index` page so the equivalent consumer test would be located in `consumer/specs/project/pipelines/index.spec.js`. +The consumer tests are grouped according to the different pages in the application. Each file contains various types of requests found in a page. As such, the consumer test files are named using the Rails standards of how pages are referenced. For example, the project pipelines page would be the `Project::Pipelines#index` page so the equivalent consumer test would be located in `consumer/specs/project/pipelines/index.spec.js`. When defining the location to output the contract generated by the test, we want to follow the same file structure which would be `contracts/project/pipelines/` for this example. This is the structure in `consumer/resources` and `consumer/fixtures` as well. +The naming of the folders must also be pluralized to match how they are called in the Rails naming standard. + #### Provider tests The provider tests are grouped similarly to our controllers. Each of these tests contains various tests for an API endpoint. For example, the API endpoint to get a list of pipelines for a project would be located in `provider/pact_helpers/project/pipelines/get_list_project_pipelines_helper.rb`. The provider states are grouped according to the different pages in the application similar to the consumer tests. ### Naming conventions -When writing the consumer and provider tests, there are parts where a name is required for the consumer and provider. Since there are no restrictions imposed by Pact on how these should be named, a naming convention is important to keep it easy for us to figure out which consumer and provider tests are involved during debugging. Pact also uses the consumer and provider names to generate the generated contracts in the `#{consumer_name}-#{provider_name}` format. +When writing the consumer and provider tests, there are parts where a name is required for the consumer and provider. Since there are no restrictions imposed by Pact on how these should be named, a naming convention is important to keep it easy for us to figure out which consumer and provider tests are involved during debugging. Pact also uses the consumer and provider names to create the locally stored contract file names in the `#{consumer_name}-#{provider_name}` format. #### Consumer naming -As mentioned in the [folder structure section](#consumer-tests), consumer tests are grouped according to the different pages in the application. As such, consumer names should follow the same naming format using the Rails standard. For example, the consumer test for `Project::Pipeline#index` would be `ProjectPipeline#index` as the consumer name. Since Pact uses this name to name the contracts it generates, the colons (`::`) are dropped as colons are not valid characters in file names. +As mentioned in the [folder structure section](#consumer-tests), consumer tests are grouped according to the different pages in the application. As such, consumer names should follow the same naming format using the Rails standard. For example, the consumer test for `Project::Pipelines#index` would be under the `project` folder and will be called `Pipelines#index` as the consumer name. #### Provider naming -These are the API endpoints that provides the data to the consumer so they are named according to the API endpoint they pertain to. Be mindful that this name is as descriptive as possible. For example, if we're writing a test for the `GET /groups/:id/projects` endpoint, we don't want to name it "Projects endpoint" as there is a `GET /projects` endpoint as well that also fetches a list of projects the user has access to across all of GitLab. An easy way to name them is by checking out our [API documentation](../../../api/api_resources.md) and naming it the same way it is named in there. So the [`GET /groups/:id/projects`](../../../api/groups.md#list-a-groups-projects) would be called `List a group’s projects` and [`GET /projects`](../../../api/projects.md#list-all-projects) would be called `List all projects`. Subsequently, the test files are named `list_a_groups_projects_helper.rb` and `list_all_projects_helper.rb` respectively. +These are the API endpoints that provides the data to the consumer so they are named according to the API endpoint they pertain to. Be mindful that this begins with the HTTP request method and the rest of the name is as descriptive as possible. For example, if we're writing a test for the `GET /groups/:id/projects` endpoint, we don't want to name it "GET projects endpoint" as there is a `GET /projects` endpoint as well that also fetches a list of projects the user has access to across all of GitLab. To choose an appropriate name, we can start by checking out our [API documentation](../../../api/api_resources.md) and naming it the same way it is named in there while making sure to keep the name in sentence case. So the [`GET /groups/:id/projects`](../../../api/groups.md#list-a-groups-projects) would be called `GET list a group's projects` and [`GET /projects`](../../../api/projects.md#list-all-projects) would be called `GET list all projects`. Subsequently, the test files are named `get_list_a_groups_projects_helper.rb` and `get_list_all_projects_helper.rb` respectively. -There are some cases where the provider being tested may not be documented so, in those cases, fall back to choosing a name that is as descriptive as possible to ensure it's easy to tell what the provider is for. +There are some cases where the provider being tested may not be documented so, in those cases, fall back to starting with the HTTP request method followed by a name that is as descriptive as possible to ensure it's easy to tell what the provider is for. #### Conventions summary | Tests | Folder structure | Naming convention | | ----- | ---------------- | ----------------- | -| Consumer Test | Follows the Rails reference standards. For example, `Project::Pipeline#index` would be `consumer/specs/project/pipelines/index.spec.js` | Follows the Rails naming standard. For example, `Project::Pipeline#index` would be `ProjectPipeline#index` | -| Provider Test | Grouped like the Rails controllers. For example, [`List project pipelines` API endpoint](../../../api/pipelines.md#list-project-pipelines) would be `provider/pact_helpers/project/pipelines/provider/pact_helpers/project/pipelines/get_list_project_pipelines_helper.rb` | Follows the API documentation naming scheme. For example, [`GET /projects/:id/pipelines`](../../../api/pipelines.md#list-project-pipelines) would be called `List project pipelines`. | +| Consumer Test | Follows the Rails reference standards. For example, `Project::Pipelines#index` would be `consumer/specs/project/pipelines/index.spec.js` | Follows the Rails naming standard. For example, `Project::Pipelines#index` would be `Pipelines#index` within the `project` folder. | +| Provider Test | Grouped like the Rails controllers. For example, [`GET list project pipelines` API endpoint](../../../api/pipelines.md#list-project-pipelines) would be `provider/pact_helpers/project/pipelines/provider/pact_helpers/project/pipelines/get_list_project_pipelines_helper.rb` | Follows the API documentation naming scheme in sentence case. For example, [`GET /projects/:id/pipelines`](../../../api/pipelines.md#list-project-pipelines) would be called `GET list project pipelines`. | diff --git a/doc/development/testing_guide/contract/provider_tests.md b/doc/development/testing_guide/contract/provider_tests.md index 1772ed9384e..3ce9f91a307 100644 --- a/doc/development/testing_guide/contract/provider_tests.md +++ b/doc/development/testing_guide/contract/provider_tests.md @@ -10,7 +10,7 @@ This tutorial guides you through writing a provider test from scratch. It is a c ## Create the skeleton -Provider tests are quite simple. The goal is to set up the test data and then link that with the corresponding contract. Start by creating a file called `discussions_helper.rb` under `spec/contracts/provider/pact_helpers/project/merge_request`. Note that the files are called `helpers` to match how they are called by Pact in the Rake tasks, which are set up at the end of this tutorial. +Provider tests are quite simple. The goal is to set up the test data and then link that with the corresponding contract. Start by creating a file called `get_discussions_helper.rb` under `spec/contracts/provider/pact_helpers/project/merge_request`. Note that the files are called `helpers` to match how they are called by Pact in the Rake tasks, which are set up at the end of this tutorial. To learn more about how the contract test directory is structured, see the contract testing [test suite folder structure](index.md#test-suite-folder-structure). @@ -23,7 +23,7 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do + Pact.service_provider 'GET discussions' do end end @@ -39,8 +39,8 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do - honours_pact_with 'MergeRequest#show' do + Pact.service_provider 'GET discussions' do + honours_pact_with 'MergeRequests#show' do end end @@ -59,10 +59,10 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do + Pact.service_provider 'GET discussions' do app { Environment::Test.app } - honours_pact_with 'MergeRequest#show' do + honours_pact_with 'MergeRequests#show' do end end @@ -79,11 +79,11 @@ require_relative '../../../spec_helper' module Provider module DiscussionsHelper - Pact.service_provider 'Merge Request Discussions Endpoint' do + Pact.service_provider 'GET discussions' do app { Environment::Test.app } - honours_pact_with 'MergeRequest#show' do - pact_uri '../contracts/project/merge_request/show/mergerequest#show-merge_request_discussions_endpoint.json' + honours_pact_with 'MergeRequests#show' do + pact_uri '../contracts/project/merge_requests/show/mergerequests#show-merge_request_discussions_endpoint.json' end end end @@ -92,20 +92,25 @@ end ## Add / update the Rake tasks -Now that you have a test created, you must create Rake tasks that run this test. The Rake tasks are defined in [`lib/tasks/contracts.rake`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/tasks/contracts.rake) where we have individual Rake tasks to run individual specs, but also Rake tasks that run a group of tests. +Now that you have a test created, you must create Rake tasks that run this test. The Rake tasks are defined in [`lib/tasks/contracts/merge_requests.rake`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/tasks/contracts/merge_requests.rake) where we have individual Rake tasks to run individual tests, but also Rake tasks that run a group of tests. -Under the `contracts:mr` namespace, introduce the Rake task to run this new test specifically. In it, call `pact.uri` to define the location of the contract and the provider test that tests that contract. Notice here that `pact_uri` has a parameter called `pact_helper`. This is why the provider tests are called `_helper.rb`. +Under the `contracts:merge_requests` namespace, introduce the Rake task to run this new test specifically. In it, call `pact.uri` to define the location of the contract and the provider test that tests that contract. Notice here that `pact_uri` has a parameter called `pact_helper`. This is why the provider tests are called `_helper.rb`. ```ruby -Pact::VerificationTask.new(:discussions) do |pact| +Pact::VerificationTask.new(:get_discussions) do |pact| + provider = File.expand_path('../../../spec/contracts/provider', __dir__) + pact_helper_location = "pact_helpers/project/merge_requests/show/get_discussions_helper.rb" + pact.uri( - "#{contracts}/contracts/project/merge_request/show/merge_request#show-merge_request_discussions_endpoint.json", - pact_helper: "#{provider}/pact_helpers/project/merge_request/discussions_helper.rb" + Provider::ContractSourceHelper.contract_location(:rake, pact_helper_location), + pact_helper: "#{provider}/#{pact_helper_location}" ) end ``` -At the same time, add your new `:discussions` Rake task to be included in the `test:merge_request` Rake task. In that Rake task, there is an array defined (`%w[metadata diffs]`). You must add `discussions` in that list. +[`Provider::ContractSourceHelper`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/provider/helpers/contract_source_helper.rb) is a helper module that has the `#contract_location` method which parses `pact_helper_location` and determines where the contract is stored locally or on the Pact Broker depending on the `requester` passed in. + +At the same time, add your new `:get_discussions` Rake task to be included in the `test:merge_requests` Rake task. In that Rake task, there is an array defined (`%w[get_diffs_batch get_diffs_metadata]`). You must add `get_discussions` in that list. ## Create test data @@ -113,7 +118,7 @@ As the last step, create the test data that allows the provider test to return t You can read more about [provider states](https://docs.pact.io/implementation_guides/ruby/provider_states). We can do global provider states but for this tutorial, the provider state is for one specific `state`. -To create the test data, create `discussions_state.rb` under `spec/contracts/provider/states/project/merge_request`. Be sure to also import this state file in the `discussions_helper.rb` file. +To create the test data, create `show_state.rb` under `spec/contracts/provider/states/project/merge_requests`. Be sure to also import this state file in the `get_discussions_helper.rb` file. ### Default user in `spec/contracts/provider/spec_helper.rb` @@ -141,7 +146,7 @@ Any further modifications to the user that's needed can be done through the indi In the state file, you must define which consumer this provider state is for. You can do that with `provider_states_for`. Make sure that the `name` provided matches the name defined for the consumer. ```ruby -Pact.provider_states_for 'MergeRequest#show' do +Pact.provider_states_for 'MergeRequests#show' do end ``` @@ -150,7 +155,7 @@ end In the `provider_states_for` block, you then define the state the test data is for. These states are also defined in the consumer test. In this case, there is a `'a merge request with discussions exists'` state. ```ruby -Pact.provider_states_for "MergeRequest#show" do +Pact.provider_states_for "MergeRequests#show" do provider_state "a merge request with discussions exists" do end @@ -162,7 +167,7 @@ end This is where you define the test data creation steps. Use `FactoryBot` to create the data. As you create the test data, you can keep [running the provider test](index.md#run-the-provider-tests) to check on the status of the test and figure out what else is missing in your data setup. ```ruby -Pact.provider_states_for "MergeRequest#show" do +Pact.provider_states_for "MergeRequests#show" do provider_state "a merge request with discussions exists" do set_up do user = User.find_by(name: Provider::UsersHelper::CONTRACT_USER_NAME) @@ -187,20 +192,19 @@ Now that the provider state file is created, you need to import the state file t # frozen_string_literal: true require_relative '../../../spec_helper' -require_relative '../../../states/project/merge_request/discussions_state' +require_relative '../../../states/project/merge_requests/show_state' module Provider module DiscussionsHelper - Pact.service_provider "/merge_request/discussions" do + Pact.service_provider "GET discussions" do app { Environments::Test.app } honours_pact_with 'Merge Request#show' do - pact_uri '../contracts/project/merge_request/show/merge_request#show-merge_request_discussions_endpoint.json' + pact_uri '../contracts/project/merge_requests/show/mergerequests#show-merge_request_discussions_endpoint.json' end end end end - ``` -And there we have it. The provider test for `discussions_helper.rb` should now pass with this. +And there we have it. The provider test for `get_discussions_helper.rb` should now pass with this. |