InfoGrab DocsInfoGrab Docs

Ruby 컨슈머 컨트랙트 테스트 작성

요약

Ruby 네이티브 Pact 컨슈머 테스트는 Rails와 외부 서비스 간 경계(예를 들어 Rails 모놀리스가 Artifact Registry 관리 API를 호출하는 경우)를 다룹니다. 컨슈머가 Rails 모놀리스 자체일 때, 즉 Rails 서비스 클라이언트(예: ArtifactRegistry::Client)가 독립된 외부 서비스를 호출할 때 Ruby 컨슈머 테스트를 사용합니다.

Ruby 네이티브 Pact 컨슈머 테스트는 Rails와 외부 서비스 간 경계(예를 들어 Rails 모놀리스가 Artifact Registry 관리 API를 호출하는 경우)를 다룹니다. 이 테스트는 pact gem을 사용하며, 프런트엔드와 Rails API 간 경계에 사용하는 JavaScript 컨슈머 테스트와는 별개입니다.

Ruby 컨슈머 테스트를 사용하는 경우#

컨슈머가 Rails 모놀리스 자체일 때, 즉 Rails 서비스 클라이언트(예: ArtifactRegistry::Client)가 독립된 외부 서비스를 호출할 때 Ruby 컨슈머 테스트를 사용합니다. Rails와 서비스 간 경계를 JS 도구로 모델링하는 것은 의미상 올바르지 않습니다.

명명 규칙#

spec/contracts/consumer/external/와 spec/contracts/contracts/external/ 아래의 디렉터리 이름은 밑줄을 사용합니다 (예: artifact_registry/).

컨트랙트 파일 이름은 하이픈을 사용합니다 (예: gitlab-rails-artifact-registry-repositories-get.json).

