InfoGrab DocsInfoGrab Docs

기능 스펙에서 프런트엔드 및 백엔드 Snowplow 이벤트 캡처

요약

expect_snowplow_event는 Gitlab::Tracking.event에 대한 목(mock)입니다. 모든 스펙은 stub_snowplow를 호출하며, 이 호출은 브라우저의 Snowplow 트래커를 localhost로 향하게 합니다.

expect_snowplow_event는 Gitlab::Tracking.event에 대한 목(mock)입니다. 실제 페이로드를 검사하지 않으며 브라우저가 보내는 어떤 것도 볼 수 없으므로, 프런트엔드 Snowplow 이벤트는 스펙에서 전혀 검증할 수 없었습니다. 기능 스펙을 위해 만든 이 메커니즘은 GitLab이 백엔드와 브라우저 양쪽에서 내보내는 실제 페이로드를 캡처합니다.

프런트엔드 이벤트가 보이지 않던 이유#

모든 스펙은 stub_snowplow를 호출하며, 이 호출은 브라우저의 Snowplow 트래커를 localhost로 향하게 합니다. 테스트 환경에서는 그곳에서 수신하는 것이 없으므로, 프런트엔드가 발생시킨 이벤트는 올바르게 내보내지지만 전달될 곳이 없습니다.

캡처 동작 방식#

:capture_snowplow_events 태그가 지정된 스펙은 브라우저 트래커의 수집기 호스트 이름을 스펙이 이미 실행 중인 Capybara 서버로 향하게 합니다. 테스트 환경에 등록된 Rack 미들웨어(Gitlab::Testing::SnowplowCollectorMiddleware)가 해당 수집기 경로에 응답하고 모든 페이로드를 기록합니다. 백엔드 이벤트는 기존 테스트 이미터를 통해 계속 전달됩니다. 둘 다 같은 버퍼에 쌓이므로, 스펙은 출처와 관계없이 한곳에서 이벤트를 읽습니다.

이 방식은 실제 브라우저와 Capybara 서버에 의존하므로, 태그에는 :js가 필요하며 없으면 명확한 오류를 발생시킵니다. 추적에 대해 아무것도 검증하지 않는 예제가 설정 비용을 부담하지 않도록, :capture_snowplow_events는 둘러싼 describe 또는 context 블록이 아니라 개별 예제에 지정합니다.

이벤트 버퍼는 태그가 지정된 각 예제 전에 생성되고 예제 후에 폐기되므로, 한 예제의 이벤트가 다른 예제에 보이는 일은 없습니다. 검증하는 내용은 단일 예제 안에서 충족할 수 있어야 합니다.

Note

expect_snowplow_event는 :capture_snowplow_events 예제에서 동작하지 않습니다. 이 메서드는 stub_snowplow가 allow(Gitlab::Tracking).to receive(:event)로 설치하는 스파이에 대해 검증하지만, :capture_snowplow_events 태그는 수집기 호스트 이름을 직접 제어해야 하므로 의도적으로 stub_snowplow를 건너뜁니다. 스파이가 없으면 expect_snowplow_event는 추적과 관련된 내용이 아니라 객체가 스파이가 아니라는 오류로 실패합니다. 대신 이 페이지의 헬퍼를 사용합니다. 기존 스펙을 이벤트 캡처를 사용하도록 변환할 때 특히 중요합니다.

이벤트를 직접 검증#

일회성 확인에는 다음 헬퍼를 직접 사용합니다.

  • captured_snowplow_events는 지금까지 캡처된 모든 항목을 SnowplowEvent 구조체로 반환합니다.
  • find_snowplow_event(**attributes)는 기다리지 않고 첫 번째 일치 항목을 반환하며, 없으면 nil을 반환합니다.
  • wait_for_snowplow_event(**attributes)는 일치 항목이 나타날 때까지 폴링한 다음 그것을 반환합니다.

