sbmt-pact 0.12.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e25420695b0554f5f33b616489005f728e0181586e0406da057fbd50bed1d06
+  data.tar.gz: 84972279401ef1a085806fc7e19a678bdd9b919edb306050c8c0432cf60c1cb3
+SHA512:
+  metadata.gz: aa7672e3b37b7ed48827fca27ce7eb433318a1bc03e1ad9d41b00fde572d718d2989ab57ae90c298bbab991b0277565d5bc23ddb2862d1a762268256357e3f50
+  data.tar.gz: 1e3ae269dd85853864be55b2131556c09f16f61d81b8308a9b112a86d2ad834e3bf159bf80d3ac34b868a8d9dc232f5601fb18ccd18e724cb1535b0f4440d713

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--require rails_helper

data/.rubocop.yml

@@ -0,0 +1,62 @@
+# We want Exclude directives from different
+# config files to get merged, not overwritten
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 2.7
+  TargetRailsVersion: 6.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - spec/internal/pkg/**/*
+
+require:
+  # Performance cops are bundled with Standard
+  - rubocop-performance
+  - rubocop-rails
+  - rubocop-rspec
+  # Standard's config uses custom cops,
+  # so it must be loaded
+  - standard
+
+inherit_gem:
+  standard: config/base.yml
+
+# rubocop-rails
+Rails/SkipsModelValidations:
+  Enabled: false
+
+# rubocop-rspec
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/LetSetup:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 10
+
+RSpec/ExampleLength:
+  Max: 70
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 15
+
+RSpec/DescribeClass:
+  Exclude:
+    - spec/sbmt/pact/tasks/*
+
+RSpec/EmptyExampleGroup:
+  Exclude:
+    - spec/pact/**/*

data/Appraisals

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# See compatibility table at https://www.fastruby.io/blog/ruby/rails/versions/compatibility-table.html
+
+versions_map = {
+  "6.0" => %w[2.7],
+  "6.1" => %w[2.7 3.0],
+  "7.0" => %w[3.1],
+  "7.1" => %w[3.2],
+  "7.2" => %w[3.3]
+}
+
+current_ruby_version = RUBY_VERSION.split(".").first(2).join(".")
+
+versions_map.each do |rails_version, ruby_versions|
+  ruby_versions.each do |ruby_version|
+    next if ruby_version != current_ruby_version
+
+    appraise "rails-#{rails_version}" do
+      gem "rails", "~> #{rails_version}.0"
+    end
+  end
+end

data/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased] - yyyy-mm-dd
+
+### Added
+
+### Changed
+
+- Remove sbmt-dev
+
+### Fixed
+
+## [0.11.1] - 2024-08-22
+
+### Fixed
+- the `verify_only` config option is now set based on the `PACT_CONSUMER_FULL_NAME` environment variable.
+- if the current `consumer_name` does not match the `verify_only` option, then the consumer verification is skipped
+
+## [0.11.0] - 2024-08-07
+
+### Added
+- async messages support
+- collection matchers
+- support of additional includes of proto-files for grpc plugin
+
+## [0.10.0] - 2024-08-15
+
+### Added
+- HTTP Rspec DSL
+
+## [0.9.0] - 2024-08-03
+
+### Added
+- pact-broker-proxy to filter proper transport types in specs
+- ability to run pact-tests on CI + dip
+
+### Fixed
+- refactor matchers
+
+## [0.8.0] - 2024-07-04
+
+### Added
+- Use `deployed: true` for default consumer selectors instead master branch
+
+## [0.7.0] - 2024-06-21
+
+### Added
+- Ability to limit consumers to verify with provider
+
+### Fixed
+- Changed pact-specs rspec meta (`type: :pact` => `pact: true`) for compatibility with legacy pact-ruby / older rspec
+- Bump used pact-protobuf-plugin version to 0.4.0
+- `match_any_string` now matches empty strings
+- limit pact:verify specs only to consumer pact-tests dir
+
+## [0.6.0] - 2024-06-05
+
+### Fixed
+- GRPC producer DSL (rspec) refined
+
+## [0.5.0] - 2024-06-05
+
+### Fixed
+- GRPC consumer DSL (rspec) refined
+- plugin matchers refined
+
+## [0.4.1] - 2024-06-06
+
+### Fixed
+- Use proper consumer version for provider verification
+
+## [0.4.0] - 2024-05-29
+
+### Added
+- Ability to verify provider specs against pact-broker
+
+## [0.3.0] - 2024-05-03
+
+### Added
+- Provider specs base DSL/helpers
+
+## [0.2.0] - 2024-04-18
+
+### Added
+- Consumer specs base DSL/helpers
+
+## [Unreleased]
+
+## [0.1.0] - 2024-04-12
+
+- Initial release