GCS 경로 슬러그는 디렉터리 이름과 일치하도록 밑줄을 사용합니다 (예: gs://.../artifact_registry/18.0/...).

모든 컨트랙트 파일 이름은 다음 형식을 따릅니다.

gitlab-rails-<service>-<resource>-<method>.json

예: gitlab-rails-artifact-registry-repositories-get.json

모든 구성 요소는 Ruby 스타일 가이드 및 pact gem의 기본 파일 이름 동작과 일관되도록 소문자로 씁니다.

파일 이름은 ContractNameGenerator가 생성하며 하드코딩하지 않습니다.

require_relative '../helpers/contract_name_generator'

ContractNameGenerator.generate(
  provider: 'artifact-registry',
  resource: 'repositories',
  method:   'GET'
)
# => 'gitlab-rails-artifact-registry-repositories-get.json'

새 컨슈머 스펙 작성#

1. 스펙 파일에서 상수 정의#

각 스펙 파일은 Pact 구성과 RSpec.describe 레이블을 모두 결정하는 최상위 상수 네 개를 선언합니다.

CONSUMER_NAME = 'gitlab-rails'
PROVIDER_NAME = 'artifact-registry'  # hyphenated; used directly in the contract filename
RESOURCE      = 'repositories'       # the resource being tested
METHOD        = 'GET'                # HTTP method, upcased

2. 픽스처 파일 생성#

픽스처는 프로바이더 상태, 요청 형태, 예상 응답을 한곳에 담으므로 스펙은 오케스트레이션에만 집중할 수 있습니다.

# spec/contracts/consumer/external/fixtures/artifact_registry/index.rb
module ArtifactRegistry
  module Fixtures
    module Repositories
      module Index
        PROVIDER_STATE = 'a namespace with repositories exists'
        UPON_RECEIVING = 'a request for a list of artifact registry repositories'

        REQUEST = {
          method:  :get,
          path:    '/api/v1/my-namespace/repositories',
          query:   'limit=20',
          headers: { 'Accept' => 'application/json' }
        }.freeze

        RESPONSE = {
          status: 200,
          # ...
        }.freeze
      end
    end
  end
end

3. 리소스 파일 생성#

리소스 파일에는 HTTP 클라이언트 호출이 들어 있습니다. 처음에는 Faraday 자리 표시자입니다. 실제 서비스 클라이언트가 생기면 그것으로 교체합니다.

# spec/contracts/consumer/external/resources/artifact_registry/repositories.rb
module ArtifactRegistry
  module Resources
    module Repositories
      def self.list(slug:, base_url:)
        Faraday.new(url: base_url) do |conn|
          conn.headers['Accept'] = 'application/json'
        end.get("/api/v1/#{slug}/repositories", limit: 20)
      end
    end
  end
end

4. 스펙 작성#

스펙 파일은 얇습니다. 상수, 픽스처, 리소스를 연결하는 일만 합니다.

# spec/contracts/consumer/external/specs/artifact_registry/index_spec.rb
require 'pact/consumer/rspec'
require_relative '../../helpers/pact_helper'
require_relative '../../helpers/contract_name_generator'
require_relative '../../fixtures/artifact_registry/index'
require_relative '../../resources/artifact_registry/repositories'

# Constants are namespaced to avoid global constant pollution when multiple
# pact specs run in the same process.
module ArtifactRegistryIndexSpec
  CONSUMER_NAME = 'gitlab-rails'
  PROVIDER_NAME = 'artifact-registry'  # hyphenated; used directly in the contract filename
  RESOURCE      = 'repositories'
  METHOD        = 'GET'
  CONTRACT_DIR  = PactHelper.contract_dir(__dir__)
end

Pact.configure { |c| c.pact_dir = ArtifactRegistryIndexSpec::CONTRACT_DIR }

# pact-ruby has no DSL option to set a custom filename - it always writes
# <consumer>-<provider>.json. Use at_exit to rename after pact-ruby's own
# after(:suite) hook has finished writing the file.
at_exit do
  default_path = File.join(
    ArtifactRegistryIndexSpec::CONTRACT_DIR,
    "#{ArtifactRegistryIndexSpec::CONSUMER_NAME}-#{ArtifactRegistryIndexSpec::PROVIDER_NAME.downcase}.json"
  )
  target_path = File.join(
    ArtifactRegistryIndexSpec::CONTRACT_DIR,
    ContractNameGenerator.generate(
      provider: ArtifactRegistryIndexSpec::PROVIDER_NAME,
      resource: ArtifactRegistryIndexSpec::RESOURCE,
      method:   ArtifactRegistryIndexSpec::METHOD
    )
  )
  File.rename(default_path, target_path) if File.exist?(default_path)
end

Pact.service_consumer ArtifactRegistryIndexSpec::CONSUMER_NAME do
  has_pact_with ArtifactRegistryIndexSpec::PROVIDER_NAME do
    mock_service(:artifact_registry_service)
  end
end

RSpec.describe "#{ArtifactRegistryIndexSpec::METHOD} /api/v1/:slug/#{ArtifactRegistryIndexSpec::RESOURCE}",
               :pact, feature_category: :artifact_registry do
  # ...
end

컨슈머 테스트 실행#

특정 서비스의 스펙을 실행합니다.

bundle exec rspec spec/contracts/consumer/external/specs/artifact_registry/ --format documentation

스펙을 실행하면 spec/contracts/contracts/external/artifact_registry/에 컨트랙트 JSON 파일이 생성됩니다.

GCS에 컨트랙트 게시#

컨트랙트는 안정(stable) 브랜치에 푸시할 때마다 서비스별 CI job (예: publish-artifact-registry-consumer-contracts)이 자동으로 게시하므로, 컨트랙트는 백포트 변경 사항에 맞게 최신 상태로 유지됩니다. 각 job은 자신이 담당하는 서비스의 스펙만 실행한 다음 다음을 호출합니다.

ruby spec/contracts/consumer/scripts/upload_contracts_to_gcs.rb

새 서비스의 컨트랙트를 추가하려면 .gitlab/ci/contract-testing-ruby.gitlab-ci.yml의 패턴을 따라 새 CI job을 추가합니다. 업로더 스크립트는 변경하지 않아도 됩니다.

업로더는 다음 환경 변수를 읽습니다.

변수 필수 설명
GCS_BUCKET 예 버킷 이름입니다. 예: gitlab-rails-consumer-contracts
RAILS_CONSUMER_CONTRACT_GCS_BUCKET_KEY 예 GCS 서비스 계정 JSON 키 파일의 경로이거나 문자열로 된 JSON 키 내용입니다.
GITLAB_VERSION 로컬에서만 사용 버전 문자열입니다. 예: 18.0. CI에서는 CI_COMMIT_REF_NAME을 통해 안정 브랜치 이름에서 버전을 자동으로 추출합니다(예: 18-0-stable-ee → 18.0).

컨트랙트는 다음 위치에 업로드됩니다.

gs:///<service-slug>//<contract-filename>

예를 들면 다음과 같습니다.

gs://gitlab-rails-consumer-contracts/artifact_registry/18.0/gitlab-rails-artifact-registry-repositories-get.json

새 서비스의 컨트랙트를 추가하려면 spec/contracts/contracts/external/ 아래에 밑줄을 사용해 해당 하위 디렉터리를 만들고(예: artifact_registry/), 기존 패턴을 따라 .gitlab/ci/contract-testing-ruby.gitlab-ci.yml에 새 CI job을 추가합니다.

Ruby 컨슈머 컨트랙트 테스트 작성

GitLab v19.6
원문 보기

요약

Ruby 네이티브 Pact 컨슈머 테스트는 Rails와 외부 서비스 간 경계(예를 들어 Rails 모놀리스가 Artifact Registry 관리 API를 호출하는 경우)를 다룹니다. 컨슈머가 Rails 모놀리스 자체일 때, 즉 Rails 서비스 클라이언트(예: ArtifactRegistry::Client)가 독립된 외부 서비스를 호출할 때 Ruby 컨슈머 테스트를 사용합니다.

Ruby 네이티브 Pact 컨슈머 테스트는 Rails와 외부 서비스 간 경계(예를 들어 Rails 모놀리스가 Artifact Registry 관리 API를 호출하는 경우)를 다룹니다. 이 테스트는 pact gem을 사용하며, 프런트엔드와 Rails API 간 경계에 사용하는 JavaScript 컨슈머 테스트와는 별개입니다.

Ruby 컨슈머 테스트를 사용하는 경우#

컨슈머가 Rails 모놀리스 자체일 때, 즉 Rails 서비스 클라이언트(예: ArtifactRegistry::Client)가 독립된 외부 서비스를 호출할 때 Ruby 컨슈머 테스트를 사용합니다. Rails와 서비스 간 경계를 JS 도구로 모델링하는 것은 의미상 올바르지 않습니다.

명명 규칙#

spec/contracts/consumer/external/와 spec/contracts/contracts/external/ 아래의 디렉터리 이름은 밑줄을 사용합니다 (예: artifact_registry/).

컨트랙트 파일 이름은 하이픈을 사용합니다 (예: gitlab-rails-artifact-registry-repositories-get.json).

GCS 경로 슬러그는 디렉터리 이름과 일치하도록 밑줄을 사용합니다 (예: gs://.../artifact_registry/18.0/...).

모든 컨트랙트 파일 이름은 다음 형식을 따릅니다.

gitlab-rails-<service>-<resource>-<method>.json

예: gitlab-rails-artifact-registry-repositories-get.json

모든 구성 요소는 Ruby 스타일 가이드 및 pact gem의 기본 파일 이름 동작과 일관되도록 소문자로 씁니다.

파일 이름은 ContractNameGenerator가 생성하며 하드코딩하지 않습니다.

require_relative '../helpers/contract_name_generator'

ContractNameGenerator.generate(
  provider: 'artifact-registry',
  resource: 'repositories',
  method:   'GET'
)
# => 'gitlab-rails-artifact-registry-repositories-get.json'

새 컨슈머 스펙 작성#

1. 스펙 파일에서 상수 정의#

각 스펙 파일은 Pact 구성과 RSpec.describe 레이블을 모두 결정하는 최상위 상수 네 개를 선언합니다.

CONSUMER_NAME = 'gitlab-rails'
PROVIDER_NAME = 'artifact-registry'  # hyphenated; used directly in the contract filename
RESOURCE      = 'repositories'       # the resource being tested
METHOD        = 'GET'                # HTTP method, upcased

2. 픽스처 파일 생성#

픽스처는 프로바이더 상태, 요청 형태, 예상 응답을 한곳에 담으므로 스펙은 오케스트레이션에만 집중할 수 있습니다.

# spec/contracts/consumer/external/fixtures/artifact_registry/index.rb
module ArtifactRegistry
  module Fixtures
    module Repositories
      module Index
        PROVIDER_STATE = 'a namespace with repositories exists'
        UPON_RECEIVING = 'a request for a list of artifact registry repositories'

        REQUEST = {
          method:  :get,
          path:    '/api/v1/my-namespace/repositories',
          query:   'limit=20',
          headers: { 'Accept' => 'application/json' }
        }.freeze

        RESPONSE = {
          status: 200,
          # ...
        }.freeze
      end
    end
  end
end

3. 리소스 파일 생성#

리소스 파일에는 HTTP 클라이언트 호출이 들어 있습니다. 처음에는 Faraday 자리 표시자입니다. 실제 서비스 클라이언트가 생기면 그것으로 교체합니다.

# spec/contracts/consumer/external/resources/artifact_registry/repositories.rb
module ArtifactRegistry
  module Resources
    module Repositories
      def self.list(slug:, base_url:)
        Faraday.new(url: base_url) do |conn|
          conn.headers['Accept'] = 'application/json'
        end.get("/api/v1/#{slug}/repositories", limit: 20)
      end
    end
  end
end

4. 스펙 작성#

스펙 파일은 얇습니다. 상수, 픽스처, 리소스를 연결하는 일만 합니다.

# spec/contracts/consumer/external/specs/artifact_registry/index_spec.rb
require 'pact/consumer/rspec'
require_relative '../../helpers/pact_helper'
require_relative '../../helpers/contract_name_generator'
require_relative '../../fixtures/artifact_registry/index'
require_relative '../../resources/artifact_registry/repositories'

# Constants are namespaced to avoid global constant pollution when multiple
# pact specs run in the same process.
module ArtifactRegistryIndexSpec
  CONSUMER_NAME = 'gitlab-rails'
  PROVIDER_NAME = 'artifact-registry'  # hyphenated; used directly in the contract filename
  RESOURCE      = 'repositories'
  METHOD        = 'GET'
  CONTRACT_DIR  = PactHelper.contract_dir(__dir__)
end

Pact.configure { |c| c.pact_dir = ArtifactRegistryIndexSpec::CONTRACT_DIR }

# pact-ruby has no DSL option to set a custom filename - it always writes
# <consumer>-<provider>.json. Use at_exit to rename after pact-ruby's own
# after(:suite) hook has finished writing the file.
at_exit do
  default_path = File.join(
    ArtifactRegistryIndexSpec::CONTRACT_DIR,
    "#{ArtifactRegistryIndexSpec::CONSUMER_NAME}-#{ArtifactRegistryIndexSpec::PROVIDER_NAME.downcase}.json"
  )
  target_path = File.join(
    ArtifactRegistryIndexSpec::CONTRACT_DIR,
    ContractNameGenerator.generate(
      provider: ArtifactRegistryIndexSpec::PROVIDER_NAME,
      resource: ArtifactRegistryIndexSpec::RESOURCE,
      method:   ArtifactRegistryIndexSpec::METHOD
    )
  )
  File.rename(default_path, target_path) if File.exist?(default_path)
end

Pact.service_consumer ArtifactRegistryIndexSpec::CONSUMER_NAME do
  has_pact_with ArtifactRegistryIndexSpec::PROVIDER_NAME do
    mock_service(:artifact_registry_service)
  end
end

RSpec.describe "#{ArtifactRegistryIndexSpec::METHOD} /api/v1/:slug/#{ArtifactRegistryIndexSpec::RESOURCE}",
               :pact, feature_category: :artifact_registry do
  # ...
end

컨슈머 테스트 실행#

특정 서비스의 스펙을 실행합니다.

bundle exec rspec spec/contracts/consumer/external/specs/artifact_registry/ --format documentation

스펙을 실행하면 spec/contracts/contracts/external/artifact_registry/에 컨트랙트 JSON 파일이 생성됩니다.

GCS에 컨트랙트 게시#

컨트랙트는 안정(stable) 브랜치에 푸시할 때마다 서비스별 CI job (예: publish-artifact-registry-consumer-contracts)이 자동으로 게시하므로, 컨트랙트는 백포트 변경 사항에 맞게 최신 상태로 유지됩니다. 각 job은 자신이 담당하는 서비스의 스펙만 실행한 다음 다음을 호출합니다.

ruby spec/contracts/consumer/scripts/upload_contracts_to_gcs.rb

새 서비스의 컨트랙트를 추가하려면 .gitlab/ci/contract-testing-ruby.gitlab-ci.yml의 패턴을 따라 새 CI job을 추가합니다. 업로더 스크립트는 변경하지 않아도 됩니다.

업로더는 다음 환경 변수를 읽습니다.

변수 필수 설명
GCS_BUCKET 예 버킷 이름입니다. 예: gitlab-rails-consumer-contracts
RAILS_CONSUMER_CONTRACT_GCS_BUCKET_KEY 예 GCS 서비스 계정 JSON 키 파일의 경로이거나 문자열로 된 JSON 키 내용입니다.
GITLAB_VERSION 로컬에서만 사용 버전 문자열입니다. 예: 18.0. CI에서는 CI_COMMIT_REF_NAME을 통해 안정 브랜치 이름에서 버전을 자동으로 추출합니다(예: 18-0-stable-ee → 18.0).

컨트랙트는 다음 위치에 업로드됩니다.

gs:///<service-slug>//<contract-filename>

예를 들면 다음과 같습니다.

gs://gitlab-rails-consumer-contracts/artifact_registry/18.0/gitlab-rails-artifact-registry-repositories-get.json

새 서비스의 컨트랙트를 추가하려면 spec/contracts/contracts/external/ 아래에 밑줄을 사용해 해당 하위 디렉터리를 만들고(예: artifact_registry/), 기존 패턴을 따라 .gitlab/ci/contract-testing-ruby.gitlab-ci.yml에 새 CI job을 추가합니다.