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을 추가합니다.