SnowplowEvent에는 다음 리더가 있습니다. event_type, category, action, label, property, platform, experiment_context입니다.

platform은 Snowplow 자체가 정의한 필드입니다. 브라우저 이벤트는 "web", 백엔드 이벤트는 "srv"이며, 이 값으로 둘을 구별합니다. event_type은 Snowplow의 e 필드입니다. 구조화된 이벤트는 "se", 페이지 뷰는 "pv"입니다.

event_type: 'pv'로 페이지 뷰를 일치시킬 수는 있지만, 어느 페이지였는지는 검증할 수 없습니다. URL은 캡처되지 않습니다.

프런트엔드 이벤트는 수집기에 비동기로 POST되므로, 이벤트가 아직 도착하지 않았을 수 있으면 find_snowplow_event보다 wait_for_snowplow_event를 사용합니다. 이 헬퍼는 최대 Capybara.default_max_wait_time(로컬에서는 10초, CI에서는 30초) 동안 폴링하며, 실패하면 캡처된 모든 이벤트를 출력합니다.

속성 값은 케이스 동등(===)으로 비교되므로, 리터럴 문자열뿐 아니라 include(...) 같은 RSpec 매처나 정규식도 전달할 수 있습니다.

it 'tracks the upgrade banner dismissal', :js, :capture_snowplow_events do
  click_button 'Dismiss'

  event = wait_for_snowplow_event(action: 'dismiss_upgrade_banner')

  expect(event.property).to include('trial')
end

추적 여정 계약 검증#

스펙에 인라인으로 작성한 검증은 그 스펙이 삭제되거나 다시 작성되는 날 사라지며, 이벤트 집합이 계속 발생한다는 보장도 함께 사라집니다. 추적 여정 계약은 이를 방지합니다. 여정의 이름을 딴 spec/fixtures/snowplow_tracking_journeys/ 아래의 YAML 파일로, 여정이 내보내야 하는 이벤트를 선언합니다. 계약은 개별 스펙보다 오래 유지되며, 여정을 진행하는 Ruby 코드를 읽지 않고도 이해할 수 있습니다.

파일 이름은 검증에 사용하는 인수와 직접 대응합니다. spec/fixtures/snowplow_tracking_journeys/invite_registration.yml의 계약은 expect_snowplow_tracking_journey('invite_registration')로 검증하며, 이 호출은 선언된 모든 이벤트를 차례로 기다립니다.

전체 스펙은 다음과 같습니다.

RSpec.describe 'SaaS registration from an invite', :js, :saas_registration, feature_category: :onboarding do
  let_it_be(:group) { create(:group, name: 'Test Group') }

  it 'registers the user and sends them to the group page', :capture_snowplow_events do
    registers_from_invite(group: group)
    fill_in_welcome_form
    click_on 'Get started!'

    expect_snowplow_tracking_journey('invite_registration')
  end
end

이벤트를 발생시키는 상호 작용 뒤에 검증을 마지막으로 두어, 선언된 모든 이벤트가 발생할 기회를 가지도록 합니다.

계약은 다음과 같습니다.

---
description: |
  What this journey is, and why these events matter.

events:
  - category: InvitesController
    action: join_clicked
    label: invite_email

  - category: registrations:new
    action: register
    label: invite_registration

나열한 필드만 확인하므로, 계약은 여정에 필요한 만큼 느슨하게도 엄격하게도 작성할 수 있습니다. 여정 중에 발생하지만 선언되지 않은 이벤트는 허용됩니다. 계약은 선언된 이벤트가 발생한다는 것만 보장하며, 다른 이벤트가 발생하지 않는다는 것은 보장하지 않습니다.

발생하는 이벤트 찾기#

이벤트 이름과 카테고리를 추측하지 않습니다. 특히 프런트엔드 카테고리는 이벤트가 발생한 페이지이며, 추측하는 값과 다른 경우가 많습니다.

