1 files changed, 53 insertions, 24 deletions
diff --git a/doc/development/testing_guide/contract/provider_tests.md b/doc/development/testing_guide/contract/provider_tests.md
index 0da5bcb4aef..92ac4c4ed71 100644
--- a/doc/development/testing_guide/contract/provider_tests.md
+++ b/doc/development/testing_guide/contract/provider_tests.md
@@ -6,23 +6,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Writing provider tests
 
-This tutorial guides you through writing a provider test from scratch. It is a continuation of the [consumer test tutorial](consumer_tests.md). To start, the provider tests are written using [`pact-ruby`](https://github.com/pact-foundation/pact-ruby). In this tutorial, you write a provider test that addresses the contract generated by `discussions.spec.js`.
+This tutorial guides you through writing a provider test from scratch. It is a continuation of the [consumer test tutorial](consumer_tests.md). To start, the provider tests are written using [`pact-ruby`](https://github.com/pact-foundation/pact-ruby). In this tutorial, you write a provider test that addresses the contract generated by `discussions.spec.js`. As Pact is a consumer-driven testing tool, this tutorial assumes that there is an existing consumer test that had already generated a contract for us to work with.
 
 ## 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/specs`. 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 `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).
 
 ### The `service_provider` block
 
 The `service_provider` block is where the provider test is defined. For this block, put in a description of the service provider. Name it exactly as it is called in the contracts that are derived from the consumer tests.
 
 ```ruby
-require_relative '../spec_helper'
+require_relative '../../../spec_helper'
 
 module Provider
   module DiscussionsHelper
     Pact.service_provider 'Merge Request Discussions Endpoint' do
-      
+
     end
   end
 end
@@ -33,33 +35,35 @@ end
 The `honours_pact_with` block describes which consumer this provider test is addressing. Similar to the `service_provider` block, name this exactly the same as it's called in the contracts that are derived from the consumer tests.
 
 ```ruby
-require_relative '../spec_helper'
+require_relative '../../../spec_helper'
 
 module Provider
   module DiscussionsHelper
     Pact.service_provider 'Merge Request Discussions Endpoint' do
-      honours_pact_with 'Merge Request Page' do
-        
+      honours_pact_with 'MergeRequest#show' do
+
       end
     end
   end
 end
 ```
 
+To learn more about how to name the consumers and providers, see contract testing [naming conventions](index.md#naming-conventions).
+
 ## Configure the test app
 
 For the provider tests to verify the contracts, you must hook it up to a test app that makes the actual request and return a response to verify against the contract. To do this, configure the `app` the test uses as `Environment::Test.app`, which is defined in [`spec/contracts/provider/environments/test.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/provider/environments/test.rb).
 
 ```ruby
-require_relative '../spec_helper'
+require_relative '../../../spec_helper'
 
 module Provider
   module DiscussionsHelper
     Pact.service_provider 'Merge Request Discussions Endpoint' do
       app { Environment::Test.app }
-      
-      honours_pact_with 'Merge Request Page' do
-        
+
+      honours_pact_with 'MergeRequest#show' do
+
       end
     end
   end
@@ -71,15 +75,15 @@ end
 Now that the test app is configured, all that is left is to define which contract this provider test is verifying. To do this, set the `pact_uri`.
 
 ```ruby
-require_relative '../spec_helper'
+require_relative '../../../spec_helper'
 
 module Provider
   module DiscussionsHelper
     Pact.service_provider 'Merge Request Discussions Endpoint' do
       app { Environment::Test.app }
-      
-      honours_pact_with 'Merge Request Page' do
-        pact_uri '../contracts/merge_request_page-merge_request_discussions_endpoint.json'
+
+      honours_pact_with 'MergeRequest#show' do
+        pact_uri '../contracts/project/merge_request/show/mergerequest#show-merge_request_discussions_endpoint.json'
       end
     end
   end
@@ -95,8 +99,8 @@ Under the `contracts:mr` namespace, introduce the Rake task to run this new test
 ```ruby
 Pact::VerificationTask.new(:discussions) do |pact|
   pact.uri(
-    "#{contracts}/contracts/merge_request_page-merge_request_discussions_endpoint.json",
-    pact_helper: "#{provider}/specs/discussions_helper.rb"
+    "#{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"
   )
 end
 ```
@@ -109,7 +113,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`. As a quick aside, make sure to also import this state file in the `discussions_helper.rb` file.
+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.
 
 ### Default user in `spec/contracts/provider/spec_helper.rb`
 
@@ -118,10 +122,13 @@ Before you create the test data, note that a default user is created in the [`sp
 ```ruby
 RSpec.configure do |config|
   config.include Devise::Test::IntegrationHelpers
+  config.include FactoryBot::Syntax::Methods
+
   config.before do
-    user = FactoryBot.create(:user, name: "Contract Test").tap do |user|
+    user = create(:user, name: Provider::UsersHelper::CONTRACT_USER_NAME).tap do |user|
       user.current_sign_in_at = Time.current
     end
+
     sign_in user
   end
 end
@@ -134,7 +141,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 'Merge Request Page' do
+Pact.provider_states_for 'MergeRequest#show' do
 end
 ```
 
@@ -143,7 +150,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 "Merge Request Page" do
+Pact.provider_states_for "MergeRequest#show" do
   provider_state "a merge request with discussions exists" do
 
   end
@@ -155,7 +162,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 "Merge Request Page" do
+Pact.provider_states_for "MergeRequest#show" do
   provider_state "a merge request with discussions exists" do
     set_up do
       user = User.find_by(name: Provider::UsersHelper::CONTRACT_USER_NAME)
@@ -172,6 +179,28 @@ Pact.provider_states_for "Merge Request Page" do
 end
 ```
 
-Note the `Provider::UsersHelper::CONTRACT_USER_NAME` here to fetch a user is a user that is from the [`spec_helper`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/contracts/provider/spec_helper.rb) that sets up a user before any of these tests run.
+## Using the test data
+
+Now that the provider state file is created, you need to import the state file to the provider test.
+
+```ruby
+# frozen_string_literal: true
+
+require_relative '../../../spec_helper'
+require_relative '../../../states/project/merge_request/discussions_state'
+
+module Provider
+  module DiscussionsHelper
+    Pact.service_provider "/merge_request/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'
+      end
+    end
+  end
+end
+
+```
 
-And with that, the provider tests for `discussion_helper.rb` should now pass with this.
+And there we have it. The provider test for `discussions_helper.rb` should now pass with this.