chore: update docs wrt verifying providers

docs/protocol-plugin-design.md

@@ -65,57 +65,21 @@ For an example of a simple gRPC consumer test, see [JVM gRPC Consumer](../exampl
 
 _High Level Summary_
 
-1. Plugin driver is responsible for starting the plugin. The framework communicates instructions for each Test Session vai the driver bus.
-2. Pact is given plugin specific configuration - including the administration API details - which is then sent to the administration server to initialise a new provider Test Session.
-3. The user starts the Provider Service, and runs the verify() command
-4. Pact fetches the pact files (e.g. from the broker), including the pacts for verification details if configured, and stores this information.
-5. For each pact, the framework will be responsible for configuring provider states, and sending each interaction from the pact file to the plugin. The plugin will then perform the plugin-specific interaction, communicating with the Provider Service and returning any mismatches to the framework. This process repeats for all interactions in all pacts.
+1. Plugin driver is responsible for starting the plugin. The framework communicates instructions for each Test Session to the plugin via the plugin driver and the gRPC interface.
+2. Pact framework fetches the pact files (e.g. from the broker), including the pacts for verification details if configured, and stores this information. 
+3. Pact framework detects plugin specific configuration in the Pact file and instructs the plugin driver to load the plugin.
+4. The user test code starts the Provider Service
+5. For each Pact interaction, the Pact framework will be responsible for configuring or invoking provider states.
 6. The Pact framework will maintain the details of the TestSession - including pacts, interaction failures, pending status, logs  etc.
-7. Pact calculates the verification status for the test session, and optionally publishes verification results back to a Broker.
-8. The Pact client library then conveys the verification status, and the driver terminates all plugin processes.
+7. The Pact framework will pass the Pact interaction to the plugin. The plugin will then perform the plugin-specific interaction, communicating with the Provider Service and returning any mismatches to the Pact framework. This process repeats for all interactions in all pacts.
+8. Pact framework calculates the verification status for the test session, and optionally publishes verification results back to a Broker.
+9. The Pact client library then conveys the verification status, and the driver terminates all plugin processes.
 
 _Provider Sequence Diagram_
-![pact_provider_plugin_sequence](https://user-images.githubusercontent.com/53900/103849702-872ec480-50f9-11eb-93ff-28d1fbfa5cd6.png)
+
+![pact_provider_plugin_sequence](protocol-transport-sequence-provider-test.png)
 
 
 _Example provider test_
 
-Here is an example for a raw "hello world" TCP provider test.
-
-```golang
-func TestV3PluginProvider(t *testing.T) {
-	go startTCPPlugin()
-	go startTCPProvider()
-
-	provider, err := v3.NewPluginProvider(v3.PluginProviderConfig{
-		Provider: "V3MessageProvider",
-		Port:     4444, // Communication port to the provider
-	})
-
-	verifier := v3.HTTPVerifier{
-		PluginConfig: provider,
-	}
-
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	// Verify the Provider with local Pact Files
-	err = verifier.VerifyPluginProvider(t, v3.VerifyPluginRequest{
-		BrokerURL:      os.Getenv("PACT_BROKER_URL"),
-		BrokerToken:    os.Getenv("PACT_BROKER_TOKEN"),
-		BrokerUsername: os.Getenv("PACT_BROKER_USERNAME"),
-		BrokerPassword: os.Getenv("PACT_BROKER_PASSWORD"),
-		PublishVerificationResults: true,
-		ProviderVersion:            "1.0.0",		
-		StateHandlers: v3.StateHandlers{
-			"world exists": func(s v3.ProviderStateV3) error {
-				// ... do something
-				return nil
-			},
-		},
-	})
-
-	assert.NoError(t, err)
-}
-```
+For an example of a simple gRPC provider test, see [JVM gRPC Provider](../examples/gRPC/area_calculator/provider-jvm).

docs/protocol-transport-sequence-consumer-test.txt

@@ -23,7 +23,7 @@ P3 <- P4: StartMockServerResponse
 P2 <- P3: Return mock server details
 P1 <- P2: Return mock server details
 P1 -> P5: Make requests to mock server
-note right of P5: Match requests\n and record results
+note right of P5: Match requests \nand record results
 P1 <- P5: Return response
 P1 -> P2: Shutdown mock server
 P2 -> P3: Shutdown mock server

docs/protocol-transport-sequence-provider-test.txt

@@ -0,0 +1,42 @@
+@startuml
+skinparam responseMessageBelowArrow true
+participant "System under test" as P1
+participant "Pact framework" as P2
+participant "Plugin Driver" as P3
+participant "Plugin" as P4
+participant "Provider" as P5
+P1 -> P2: Configure Test, fetch Pact file to verify
+P2 -> P3: Load plugin required by Pact file
+P3 -> P4: Start plugin and send InitPluginRequest
+P3 <- P4: Send catalogue entries (InitPluginResponse)
+P2 <- P3:
+P1 <- P2:
+P1 -> P5: Start gRPC provider for test
+P1 <- P5:
+P1 -> P2: Start test
+  loop For each interaction in Pact
+    P2 -> P3: Configure request to provider
+    activate P2
+    P3 -> P4: VerificationPreparationRequest
+    note right of P4: Setup request \nbased on interaction \nfrom Pact file
+    P3 <- P4: VerificationPreparationResponse
+    P2 <- P3: Return request data
+    P1 <- P2: Invoke user callback with request data
+    P1 -> P2:
+    P2 -> P3: Validate interaction with request data \nand provider details
+    P3 -> P4: VerifyInteractionRequest
+    P4 -> P5: Create request to provider
+    P4 <- P5: Return provider response
+    note right of P4: Validate response against \nPact interaction
+    P3 <- P4: VerifyInteractionResponse
+    P2 <- P3: Return results
+    deactivate P2
+  end
+P1 <- P2: Return results
+P1 -> P2: Finish Test
+P2 -> P3: Decrement access to plugin
+P3 -> P4: Shutdown plugin if no longer used
+P3 <- P4:
+P2 <- P3:
+P1 <- P2:
+@enduml