대신 실패한 검증이 알려 주도록 합니다.

  1. 여정에 필요한 상호 작용으로 스펙을 작성하고, 확실하게 알고 있는 이벤트 하나를 선언한 계약을 검증합니다.
  2. 스펙을 실행합니다. 이벤트를 찾지 못하면 실패 메시지에 실행 중 캡처된 모든 이벤트가 카테고리, 액션, 레이블, 속성, 실험 컨텍스트와 함께 출력됩니다.
  3. 중요한 이벤트를 계약에 복사하고, 조직 폴백이나 일반 활동 이벤트 같은 부수적인 이벤트는 제외합니다.

실험#

계약은 실험의 이름을 지정하고 variants: 아래에 실험군을 선언할 수 있습니다. 이 예시의 이름은 설명을 위한 것입니다.

---
experiment: my_experiment
description: |
  ...

variants:
  candidate:
    events:
      - category: my_experiment
        action: assignment

      - action: click_call_to_action

      - category: my_experiment
        action: finish_signup

  control:
    events:
      - category: my_experiment
        action: assignment

      - action: click_call_to_action

      - category: my_experiment
        action: finish_signup

한 번에 하나의 실험군을 variant:로 검증합니다.

expect_snowplow_tracking_journey('my_experiment', variant: variant)

experiment:가 설정되면, 검증 중인 실험군에 선언된 모든 이벤트는 주어진 변형에 대해 해당 실험의 컨텍스트를 추가로 포함해야 하므로, 이벤트마다 컨텍스트를 반복해서 쓸 필요가 없습니다.

실험 이벤트는 category가 아니라 그 컨텍스트로 일치시킵니다. 백엔드 실험 이벤트는 실험 이름을 카테고리로 사용하지만, 프런트엔드 이벤트는 root:index처럼 이벤트가 발생한 페이지로 분류됩니다. 컨텍스트는 두 종류의 이벤트가 모두 가지고 있는 유일한 필드입니다.

variants:는 임시로 사용하도록 만들어졌습니다. 실험을 정리한 후 우승한 실험군의 이벤트를 최상위 events: 키로 옮기고 experiment:와 variants:를 삭제하여 영구적인 여정 계약을 남깁니다.

발생할 수 있는 오류#

스펙이나 계약이 잘못 구성되면 expect_snowplow_tracking_journey는 ArgumentError를 발생시킵니다. 각 오류는 제품의 문제가 아니라 스펙이나 YAML 파일에서 고쳐야 할 부분이 있다는 뜻입니다.

메시지 의미
No tracking journey named '' in 해당 이름의 계약 파일이 없습니다.
declares no variants, drop variant: variants: 섹션이 없는 계약에 variant:를 전달했습니다.
declares variants a, b, pass one 계약에 실험군이 있으므로 variant:로 어느 것인지 지정해야 합니다.
has no variant '', only a, b 전달한 실험군 이름이 계약의 어떤 실험군과도 일치하지 않습니다.
declares no events to assert 계약 또는 선택한 실험군에 선언된 이벤트가 없으므로, 아무것도 확인하지 않고 검증이 통과합니다.

스펙이 캡처한 이벤트 읽기#

:capture_snowplow_events 태그가 지정된 모든 예제는 예제 자체에서 검증하는 내용 외에도 캡처한 내용을 디스크에 기록합니다. 추가 설정은 필요하지 않습니다. 로컬에서는 덤프가 tmp/captured_snowplow_events/ 아래에 저장됩니다. CI에서는 rspec/captured_snowplow_events/ 아래에 저장되며, .gitlab/ci/rails/shared.gitlab-ci.yml의 .artifact-base 앵커가 이 디렉터리를 포함하므로 테스트 잡이 이를 잡 아티팩트로 수집합니다. 아티팩트는 31일 후에 만료됩니다.

