From c24e84f19c4cf6cd37fb14a5e424b24743397a40 Mon Sep 17 00:00:00 2001 From: Olivier Picaud Date: Mon, 23 Oct 2023 19:31:49 +0200 Subject: [PATCH] docs: update rules_pact and main docs --- README.md | 3 +- rules_pact/BUILD.bazel | 10 ++- rules_pact/README.md | 140 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 3 deletions(-) create mode 100644 rules_pact/README.md diff --git a/README.md b/README.md index e7e8c835..a31e91bf 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,9 @@ Providing a technical way to enhance collaboration within a team or within multi ### Currently - build has been succesfully ran on macos-darwin64 and linux-amd64 platforms -- no extra tools needs to be installed to build (a part Bazel of course) +- no extra tools needs to be installed to build (a part from Bazel of course) - the build is taking around 10 minutes, the most difficult part is to ensure cache usages (a part the first build) +- the monorepo is releasing [rules_pact](https://github.com/opicaud/monorepo/blob/main/rules_pact/README.md) ### Stats | #Build | Cache | Time | Build type | Cache time | diff --git a/rules_pact/BUILD.bazel b/rules_pact/BUILD.bazel index f9e230a3..b58391c5 100644 --- a/rules_pact/BUILD.bazel +++ b/rules_pact/BUILD.bazel @@ -1,5 +1,5 @@ load("@rules_pact//:defs.bzl", "pact_protobuf_plugin_toolchain", "pact_reference_toolchain") - +load("@bazel_skylib//rules:diff_test.bzl", "diff_test") load("@@//hack:release.bzl", "release_me") release_me() @@ -43,7 +43,7 @@ load("@stardoc//stardoc:stardoc.bzl", "stardoc") stardoc( name = "docs", input = "@rules_pact//:defs.bzl", - out = "README.md", + out = "docs.md", deps = [":bzl_lib"] ) load("@bazel_skylib//:bzl_library.bzl", "bzl_library") @@ -59,6 +59,12 @@ bzl_library( ) +diff_test( + name = "docs_diff_test", + file1 = ":docs", + file2 = ":README.md", +) + exports_files( glob(["defs.bzl"]), visibility = ["//visibility:public"], diff --git a/rules_pact/README.md b/rules_pact/README.md new file mode 100644 index 00000000..c45a2a00 --- /dev/null +++ b/rules_pact/README.md @@ -0,0 +1,140 @@ + + +# rules_pact +Bazel rules to test services interactions with [pacts][pactsws] + +[pactsws]: https://docs.pact.io/ + +- [consumer](#consumer) +- [provider](#provider) +- [side_car](#side_car) +- [pact_test](#pact_test) +- [pact_reference_toolchain](#pact_reference_toolchain) +- [pact_protobuf_plugin_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 | | + + + + +## pact_test + +
+pact_test(name, consumer, provider)
+
+ + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| consumer | - | Label | optional | `None` | +| provider | - | Label | optional | `None` | + + + + +## 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 | `{}` | + +