rules_pact

Bazel rules to test services interactions with pacts

MODULE.bazel

bazel_dep(name = "rules_pact", version = "1.2.0")

Usage

You can find this full example inside this repository

Start to declare a consumer:

consumer(
    name = "area-calculator-grpc",
    testonly = True,
    srcs = ":consumer_test",
    data = ["//events/eventstore/grpc/proto:protodef"],
    visibility = ["//visibility:public"],
)

srcs = ":consumer_test" contains the implementation of the pact-test, in your favourite language :), see this example with go

Then declare a provider:

provider(
    name = "area-calculator-provider",
    srcs = ":cmd",
    opts = {
        "transport": "grpc",
        "port": "50051",
    },
    visibility = ["//visibility:public"],
    deps = [":proxy"],
)

use opts rule attribute to declare some options used by the toolchain pact_verifier_cli

If needed, declare a side_car with the provider (proxy / state-manager /...) and bind it as a deps to your provider

Example of a http proxy side_car

side_car(
    name = "proxy",
    srcs = "//shape-app/api/proxy",
    health_check = "http://localhost:8080/healthz"
)

Example of a state-manager side_car:

side_car(
    name = "side_car",
    srcs = "//events/eventstore/grpc/test/helper",
    opts = {
        "state-change-url": "http://localhost:8081/event",
        "state-change-teardown": "true",
    },
    env = {
        "CONFIG": "$(location //events/eventstore/grpc/test/helper:config)",
    },
    data = ["//events/eventstore/grpc/test/helper:config"],
    health_check = "http://localhost:8081/healthz"
)

Then declare your pact_test:

pact_test(
    name = "pact_test",
    testonly = True,
    consumer = "//shape-app/api/pacts:grpc-consumer-go",
    provider = ":area-calculator-provider",
)

The pact_test rule will run the consumer to create the contract if tests are green. Then it will run the provider against the contract via pact_verifier_cli with the help of the side_car

Toolchains

toolchain	os	cpu	version (default)
pact_verifier_cli	osx;linux	amd64	1.0.1
pact_protobuf_plugin	osx;linux	amd64	0.3.5
libpact_ffi	osx;linux	amd64	0.4.9

NB: it's possible to embed libpact_ffi to create an hermetic build, like this example, by applying a patch.

Rules

• consumer
• provider
• side_car
• pact_test
• pact_reference_toolchain
• pact_protobuf_plugin_toolchain

consumer

consumer(name, srcs, data)

Rule that wrap consumer interaction. It executes the test provided in srcs attribute through the toolchain. This rule will be executed from the pact_test rule.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	a test target	Label	optional	None
data	data useful to provide with test target	List of labels	optional	[]

pact_protobuf_plugin_toolchain

pact_protobuf_plugin_toolchain(name, manifest, protobuf_plugin)

A pact protobuf plugin toolchain

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
manifest	A json manifest	Label	required
protobuf_plugin	A pact protobuf plugin binary	Label	required

pact_reference_toolchain

pact_reference_toolchain(name, libpact_ffi, pact_verifier_cli)

A pact reference toolchain

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
libpact_ffi	A pact ffi library	Label	required
pact_verifier_cli	A pact reference binary	Label	required

provider

provider(name, deps, srcs, opts)

Rule that describe provider interaction

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	any useful dep to run with the provider like a state-manager, a proxy or a side-car	List of labels	optional	[]
srcs	the provider to run	Label	optional	None
opts	options to provide to pact_verifier_cli	Dictionary: String -> String	optional	{}

side_car

side_car(name, srcs, data, env, health_check, opts)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	the side-car to run	Label	optional	None
data	any data useful to run with the side-car, like a configuration file for instance	List of labels	optional	[]
env	any environment variable to provide with the side_car	Dictionary: String -> String	optional	{}
health_check	uri to curl before launching provider test	String	optional	"nop"
opts	the option specific to the side-car	Dictionary: String -> String	optional	{}

pact_test

pact_test(kwargs)

PARAMETERS

Name	Description	Default Value
kwargs	-	none