각 예제는 RSpec 예제 ID를 딴 자체 디렉터리를 가지며, 이 ID는 스펙 파일 경로에 예제의 범위 지정 위치를 더한 값입니다(예: 1-1-1-1). 설명은 고유하지 않으므로 설명 대신 ID를 사용합니다. 공유 예제는 실행되는 모든 컨텍스트에 같은 설명을 가져가므로, 그렇지 않으면 실험의 두 실험군이 같은 디렉터리에서 충돌합니다.

tmp/captured_snowplow_events/
  index.json
  ee/spec/features/experiments/my_experiment_events_spec/
    1-1-1-1/   events.yml  payloads.json
    1-2-1-1/   events.yml  payloads.json

각 예제 디렉터리에는 두 파일이 있습니다.

  • events.yml은 구조화된 이벤트를 추적 여정 계약과 같은 형태로 담으며, 중복을 제거하고 이벤트에 없던 필드는 제외합니다. 헤더 주석에는 예제 설명, 파일과 줄, UTC 타임스탬프, 그리고 계약으로 표현할 수 없는 페이지 뷰와 자기 기술(self-describing) 이벤트의 개수가 기록됩니다.
  • payloads.json은 수집기에 POST되었을 원시 페이로드를 그대로 담습니다.
# Captured from: My experiment when assigned the candidate variant ...
# ./ee/spec/features/experiments/my_experiment_events_spec.rb:16 at 2026-09-02T08:28:00Z
#
# Frontend categories are the page an event fired on, so they are rarely worth asserting.
# Also captured, not expressible in a contract: 1 page view, 1 self-describing event
---
events:
- category: my_experiment
  action: assignment
- category: root:index
  action: click_call_to_action

루트에 있는 index.json은 예제별로 항목 하나씩, 각 예제의 덤프를 그것이 증명하는 추적 여정과 변형에 매핑하므로, 어떤 스펙이 생성했는지 몰라도 실험 이름으로 덤프를 찾을 수 있습니다. 여정을 검증하지 않고 이벤트를 캡처한 예제나 여정 검증에 실패한 예제는 "journey": null로 나열됩니다. 성공한 항목은 다음과 같습니다.

{
  "journey": "my_experiment",
  "variant": "candidate",
  "events": "ee/spec/features/experiments/my_experiment_events_spec/1-1-1-1/events.yml",
  "payloads": "ee/spec/features/experiments/my_experiment_events_spec/1-1-1-1/payloads.json"
}

예제를 다시 실행하면 해당 디렉터리가 교체되므로, 디스크의 내용은 항상 가장 최근 실행의 결과입니다.

이 덕분에 실험 이벤트의 증거를 롤아웃 이슈에 게시할 때 Docker에서 Snowplow Micro를 실행하고 UI에서 이벤트를 수동으로 복사할 필요가 없어집니다. events.yml의 내용을 이슈에 붙여 넣습니다.

각 CI 잡은 그 안에서 실행된 예제만 기록하므로, 덤프는 병렬 rspec system 및 rspec-ee system 잡에 분산되고 각 index.json은 단일 잡만 다룹니다. 올바른 샤드를 찾는 데는 스펙을 직접 실행하는 것보다 시간이 오래 걸리므로, 롤아웃 증거를 수집할 때는 보통 로컬 실행이 더 빠릅니다.

범위와 제한#

  • 이 방식은 애플리케이션이 실제로 내보내는 페이로드를 증명합니다. 캡처는 HTTP POST 직전의 마지막 지점에서 이루어지므로, 재구성한 것이 아니라 실제 페이로드입니다.
  • 수집기가 실행되지 않으므로 이벤트 컨텍스트는 Iglu 스키마 레지스트리에 대해 검증되지 않습니다. 검증이 필요하면 Snowplow Micro를 사용합니다. 로컬 설정 및 디버깅을 참조합니다.
  • 계약은 이벤트가 프런트엔드인지 백엔드인지 기록하지 않으므로, 둘 사이를 오가는 이벤트도 계약을 계속 충족합니다.

