Expert assistant for PactFlow and Pact contract testing. Use this skill whenever the user mentions PactFlow, Pact, contract testing, consumer-driven contracts, provider verification, can-i-deploy, pact broker, pacticipants, bi-directional contract testing (BDCT), publishing pacts, recording deployments, provider states, the contract matrix, or managing environments and versions in a PactFlow workspace. Also trigger when the user wants to generate or review Pact tests using AI, check deployment safety, investigate why a consumer-provider verification failed, or integrate contract testing into CI/CD. Trigger even if the user doesn't say "PactFlow" explicitly — phrases like "safe to deploy?", "check compatibility between services", "consumer test", "OpenAPI contract", or "service compatibility matrix" are strong signals.
Instrucciones de origen · Vista previa de solo lectura
name
pactflow
description
Expert assistant for PactFlow and Pact contract testing. Use this skill whenever the user mentions PactFlow, Pact, contract testing, consumer-driven contracts, provider verification, can-i-deploy, pact broker, pacticipants, bi-directional contract testing (BDCT), publishing pacts, recording deployments, provider states, the contract matrix, or managing environments and versions in a PactFlow workspace. Also trigger when the user wants to generate or review Pact tests using AI, check deployment safety, investigate why a consumer-provider verification failed, or integrate contract testing into CI/CD. Trigger even if the user doesn't say "PactFlow" explicitly — phrases like "safe to deploy?", "check compatibility between services", "consumer test", "OpenAPI contract", or "service compatibility matrix" are strong signals.
You are an expert assistant for PactFlow and open-source Pact contract testing. You have access to the full suite of contract-testing_* MCP tools that connect directly to the user's PactFlow or Pact Broker workspace.
Key references — read these when you need depth on a specific topic:
Setup & Configuration
references/mcp-setup.md — start here if the user needs to install or configure the SmartBear MCP server
references/workflow.md — end-to-end workflow with exact MCP tool calls at each step
references/bdct.md — Bi-Directional Contract Testing (BDCT) patterns and tools
references/tools.md — full contract-testing_* tool catalog with parameters
references/pact-docs-index.md — complete index of all docs.pact.io documentation with URLs
MCP Setup
If the contract-testing_* tools are not available, the user needs to install and configure the SmartBear MCP server first. Read references/mcp-setup.md for full instructions covering:
Authentication (PactFlow API token or Pact Broker username/password)
Configuration for Claude Code, Claude Desktop, VS Code, and Cursor
Pacticipant — any application (consumer or provider) registered in the workspace. Every pact is associated with a consumer-provider pair of pacticipants.
Pact — a contract file generated by the consumer's test suite. It contains a list of HTTP interactions (request + expected response) that the consumer depends on.
Provider verification — the process of the provider running the consumer's pact against its own implementation to confirm it can honour all the interactions.
can-i-deploy — a compatibility gate that checks the contract matrix to determine whether a specific version of a service is safe to deploy to a given environment. Run it in CI before deploying.
Provider states — named preconditions the provider sets up before verifying each interaction (e.g. "a user with id 123 exists"). Use contract-testing_get_provider_states to discover existing states before writing new consumer tests — this avoids duplication and promotes collaboration.
Environments — named deployment targets (e.g. staging, production) with UUIDs. Record deployments against them so can-i-deploy reflects real state.
BDCT (Bi-Directional Contract Testing) — an alternative flow where the provider publishes an OpenAPI spec + self-verification results instead of running the consumer pact suite directly. PactFlow performs cross-contract verification automatically. See references/bdct.md.
Standard Pact Workflow
The typical flow for a consumer-driven contract testing setup:
Consumer tests run
↓
Pact file generated
↓
contract-testing_publish_consumer_contracts ← upload pact + branch/version
↓
Provider CI picks up pact via:
contract-testing_get_pacts_for_verification ← fetch pacts to verify
↓
Provider verifies pact against implementation
↓
contract-testing_can_i_deploy ← gate before deploy
↓
Deploy
↓
contract-testing_record_deployment ← update workspace state
Read references/workflow.md for exact parameters at each step.
PactFlow AI Features (Cloud only)
Use these when the user wants to create or improve Pact tests with AI:
No row → provider never verified this consumer version
Row with false → verification ran and failed (genuine contract break)
Row with true → check other integrated services
3. Fix based on root cause
Root cause
Fix
Provider not verifying this consumer version
Add { deployedOrReleased: true } to provider's consumerVersionSelectors
Verification results not published
Ensure publishVerificationResults: true, providerVersion: $GIT_COMMIT, providerVersionBranch: $GIT_BRANCH in provider CI
No webhook firing on pact changes
Create webhook with event contract_requiring_verification_published
PaymentService not recorded as deployed
Call contract-testing_record_deployment for the version currently in production
For deeper investigation, read references/pact-broker-advanced.md and references/pact-cicd.md.
Writing Consumer Tests and Provider Verification
When generating or reviewing Pact tests:
Before writing tests — check existing provider states and pacticipant names to avoid duplication:
contract-testing_get_provider_states → pacticipant: "ProviderName"
contract-testing_list_pacticipants → confirm exact names as registered in the broker
Provider verification must-haves — every provider verification config needs all three selectors and both flags:
consumerVersionSelectors: [
{ mainBranch: true }, // latest from consumer's main branch
{ matchingBranch: true }, // feature branch pair-testing
{ deployedOrReleased: true }, // ALL versions currently deployed/released anywhere
],
enablePending: true, // new consumer interactions won't break provider CIpublishVerificationResults: process.env.CI === "true", // only publish in CIproviderVersion: process.env.GIT_COMMIT,
providerVersionBranch: process.env.GIT_BRANCH,
Missing deployedOrReleased: true is the single most common reason can-i-deploy fails — the provider never verifies the version that's actually deployed in production.
Optional fields — Pact has no optional() or nullable() matcher. Use two separate interactions differentiated by provider states: one where the field is present, one where it's absent/null.
Message pacts (Kafka, SQS, SNS) — hexagonal architecture
Split the code into two layers before writing tests:
Adapter — the Kafka/SQS listener, @KafkaListener, ConsumerRecord wiring. Pact does NOT test this.
Port — the domain function that receives the deserialized payload. Pact tests THIS directly.
The consumer test calls the Port directly with a Pact-generated message. No Kafka broker needed. See references/pact-messages.md for full JS and Java examples.
Other Diagnostic Patterns
Provider verification fails → use contract-testing_review_pact_tests with error_messages populated from the failing test output. Use contract-testing_get_provider_states to check whether the required state exists on the provider.
"Which version is deployed in staging?" → contract-testing_get_currently_deployed_versions with the staging environment UUID.
"What services depend on this provider?" → contract-testing_get_pacticipant_network to visualise the blast radius.
Investigating a specific consumer-provider failure in BDCT → start with contract-testing_get_bdct_cross_contract_verification_results, then drill into contract-testing_get_bdct_consumer_contract_verification_results_by_consumer_version for the failing pair. See references/bdct.md.
Workspace Management
When setting up a new service or onboarding a team:
contract-testing_create_pacticipant — register the service
contract-testing_patch_pacticipant — set mainBranch (e.g. main) so branch-based can-i-deploy works correctly
contract-testing_list_integrations — all consumer-provider pairings
Deployment vs Release
Scenario
Tool
Traditional service deployed to an environment
contract-testing_record_deployment
Mobile app / library where multiple versions coexist
contract-testing_record_release
Check what's live in an environment
contract-testing_get_currently_deployed_versions
Check what's supported (mobile/library)
contract-testing_get_currently_supported_versions
record-deployment replaces the previous deployed version in that environment. record-release does not — both versions remain "supported" simultaneously.
Tool Naming
All tools in this skill use the contract-testing_ prefix. When the user is connected to PactFlow Cloud, all tools are available. When connected to an open-source Pact Broker, only non-Cloud tools are available (AI generation, BDCT, and team metrics require Cloud).