data/Dockerfile

@@ -0,0 +1,14 @@
+ARG RUBY_VERSION
+
+FROM ruby:$RUBY_VERSION
+
+ARG BUNDLER_VERSION
+ARG RUBYGEMS_VERSION
+
+ENV BUNDLE_JOBS=4 \
+  BUNDLE_RETRY=3
+
+RUN gem update --system "${RUBYGEMS_VERSION}" \
+  && rm /usr/local/lib/ruby/gems/*/specifications/default/bundler*.gemspec \
+  && gem install --default bundler:${BUNDLER_VERSION} \
+  && gem install bundler -v ${BUNDLER_VERSION}

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source ENV.fetch("RUBYGEMS_PUBLIC_SOURCE", "https://rubygems.org/")
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kuper Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# Sbmt Pact
+
+**`sbmt-pact`** is a powerful Ruby gem designed to simplify and streamline [Pact](https://docs.pact.io/) testing between microservices. This gem provides a robust set of RSpec utilities to help developers implement consumer-driven contract testing in microservice architectures.
+
+In the world of microservices, ensuring seamless communication between services is crucial. This gem leverages the Pact to enable effective contract testing, allowing you to catch integration issues early in the development cycle. Contract testing is a way to check if different parts of a system work well together. It's like making sure two puzzle pieces fit perfectly before assembling the whole puzzle. Each part is tested on its own to see if it follows a set of rules (the "contract") that everyone agreed on. This helps catch problems early and makes sure all parts of the system speak the same language.
+
+## Motivation
+
+Currently, the existing version of the [pact-ruby](https://github.com/pact-foundation/pact-ruby) gem only supports Pact Specification versions v1 and v2, which doesn't allow for:
+- Writing contract tests with non-HTTP transports (for example, gRPC)
+- Writing contract tests for async messages (Kafka, etc.)
+
+The `pact-ruby` gem is in maintenance mode, as there has been a transition to rust-core, which is intended to be used through FFI in non-Rust stacks.
+
+This gem eliminates the above-mentioned limitations and implements support for the latest versions of Pact specifications:
+- It's based on pact-ffi and pact-ruby-ffi
+- It provides a convenient DSL, simplifying the writing of contract tests in Ruby/RSpec
+
+## Architecture
+
+![Pact tests architecture](docs/sbmt-pact-arch.png)
+
+- DSL - implementation of RSpec-DSL for convenient writing of Pact tests
+- Matchers - implementation of Pact matchers, which are convenient helpers used in consumer-DSL, encapsulating all the logic for serialization into Pact format
+- Mock servers - mock servers that allow for correct execution of provider tests
+
+## Usage
+
+For each type of interaction (due to their specific features), a separate version of DSL has been implemented. However, the general principles remain the same for each type of interaction.
+
+```ruby
+
+# Declaration of a consumer test, always include the :pact tag
+# This is used in CI/CD pipelines to separate Pact tests from other RSpec tests
+# Pact tests are not run as part of the general RSpec pipeline
+RSpec.describe "SomePactConsumerTestForAnyTransport", :pact do
+  # declaration of the type of interaction - here we determine which consumer and provider interact on which transport
+  has_http_pact_between "CONSUMER-NAME", "PROVIDER-NAME"
+  # or
+  has_grpc_pact_between "CONSUMER-NAME", "PROVIDER-NAME"
+  # or
+  has_message_pact_between "CONSUMER-NAME", "PROVIDER-NAME"
+
+  # the context for one of the interactions, for example GET /api/v2/stores
+  context "with GET /api/v2/stores" do
+      let(:interaction) do
+        # creating a new interaction - within which we describe the contract
+        new_interaction
+          # if you need to save any metadata for subsequent use by the test provider,
+          # for example, specify the entity ID that will need to be moved to the database in the test provider
+          # we use the provider states, see more at https://docs.pact.io/getting_started/provider_states
+          .given("UNIQUE PROVIDER STATE", key1: value1, key2: value2)
+          # the description of the interaction, used for identification inside the package binding,
+          # is optional in some cases, but it is recommended to always specify
+          .upon_receiving("UNIQUE INTERACTION DESCRIPTION")
+          # the description of the request using the matchers
+          # the name and parameters of the method differ for different transports
+          .with_request(...)
+          # the description of the response using the matchers
+          # the name and parameters of the method differ for different transports
+          .with_response(...)
+          # further, there are differences for different types of transports,
+          # for more information, see the relevant sections of the documentation
+      end
+
+      it "executes the pact test without errors" do
+        interaction.execute do
+          # here our client is called for the API being tested
+          # in this context, the client can be: http client, grpc client, kafka consumer
+          expect(make_request).to be_success
+        end
+      end
+    end
+  end
+
+```
+
+Common DSL Methods:
+- `new_interaction` - initializes a new interaction
+- `given` - allows specifying a provider state with or without parameters, for more details see https://docs.pact.io/getting_started/provider_states
+- `upon_receiving` - allows specifying the name of the interaction
+
+### HTTP consumers
+
+Specific DSL methods:
+- `with_request(HTTP_METHOD, QUERY_PATH, {headers: kv_hash, body: kv_hash})` - request definition
+- `with_response(HTTP_STATUS, {headers: kv_hash, body: kv_hash})` - response definition
+
+More at [http_client_spec.rb](spec/pact/providers/sbmt-pact-test-app/http_client_spec.rb)
+
+### gRPC consumers
+
+Specific DSL methods:
+- `with_service(PROTO_PATH, RPC_SERVICE_AND_ACTION)` - specifies the contract used, PROTO_PATH is relative from the app root
+- `with_request(request_kv_hash)` - request definition
+- `with_response(response_kv_hash)` - response definition
+
+More at [grpc_client_spec.rb](spec/pact/providers/sbmt-pact-test-app/grpc_client_spec.rb)
+
+### Kafka consumers
+
+Specific DSL methods:
+- `with_headers(kv_hash)` - message-headers definition; you can use matchers
+- `with_metadata(kv_hash)` - message-metadata definition (special keys are `key` and `topic`, where, respectively, you can specify the matchers for the partitioning key and the topic
+
+Next, the specifics are one of two options for describing the format:
+
+**JSON** (to describe a message in a JSON representation):
+- `with_json_contents(kv_hash)` - message format definition
+
+**PROTO** (to describe the message in the protobuf view):
+- `with_proto_class(PROTO_PATH, PROTO_MESSAGE_NAME)` - specifies the contract used, PROTO_PATH is relative to the root, PROTO_MESSAGE_NAME is the name of the message used from the proto file
+- `with_proto_contents(kv_hash)` - message format definition
+
+More at [kafka_spec.rb](spec/pact/providers/sbmt-pact-test-app/kafka_spec.rb)
+
+### Matchers
+
+Matchers are special helper methods that allow you to define rules for matching request/response parameters at the level of the pact manifest.
+The matchers are described in the [Pact specifications](https://github.com/pact-foundation/pact-specification). In this gem, the matchers are implemented as RSpec helpers.
+
+For details of the implementation, see [matchers.rb](lib/sbmt/pact/matchers.rb)
+
+- `match_exactly(sample)` - match the exact value specified in the sample
+- `match_type_of(sample)` - match the data type (integer, string, boolean) specified in the sample
+- `match_include(sample)` - match a substring
+- `match_any_string(sample)` - match any string, because of the peculiarities, null and empty strings will also be matched here
+- `match_any_integer(sample)` - match any integer
+- `match_any_decimal(sample)` - match any float/double
+- `match_any_number(sample)` - match any integer/float/double
+- `match_any_boolean(sample)` - match any true/false
+- `match_uuid(sample)` - match any UUID (`match_regex` is used under the hood)
+- `match_regex(regex, sample)` - match by regexp
+- `match_datetime(format, sample)` - match any datetime
+- `match_iso8601(sample)` - match datetime in ISO8601 (the matcher does not fully comply with ISO8601, matches only the most common variants, `match_regex` is used under the hood)
+- `match_date(format, sample)` - match any date (rust datetime)
+- `match_time(format, sample)` - match any time (rust datetime)
+- `match_each(template)` - match all the elements of the array according to the specified template, you can use it for nested elements
+- `match_each_regex(regex, sample)` - match all array elements by regex, used for arrays with string elements
+- `match_each_key(template, key_matchers)` - match each hash key according to the specified template
+- `match_each_value(template)` - match each hash value according to the specified template, can be used for nested elements
+- `match_each_kv(template, key_matchers)` - match all the keys/values of Hash according to the specified template and key_matchers, can be used for nested elements
+
+See the different uses of the matchers in [matchers_spec.rb](spec/sbmt/pact/matchers_spec.rb)
+
+## Development & Test
+
+Install [Dip](https://github.com/bibendi/dip)
+
+### Setup
+
+```shell
+dip provision
+```
+
+### Run unit tests
+
+```shell
+dip rspec
+```
+
+### Run pact tests
+
+The Pact tests are not run within the general rspec pipeline, they need to be run separately, see below
+
+#### Consumer tests
+
+```shell
+dip pact consumer
+# or
+bundle exec rspec -t pact spec/pact/providers/**/*_spec.rb
+```
+
+**NOTE** If you have never run it, you need to run it at least once to generate json-pact manifests that will be used in provider tests (below)
+
+#### Provider tests
+
+```shell
+dip pact provider
+# or
+bundle exec rspec -t pact spec/pact/consumers/*_spec.rb
+```
+
+#### Using Pact Broker locally
+
+If you need to check the ability to work with a package broker locally, you need to do the following:
+
+- Run the broker
+
+```shell
+$ dip up pact-broker
+```
+
+- Run consumer tests to generate a pact manifest (it will be created in `spec/internal/pacts` based on the results of successful completion of consumer tests)
+
+```shell
+$ dip pact consumer
+```
+
+- Publish the generated pact manifest in the pact broker
+
+```shell
+$ dip pact-cli publish
+```
+
+- Make sure that the manifest is published by opening it in a browser http://localhost:9292 (don't forget to forward port 9292 to localhost, see `docker-compose.yml`)
+
+- run provider tests using a pact broker
+
+```shell
+$ dip pact provider-with-local-broker
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/dip.yml

@@ -0,0 +1,86 @@
+version: '7'
+
+environment:
+  RUBY_VERSION: '3.3'
+
+compose:
+  files:
+    - docker-compose.yml
+
+interaction:
+  bash:
+    description: Open the Bash shell in app's container
+    service: ruby
+    command: /bin/bash
+
+  bundle:
+    description: Run Bundler commands
+    service: ruby
+    command: bundle
+
+  rails:
+    description: Run RoR commands
+    service: ruby
+    command: bundle exec rails
+
+  appraisal:
+    description: Run Appraisal commands
+    service: ruby
+    command: bundle exec appraisal
+
+  rspec:
+    description: Run Rspec commands
+    service: ruby
+    command: bundle exec rspec
+    subcommands:
+      all:
+        command: bundle exec appraisal rspec
+      rails-6.0:
+        command: bundle exec appraisal rails-6.0 rspec
+      rails-6.1:
+        command: bundle exec appraisal rails-6.1 rspec
+      rails-7.0:
+        command: bundle exec appraisal rails-7.0 rspec
+
+  pact:
+    description: Run pact tests
+    service: ruby
+    environment:
+      RAILS_ENV: test
+      PACT_DO_NOT_TRACK: true
+    subcommands:
+      consumer:
+        command: bundle exec rspec -t pact spec/pact/providers/**/*_spec.rb
+      provider:
+        command: bundle exec rspec -t pact spec/pact/consumers/*_spec.rb
+      provider-with-local-broker:
+        command: /bin/sh -c 'PACT_CONSUMER_BRANCH=master PACT_CONSUMER_FULL_NAME=sbmt-pact-test-app PACT_BROKER_URL=http://pact-broker:9292 bundle exec rspec -t pact spec/pact/consumers/*_spec.rb'
+
+  pact-cli:
+    description: Run pact-broker commands
+    service: pact-cli
+    subcommands:
+      publish:
+        command: pact-broker publish --consumer-app-version 1.0.0 --branch master --broker-base-url http://pact-broker:9292 sbmt-pact-test-app-sbmt-pact-test-app.json
+
+  rubocop:
+    description: Run Ruby linter
+    service: ruby
+    command: bundle exec rubocop
+
+  setup:
+    description: Install deps
+    service: ruby
+    command: bin/setup
+
+  test:
+    description: Run linters, run all tests
+    service: ruby
+    command: bin/test
+
+provision:
+  - dip compose down --volumes
+  - cp -f lefthook-local.dip_example.yml lefthook-local.yml
+  - rm -f Gemfile.lock
+  - rm -f gemfiles/*gemfile*
+  - dip setup

data/docker-compose.yml

@@ -0,0 +1,40 @@
+services:
+  ruby:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        RUBY_VERSION: ${RUBY_VERSION:-3.3}
+        BUNDLER_VERSION: 2.4.22
+        RUBYGEMS_VERSION: 3.4.22
+    image: sbmt-pact-dev:0.1.0-ruby_${RUBY_VERSION:-3.3}
+    environment:
+      HISTFILE: /app/tmp/.bash_history
+      BUNDLE_PATH: /usr/local/bundle
+      BUNDLE_CONFIG: /app/.bundle/config
+    command: bash
+    working_dir: /app
+    volumes:
+      - .:/app:cached
+      - ${SBMT_RUBYGEMS_PATH:-..}:/app/vendor/gems:cached
+      - bundler_data:/usr/local/bundle
+
+  pact-broker:
+    image: pactfoundation/pact-broker
+    ports:
+      - 9292
+    environment:
+      PACT_BROKER_DATABASE_ADAPTER: sqlite
+      PACT_BROKER_DATABASE_NAME: pact_broker.sqlite
+      PACT_BROKER_LOG_LEVEL: DEBUG
+
+  pact-cli:
+    image: pactfoundation/pact-cli
+    working_dir: /app
+    depends_on:
+      - pact-broker
+    volumes:
+      - ./spec/internal/pacts:/app:cached
+
+volumes:
+  bundler_data:

data/lefthook-local.dip_example.yml

@@ -0,0 +1,4 @@
+pre-commit:
+  commands:
+    rubocop:
+      run: dip {cmd}

data/lefthook.yml

@@ -0,0 +1,6 @@
+pre-commit:
+  commands:
+    rubocop:
+      tags: backend
+      glob: "{*.rb,**/*.rb,Gemfile,Rakefile}"
+      run: bundle exec rubocop -A --force-exclusion {staged_files} && git add {staged_files}

data/lib/sbmt/pact/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Sbmt
+  module Pact
+    class Configuration
+      attr_reader :before_provider_state_proc, :after_provider_state_proc
+
+      class GlobalProviderConfigurationError < ::Sbmt::Pact::Error; end
+
+      def before_provider_state_setup(&block)
+        raise GlobalProviderConfigurationError, "no block given" unless block
+
+        @before_provider_state_proc = block
+      end
+
+      def after_provider_state_teardown(&block)
+        raise GlobalProviderConfigurationError, "no block given" unless block
+
+        @after_provider_state_proc = block
+      end
+    end
+  end
+end