기능 스펙에서 프런트엔드 및 백엔드 Snowplow 이벤트 캡처

GitLab v19.6
원문 보기

요약

expect_snowplow_event는 Gitlab::Tracking.event에 대한 목(mock)입니다. 모든 스펙은 stub_snowplow를 호출하며, 이 호출은 브라우저의 Snowplow 트래커를 localhost로 향하게 합니다.

expect_snowplow_event는 Gitlab::Tracking.event에 대한 목(mock)입니다. 실제 페이로드를 검사하지 않으며 브라우저가 보내는 어떤 것도 볼 수 없으므로, 프런트엔드 Snowplow 이벤트는 스펙에서 전혀 검증할 수 없었습니다. 기능 스펙을 위해 만든 이 메커니즘은 GitLab이 백엔드와 브라우저 양쪽에서 내보내는 실제 페이로드를 캡처합니다.

프런트엔드 이벤트가 보이지 않던 이유#

모든 스펙은 stub_snowplow를 호출하며, 이 호출은 브라우저의 Snowplow 트래커를 localhost로 향하게 합니다. 테스트 환경에서는 그곳에서 수신하는 것이 없으므로, 프런트엔드가 발생시킨 이벤트는 올바르게 내보내지지만 전달될 곳이 없습니다.

캡처 동작 방식#

:capture_snowplow_events 태그가 지정된 스펙은 브라우저 트래커의 수집기 호스트 이름을 스펙이 이미 실행 중인 Capybara 서버로 향하게 합니다. 테스트 환경에 등록된 Rack 미들웨어(Gitlab::Testing::SnowplowCollectorMiddleware)가 해당 수집기 경로에 응답하고 모든 페이로드를 기록합니다. 백엔드 이벤트는 기존 테스트 이미터를 통해 계속 전달됩니다. 둘 다 같은 버퍼에 쌓이므로, 스펙은 출처와 관계없이 한곳에서 이벤트를 읽습니다.

이 방식은 실제 브라우저와 Capybara 서버에 의존하므로, 태그에는 :js가 필요하며 없으면 명확한 오류를 발생시킵니다. 추적에 대해 아무것도 검증하지 않는 예제가 설정 비용을 부담하지 않도록, :capture_snowplow_events는 둘러싼 describe 또는 context 블록이 아니라 개별 예제에 지정합니다.

이벤트 버퍼는 태그가 지정된 각 예제 전에 생성되고 예제 후에 폐기되므로, 한 예제의 이벤트가 다른 예제에 보이는 일은 없습니다. 검증하는 내용은 단일 예제 안에서 충족할 수 있어야 합니다.

Note

expect_snowplow_event는 :capture_snowplow_events 예제에서 동작하지 않습니다. 이 메서드는 stub_snowplow가 allow(Gitlab::Tracking).to receive(:event)로 설치하는 스파이에 대해 검증하지만, :capture_snowplow_events 태그는 수집기 호스트 이름을 직접 제어해야 하므로 의도적으로 stub_snowplow를 건너뜁니다. 스파이가 없으면 expect_snowplow_event는 추적과 관련된 내용이 아니라 객체가 스파이가 아니라는 오류로 실패합니다. 대신 이 페이지의 헬퍼를 사용합니다. 기존 스펙을 이벤트 캡처를 사용하도록 변환할 때 특히 중요합니다.

이벤트를 직접 검증#

일회성 확인에는 다음 헬퍼를 직접 사용합니다.

  • captured_snowplow_events는 지금까지 캡처된 모든 항목을 SnowplowEvent 구조체로 반환합니다.
  • find_snowplow_event(**attributes)는 기다리지 않고 첫 번째 일치 항목을 반환하며, 없으면 nil을 반환합니다.
  • wait_for_snowplow_event(**attributes)는 일치 항목이 나타날 때까지 폴링한 다음 그것을 반환합니다.

