첫 관리형 테스트 실행

이 안내는 함께 제공되는 Order Desk 애플리케이션을 사용합니다. 실제 결제 게이트웨이를 호출하지 않고 구현된 결제 mock과 함께 HTTP 애플리케이션을 Docker에서 실행합니다. 실행 중인 서버와 연결된 에이전트, Compose를 포함한 Docker가 필요합니다.

직접 개발하는 애플리케이션에는 프로젝트 설정을 완료한 뒤 예제 경로와 테스트 파일을 작성한 값으로 바꿔 적용하세요.

예제 확인

예제는 Redpact 체크아웃의 examples/order-desk에 있습니다. 도구 호출에는 /absolute/path/to/redpact/examples/order-desk처럼 절대 경로를 사용하세요.

예제 설정은 compose.yaml을 참조하고 payments의 고정 mock 의존성을 정의하며 테스트에 서비스 연결을 제공합니다. tests/http.test.js는 결제 요청이 HTTP 200과 함께 quantity: 1, totalCents: 250을 반환하는지 검증합니다. 로컬 픽스처가 관리형 서비스 주소를 확인하므로 할당된 호스트 포트를 추측할 필요가 없습니다.

같은 인스턴스에서 CLI로 예제 설정을 조회하고 검증하세요.

redpact settings describe --scope project --path /absolute/path/to/redpact/examples/order-desk
redpact settings validate --scope project --path /absolute/path/to/redpact/examples/order-desk

제공된 파일에 이미 예제 설정이 들어 있습니다. 일반적인 템플릿으로 덮어쓰지 마세요.

시나리오 시작

CLI로 실행을 제출하세요.

redpact tests run --kind integration \
  --path /absolute/path/to/redpact/examples/order-desk --test http.test.js --json

테스트 경로는 설정된 테스트 디렉터리를 기준으로 한 상대 경로이며, 기본 디렉터리는 integration입니다. 이 예제는 tests로 설정되어 있습니다. 이 시나리오를 명시하면 다른 소스 묶음을 명시적으로 지정해야 하는 별도의 예제 테스트가 함께 실행되는 일을 피할 수 있습니다.

Redpact는 요청을 기록하고 식별자를 반환합니다. 반환된 상태가 awaiting_approval이면 검토 대기 중인 요청으로, 아직 실행이 시작되지 않았습니다. 연결된 클라이언트에서 제공하는 제어를 따르거나, 클라이언트가 이를 표시하지 못한다면 문제 해결을 확인하세요. 반복해서 상태를 조회해도 요청이 승인되지는 않습니다.

Redpact는 요청 접수 시 승인 대기에 들어가기 전에 Integration 테스트 소스를 수집해 보존합니다. 실행이 허용되면 해당 테스트로 실행할 환경을 준비합니다. 검토 중 테스트 파일을 편집해도 기존 제출은 바뀌지 않으므로 변경을 포함하려면 새 요청을 제출하세요. 대기 상태에 준비 과정이 포함될 수 있습니다. ID를 받았다고 테스트가 통과한 것은 아닙니다. redpact tests run를 다시 호출하면 새 요청이 만들어집니다. 접수된 요청은 redpact runs show으로 추적하세요.

결과 읽기

반환된 ID로 CLI 결과를 조회하세요.

redpact runs show --kind integration --id RETURNED_RUN_ID --json

실행이 최종 상태에 도달할 때까지 확인하세요. 시나리오 결과, 진단, 환경 정리 상태를 살펴봅니다. 예제의 기대 결과는 결제 시나리오 통과입니다. 이 안내 자체가 사용자의 컴퓨터에서 통과했다는 근거는 아닙니다.

시작에 실패했다면 단언을 바꾸기 전에 환경을 진단하세요. 단언 실패, 모듈 수집 오류, Docker 시작 문제는 서로 다른 의미입니다. 문제 해결을 참고하세요.

뷰어에서 같은 실행 찾기

Order Desk 프로젝트와 요청에 사용한 체크아웃을 선택하세요. Integration 결과와 Log를 살펴보고, 기록된 제출·실행 식별자를 도구 응답과 비교하세요. 기록이 없다면 서버 인스턴스나 체크아웃이 다른 경우가 많습니다.

