feat(provider): add SoftFail mode for downstream-gated verification (#580)

Callers that have a downstream authoritative gate (e.g. a Pact Broker
can-i-merge / can-i-deploy check) want verification mismatches to be
recorded to the broker and reported in the test framework, but NOT to
fail CI locally — the downstream gate makes the real decision.

Previously the only way to suppress local failure was at the shell
layer (turning off pipefail around `go test`), which also silenced
verifier panics, broker auth failures, and any other infrastructure
problem. That made "tests didn't actually run but CI is green" a
common failure mode.

New behavior — `VerifyRequest.SoftFail` (default false, preserves
existing behavior):

  - SoftFail = false (default):
      err == nil           → subtest PASS
      err != nil           → subtest FAIL (t.Error)
  - SoftFail = true:
      err == nil           → subtest PASS
      ErrVerifierFailed    → subtest SKIP (t.Skipf, message preserved)
      any other err        → subtest FAIL (t.Error)

Infrastructure errors (ErrVerifierFailedToRun, panics, broker auth)
always fail the subtest, regardless of SoftFail — they signal the
verifier could not produce a result for the downstream gate to act on.

The discrimination uses `errors.Is(err, native.ErrVerifierFailed)`,
which leverages the mutual-exclusivity invariant of the two verifier
sentinels documented in #579.

Author: stan-is-hate

provider/verifier.go

@@ -2,6 +2,7 @@ package provider
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"log"
@@ -172,14 +173,35 @@ func (v *Verifier) verifyProviderRaw(request VerifyRequest, writer outputWriter)
 // VerifyProvider accepts an instance of `*testing.T`
 // running the provider verification with granular test reporting and
 // automatic failure reporting for nice, simple tests.
+//
+// The subtest "Provider pact verification" renders as:
+//   - PASS when verification succeeded;
+//   - SKIP (with the underlying error in the skip message) when
+//     request.SoftFail is true AND the error is a verification mismatch
+//     (errors.Is(err, ErrVerifierFailed)) — i.e. a downstream gate owns
+//     the authoritative compatibility decision;
+//   - FAIL otherwise — strict mode for any error, or soft-fail mode when
+//     the verifier itself could not produce a result (infrastructure
+//     error, panic, etc.).
 func (v *Verifier) VerifyProvider(t *testing.T, request VerifyRequest) error {
 	err := v.verifyProviderRaw(request, t)
 
 	// TODO: granular test reporting
 	// runTestCases(t, res)
 
 	t.Run("Provider pact verification", func(t *testing.T) {
-		if err != nil {
+		switch {
+		case err == nil:
+			// PASS — verification succeeded.
+		case request.SoftFail && errors.Is(err, native.ErrVerifierFailed):
+			// Soft-fail mode + verification mismatch: render as SKIP so the
+			// test framework does not propagate failure. The caller is
+			// responsible for gating elsewhere (e.g. broker can-i-merge).
+			t.Skipf("pact verification failed (soft-fail enabled, broker has the record): %v", err)
+		default:
+			// Strict mode + any error, OR soft-fail mode + infrastructure
+			// error: fail loudly. Infrastructure errors signal the verifier
+			// could not produce a result for downstream gates to act on.
 			t.Error(err)
 		}
 	})

provider/verify_request.go

@@ -112,6 +112,23 @@ type VerifyRequest struct {
 	// PublishVerificationResults to the Pact Broker.
 	PublishVerificationResults bool
 
+	// SoftFail, when true, renders a verification mismatch (one or more
+	// consumer expectations not satisfied by the provider, returned by the
+	// verifier as ErrVerifierFailed) as a SKIPped subtest rather than a
+	// failed one. Use when the caller has a downstream gate — e.g. a Pact
+	// Broker can-i-merge / can-i-deploy check — that owns the authoritative
+	// compatibility decision, and local CI failure on the mismatch would
+	// duplicate or contradict that gate.
+	//
+	// Infrastructure errors (ErrVerifierFailedToRun, panics, broker auth
+	// failures, etc.) always fail the subtest regardless of this flag —
+	// they signal that the verifier could not produce a result for the
+	// downstream gate to act on.
+	//
+	// Default false preserves existing behavior: any verifier error fails
+	// the subtest.
+	SoftFail bool
+
 	// ProviderVersion is the semantical version of the Provider API.
 	ProviderVersion string