SnowplowEvent에는 다음 리더가 있습니다. event_type, category, action, label, property, platform, experiment_context입니다.

platform은 Snowplow 자체가 정의한 필드입니다. 브라우저 이벤트는 "web", 백엔드 이벤트는 "srv"이며, 이 값으로 둘을 구별합니다. event_type은 Snowplow의 e 필드입니다. 구조화된 이벤트는 "se", 페이지 뷰는 "pv"입니다.

event_type: 'pv'로 페이지 뷰를 일치시킬 수는 있지만, 어느 페이지였는지는 검증할 수 없습니다. URL은 캡처되지 않습니다.

프런트엔드 이벤트는 수집기에 비동기로 POST되므로, 이벤트가 아직 도착하지 않았을 수 있으면 find_snowplow_event보다 wait_for_snowplow_event를 사용합니다. 이 헬퍼는 최대 Capybara.default_max_wait_time(로컬에서는 10초, CI에서는 30초) 동안 폴링하며, 실패하면 캡처된 모든 이벤트를 출력합니다.

속성 값은 케이스 동등(===)으로 비교되므로, 리터럴 문자열뿐 아니라 include(...) 같은 RSpec 매처나 정규식도 전달할 수 있습니다.

it 'tracks the upgrade banner dismissal', :js, :capture_snowplow_events do
  click_button 'Dismiss'

  event = wait_for_snowplow_event(action: 'dismiss_upgrade_banner')

  expect(event.property).to include('trial')
end

추적 여정 계약 검증#

스펙에 인라인으로 작성한 검증은 그 스펙이 삭제되거나 다시 작성되는 날 사라지며, 이벤트 집합이 계속 발생한다는 보장도 함께 사라집니다. 추적 여정 계약은 이를 방지합니다. 여정의 이름을 딴 spec/fixtures/snowplow_tracking_journeys/ 아래의 YAML 파일로, 여정이 내보내야 하는 이벤트를 선언합니다. 계약은 개별 스펙보다 오래 유지되며, 여정을 진행하는 Ruby 코드를 읽지 않고도 이해할 수 있습니다.

파일 이름은 검증에 사용하는 인수와 직접 대응합니다. spec/fixtures/snowplow_tracking_journeys/invite_registration.yml의 계약은 expect_snowplow_tracking_journey('invite_registration')로 검증하며, 이 호출은 선언된 모든 이벤트를 차례로 기다립니다.

전체 스펙은 다음과 같습니다.

RSpec.describe 'SaaS registration from an invite', :js, :saas_registration, feature_category: :onboarding do
  let_it_be(:group) { create(:group, name: 'Test Group') }

  it 'registers the user and sends them to the group page', :capture_snowplow_events do
    registers_from_invite(group: group)
    fill_in_welcome_form
    click_on 'Get started!'

    expect_snowplow_tracking_journey('invite_registration')
  end
end

이벤트를 발생시키는 상호 작용 뒤에 검증을 마지막으로 두어, 선언된 모든 이벤트가 발생할 기회를 가지도록 합니다.

계약은 다음과 같습니다.

---
description: |
  What this journey is, and why these events matter.

events:
  - category: InvitesController
    action: join_clicked
    label: invite_email

  - category: registrations:new
    action: register
    label: invite_registration

나열한 필드만 확인하므로, 계약은 여정에 필요한 만큼 느슨하게도 엄격하게도 작성할 수 있습니다. 여정 중에 발생하지만 선언되지 않은 이벤트는 허용됩니다. 계약은 선언된 이벤트가 발생한다는 것만 보장하며, 다른 이벤트가 발생하지 않는다는 것은 보장하지 않습니다.

발생하는 이벤트 찾기#

이벤트 이름과 카테고리를 추측하지 않습니다. 특히 프런트엔드 카테고리는 이벤트가 발생한 페이지이며, 추측하는 값과 다른 경우가 많습니다.