기록된 소스를 열어 무엇이 제출됐는지 확인하세요. 이후 작업 파일을 수정해도 스냅샷은 바뀌지 않습니다. 통과는 실행된 시나리오에 대한 결과이며, 테스트하지 않은 동작이나 이후 변경까지 검증하지는 않습니다. 결과 읽기를 참고하세요.

예제의 단언 이해하기

예제는 로컬 fixture에서 test와 expect를 가져옵니다. fixture는 준비된 애플리케이션에 접근할 API 클라이언트를 제공합니다. 핵심 검증은 다음과 같습니다.

const response = await api.checkout()
expect(response.status).toBe(200)
expect(await response.json()).toMatchObject({ quantity: 1, totalCents: 250 })

상태 단언은 요청 성공 여부를 확인합니다. 본문 단언은 다른 응답 필드를 허용하면서 예상한 수량과 합계가 들어 있는지 확인합니다. 요청을 수정하기 전에 fixture와 애플리케이션을 함께 읽으세요. 예제의 API 클라이언트는 애플리케이션 코드이며 Redpact 내장 API가 아닙니다.

이 시나리오는 선택한 mock을 사용하는 결제 응답 하나를 검증합니다. 실제 결제 제공자와의 호환성, 재시작 후 데이터 유지, 브라우저 동작까지 확인하지는 않습니다. 그런 주장이 필요하다면 해당 경계에서 확인하는 시나리오를 추가하세요.

첫 결과를 검토 가능한 형태로 정리하기

요청이 끝나면 실제 기록에서 다음 정보를 확인하세요.

예를 들어 기록된 결제 케이스가 payments: mock으로 통과했다고 설명하면서 실제 실행 ID를 함께 제시할 수 있습니다. 이 정보는 반환된 근거에서 가져오세요. 예시의 기대 결과를 관찰된 결과처럼 복사하면 안 됩니다.

수정 후 다시 실행하기

첫 시도가 실패하면 ID를 남겨 두고 보고된 원인을 수정하세요. 헬퍼가 누락됐다면 소스 번들을, 이미지 빌드가 실패했다면 애플리케이션 빌드를 수정해야 합니다. 응답이 예상과 다르면 단언과 실제 동작을 조사해야 합니다.

관련 입력을 고친 뒤에는 새 요청을 제출하세요. redpact runs show은 기존 요청을 읽는 도구이며 테스트를 재실행하거나 수정된 파일을 반영하지 않습니다. 새 기록의 소스와 결과를 원래 실패와 비교하세요. 새 실행은 현재 애플리케이션과 설정 입력으로 새 환경을 준비합니다.

환경 수명

실행마다 새 임시 환경을 준비하고 종료 후 해당 리소스를 제거합니다. 기록된 소스, 결과, 로그는 남습니다. 정리 상태는 테스트 판정과 별개입니다. 테스트가 통과했더라도 리소스 제거에 실패했다면 확인이 필요할 수 있습니다.

모든 테스트 실행은 자체 임시 환경을 사용하며 독립적인 테스트 환경 준비·재사용은 지원하지 않습니다. 수동 점검용 Project Container는 별도 환경을 명시적으로 시작하며 테스트가 재사용할 수 없습니다. 독립 관리 서비스에는 shared-local 또는 remote 종류를 사용합니다. 테스트는 자동 정리하며 공개 취소·환경 강제 종료를 제공하지 않습니다. 결과와 정리 상태를 확인하고 남은 정리 실패를 보고하세요. 수동 Container 제어는 수동 리소스만 관리합니다.

내 애플리케이션에 적용

에이전트에게 실제 서비스 연결과 단언을 사용해 관찰 가능한 애플리케이션 동작 하나를 검증하는 의미 있는 통합 시나리오를 작성하도록 요청하세요. 필요한 헬퍼는 수집되는 소스 묶음 안에 두세요. 묶음 밖의 임의 import가 자동으로 수집되지는 않습니다. 검토하려는 실제 체크아웃에서 실행하고 반환된 식별자를 보관하세요.

단위 테스트 명령, Vitest 통합 테스트, Playwright 기능 테스트와 캡처는 테스트 종류와 작성 방법을 이어서 확인하세요.