대신 실패한 검증이 알려 주도록 합니다.

  1. 여정에 필요한 상호 작용으로 스펙을 작성하고, 확실하게 알고 있는 이벤트 하나를 선언한 계약을 검증합니다.
  2. 스펙을 실행합니다. 이벤트를 찾지 못하면 실패 메시지에 실행 중 캡처된 모든 이벤트가 카테고리, 액션, 레이블, 속성, 실험 컨텍스트와 함께 출력됩니다.
  3. 중요한 이벤트를 계약에 복사하고, 조직 폴백이나 일반 활동 이벤트 같은 부수적인 이벤트는 제외합니다.

실험#

계약은 실험의 이름을 지정하고 variants: 아래에 실험군을 선언할 수 있습니다. 이 예시의 이름은 설명을 위한 것입니다.

---
experiment: my_experiment
description: |
  ...

variants:
  candidate:
    events:
      - category: my_experiment
        action: assignment

      - action: click_call_to_action

      - category: my_experiment
        action: finish_signup

  control:
    events:
      - category: my_experiment
        action: assignment

      - action: click_call_to_action

      - category: my_experiment
        action: finish_signup

한 번에 하나의 실험군을 variant:로 검증합니다.

expect_snowplow_tracking_journey('my_experiment', variant: variant)

experiment:가 설정되면, 검증 중인 실험군에 선언된 모든 이벤트는 주어진 변형에 대해 해당 실험의 컨텍스트를 추가로 포함해야 하므로, 이벤트마다 컨텍스트를 반복해서 쓸 필요가 없습니다.

실험 이벤트는 category가 아니라 그 컨텍스트로 일치시킵니다. 백엔드 실험 이벤트는 실험 이름을 카테고리로 사용하지만, 프런트엔드 이벤트는 root:index처럼 이벤트가 발생한 페이지로 분류됩니다. 컨텍스트는 두 종류의 이벤트가 모두 가지고 있는 유일한 필드입니다.

variants:는 임시로 사용하도록 만들어졌습니다. 실험을 정리한 후 우승한 실험군의 이벤트를 최상위 events: 키로 옮기고 experiment:와 variants:를 삭제하여 영구적인 여정 계약을 남깁니다.

발생할 수 있는 오류#

스펙이나 계약이 잘못 구성되면 expect_snowplow_tracking_journey는 ArgumentError를 발생시킵니다. 각 오류는 제품의 문제가 아니라 스펙이나 YAML 파일에서 고쳐야 할 부분이 있다는 뜻입니다.

메시지 의미
No tracking journey named '' in 해당 이름의 계약 파일이 없습니다.
declares no variants, drop variant: variants: 섹션이 없는 계약에 variant:를 전달했습니다.
declares variants a, b, pass one 계약에 실험군이 있으므로 variant:로 어느 것인지 지정해야 합니다.
has no variant '', only a, b 전달한 실험군 이름이 계약의 어떤 실험군과도 일치하지 않습니다.
declares no events to assert 계약 또는 선택한 실험군에 선언된 이벤트가 없으므로, 아무것도 확인하지 않고 검증이 통과합니다.

스펙이 캡처한 이벤트 읽기#

:capture_snowplow_events 태그가 지정된 모든 예제는 예제 자체에서 검증하는 내용 외에도 캡처한 내용을 디스크에 기록합니다. 추가 설정은 필요하지 않습니다. 로컬에서는 덤프가 tmp/captured_snowplow_events/ 아래에 저장됩니다. CI에서는 rspec/captured_snowplow_events/ 아래에 저장되며, .gitlab/ci/rails/shared.gitlab-ci.yml의 .artifact-base 앵커가 이 디렉터리를 포함하므로 테스트 잡이 이를 잡 아티팩트로 수집합니다. 아티팩트는 31일 후에 만료됩니다.

각 예제는 RSpec 예제 ID를 딴 자체 디렉터리를 가지며, 이 ID는 스펙 파일 경로에 예제의 범위 지정 위치를 더한 값입니다(예: 1-1-1-1). 설명은 고유하지 않으므로 설명 대신 ID를 사용합니다. 공유 예제는 실행되는 모든 컨텍스트에 같은 설명을 가져가므로, 그렇지 않으면 실험의 두 실험군이 같은 디렉터리에서 충돌합니다.

tmp/captured_snowplow_events/
  index.json
  ee/spec/features/experiments/my_experiment_events_spec/
    1-1-1-1/   events.yml  payloads.json
    1-2-1-1/   events.yml  payloads.json

각 예제 디렉터리에는 두 파일이 있습니다.

  • events.yml은 구조화된 이벤트를 추적 여정 계약과 같은 형태로 담으며, 중복을 제거하고 이벤트에 없던 필드는 제외합니다. 헤더 주석에는 예제 설명, 파일과 줄, UTC 타임스탬프, 그리고 계약으로 표현할 수 없는 페이지 뷰와 자기 기술(self-describing) 이벤트의 개수가 기록됩니다.
  • payloads.json은 수집기에 POST되었을 원시 페이로드를 그대로 담습니다.
# Captured from: My experiment when assigned the candidate variant ...
# ./ee/spec/features/experiments/my_experiment_events_spec.rb:16 at 2026-09-02T08:28:00Z
#
# Frontend categories are the page an event fired on, so they are rarely worth asserting.
# Also captured, not expressible in a contract: 1 page view, 1 self-describing event
---
events:
- category: my_experiment
  action: assignment
- category: root:index
  action: click_call_to_action

루트에 있는 index.json은 예제별로 항목 하나씩, 각 예제의 덤프를 그것이 증명하는 추적 여정과 변형에 매핑하므로, 어떤 스펙이 생성했는지 몰라도 실험 이름으로 덤프를 찾을 수 있습니다. 여정을 검증하지 않고 이벤트를 캡처한 예제나 여정 검증에 실패한 예제는 "journey": null로 나열됩니다. 성공한 항목은 다음과 같습니다.

{
  "journey": "my_experiment",
  "variant": "candidate",
  "events": "ee/spec/features/experiments/my_experiment_events_spec/1-1-1-1/events.yml",
  "payloads": "ee/spec/features/experiments/my_experiment_events_spec/1-1-1-1/payloads.json"
}

예제를 다시 실행하면 해당 디렉터리가 교체되므로, 디스크의 내용은 항상 가장 최근 실행의 결과입니다.

이 덕분에 실험 이벤트의 증거를 롤아웃 이슈에 게시할 때 Docker에서 Snowplow Micro를 실행하고 UI에서 이벤트를 수동으로 복사할 필요가 없어집니다. events.yml의 내용을 이슈에 붙여 넣습니다.

각 CI 잡은 그 안에서 실행된 예제만 기록하므로, 덤프는 병렬 rspec system 및 rspec-ee system 잡에 분산되고 각 index.json은 단일 잡만 다룹니다. 올바른 샤드를 찾는 데는 스펙을 직접 실행하는 것보다 시간이 오래 걸리므로, 롤아웃 증거를 수집할 때는 보통 로컬 실행이 더 빠릅니다.

범위와 제한#

  • 이 방식은 애플리케이션이 실제로 내보내는 페이로드를 증명합니다. 캡처는 HTTP POST 직전의 마지막 지점에서 이루어지므로, 재구성한 것이 아니라 실제 페이로드입니다.
  • 수집기가 실행되지 않으므로 이벤트 컨텍스트는 Iglu 스키마 레지스트리에 대해 검증되지 않습니다. 검증이 필요하면 Snowplow Micro를 사용합니다. 로컬 설정 및 디버깅을 참조합니다.
  • 계약은 이벤트가 프런트엔드인지 백엔드인지 기록하지 않으므로, 둘 사이를 오가는 이벤트도 계약을 계속 충족합니다.