Test clocks: How we made it easier to test Stripe Billing integrations

🖼️ 인포그래픽

Test clocks: How we made it easier to test Stripe Billing integrations 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Stripe Billing의 테스트 시계는 실제 운영 로직을 그대로 사용하면서 의미 있는 결제 이벤트로 시간을 빠르게 이동시켜, 장기간의 구독·청구 시나리오를 짧은 시간 안에 검증하게 해준다.

📌 핵심 요약

결제 통합은 일광 절약 시간, 윤년, 서로 다른 타임스탬프 형식, 부정확한 시스템 시계 등 시간에 관한 잘못된 가정 때문에 오류가 발생하기 쉽다.
과거에는 구독 주기를 인위적으로 줄이거나 10초 체험판을 만드는 방식으로 테스트했지만, 이는 실제 운영 설정을 완전히 재현하지 못했다.
테스트 시계는 고객 객체와 관련 결제 리소스에 별도의 시간 기준을 연결하고, 시간이 흐른 것처럼 구독·청구서 상태를 변경하며 웹훅을 발생시킨다.
Stripe는 물리적 타임스탬프와 논리적 이벤트를 결합한 하이브리드 논리 시계를 사용해 모든 중간 초를 거치지 않고 다음 청구일 같은 의미 있는 시점으로 이동하도록 설계했다.
실제 시계와 테스트 시계를 선택할 수 있는 추상 시간 공급자를 도입하고, 테스트 시계가 연결된 객체를 실시간 비동기 스케줄러에서 제외해 테스트 시계가 실행 순서를 전담하게 했다.

🧩 주요 포인트

실제 시간 대기와 축약된 테스트 주기 의존 → 운영 환경과 다른 설정에서 생기는 검증 불확실성을 테스트 시계로 줄였다.
각 단계마다 다음 의미 있는 이벤트를 다시 계산 → 이벤트 처리로 새 일정이나 상태 변화가 생겨도 정해진 순서대로 반영할 수 있다.
시간 조회 추상화와 스케줄러 분리 → 기존 API 표현과 업무 로직을 바꾸지 않으면서 실제 시간과 테스트 시간을 안전하게 운용한다.

🧠 상세 정리

1. 시간 기반 결제 통합이 어려운 이유

Stripe Billing은 반복 결제, 사용량에 따른 트리거, 맞춤형 기능을 통해 기업이 고객 관계를 관리하도록 지원하며, 이러한 처리는 사업 운영의 핵심 흐름에 해당한다. 그러나 하루가 언제나 24시간이라는 가정, 2월이 항상 28일이라는 가정, 타임스탬프 형식이 늘 동일하다는 가정, 시스템 시계가 정확하다는 가정은 실제 환경에서 성립하지 않을 수 있다. 일광 절약 시간 변경과 윤년처럼 달력과 시계에는 예외가 있으므로, 구독 상태와 청구 시점을 다루는 통합은 다양한 시간 경계를 반드시 검증해야 한다. Stripe는 이처럼 시간에 관한 흔한 오해가 오류로 이어질 수 있기 때문에 Billing 통합이 예상대로 작동하는지 신뢰성 있게 확인할 수단이 필요하다고 설명한다.

2. 기존 테스트 방식과 테스트 시계의 도입

과거에는 시간이 실제로 흐르기를 기다리는 것이 Billing 시나리오를 시험하는 사실상 유일한 방법이었다. 개발자는 운영 환경보다 짧은 구독 주기를 별도로 만들거나 10초짜리 체험 기간을 설정해 구독 상태를 강제로 전환한 뒤, 그 과정에서 문제가 나타나는지 관찰했다. 하지만 운영 시스템과 완전히 일치하지 않는 구성을 기반으로 한 검증은 신뢰하기 어려웠고, 장기간에 걸친 동작을 빠르게 확인하기도 힘들었다. 테스트 시계는 고객 객체와 관련 Billing 리소스에 시간 기준을 연결해 실제 시간을 기다리지 않고 미래로 이동하며, 구독과 청구서의 상태 변경 및 웹훅 발생까지 실제 시간이 지난 것처럼 처리한다. 덕분에 윤년과 같은 경계 조건도 몇 차례의 API 호출이나 대시보드 조작만으로 시험할 수 있다.

3. 하이브리드 논리 시계의 핵심 개념

Stripe는 시간을 초·분·일이 연속적으로 흐르는 물리적 시계로만 보지 않고, 특정 타임스탬프에 발생하는 의미 있는 이벤트의 순서로도 해석했다. 실제 시계의 물리적 타임스탬프와 논리적 이벤트의 순서를 결합한 것이 테스트 환경에 적용된 하이브리드 논리 시계다. 이 방식에서는 현재 시각부터 30일 뒤까지 모든 초를 통과하는 대신 다음 월별 청구일과 같은 중요한 이벤트로 바로 이동할 수 있어 시간 전진에 드는 계산 비용이 크게 줄어든다. 다만 의미 있는 이벤트 전체와 그 순서는 사전에 확정할 수 없는데, 한 이벤트의 처리가 객체 상태를 바꾸거나 새로운 이벤트를 만들 수 있기 때문이다. 예를 들어 첫 10일을 무료로 전환하면 기존 구독 주기를 유지할 수도 있고 주기와 청구 시점을 10일 늦출 수도 있으므로, 다음 이벤트를 동적으로 다시 판단해야 한다.

4. 목표 시각까지 전진하는 반복 알고리즘

사용자가 테스트 시계를 미래의 목표 시각으로 이동시키면 시스템은 먼저 해당 시계를 사용하는 모든 객체에서 다음으로 의미 있는 시점을 계산한다. 그 시점이 목표 시각보다 뒤라면 시계의 고정 시각을 목표 시각으로 설정하고 전진을 종료하며, 목표 시각보다 앞이라면 예정된 동작을 실행한 후 고정 시각을 해당 이벤트 시각으로 옮긴다. 이벤트 처리가 끝나면 처음부터 계산을 반복하므로, 방금 실행한 동작이 새로운 이벤트를 예약하거나 기존 상태를 변경해도 그 결과가 다음 단계에 반영된다. 글의 예시에서는 19시에서 다음 날 6시 30분으로 이동하면서 자정의 이벤트를 처리하고, 그 이벤트가 새로 만든 1시 30분 이벤트와 기존 3시 이벤트를 차례로 실행한다. 이후 다음 이벤트가 목표 시각을 넘는다는 사실을 확인하면 시계를 6시 30분에 맞추고 종료한다.

5. 기존 업무 로직을 유지한 구현 방식

테스트 시계는 객체가 인식하는 현재 시각만 바꾸기 때문에, 각 의미 있는 시점에서는 실제 시간이 흘렀을 때와 정확히 같은 업무 로직이 실행된다. Stripe는 내부 코드가 현실 세계의 시계에 직접 의존하지 않도록 수정하고, 실제 시계 또는 테스트 시계를 기반으로 타임스탬프를 제공하는 추상화된 시간 공급자를 도입했다. 이 변경은 Billing 객체가 API에 표시되는 의미를 바꾸지 않으며, 개발자와 내부 시스템이 기존 로직을 동작 변화 없이 계속 사용할 수 있게 한다. 또한 테스트 시계가 연결된 객체는 현실 시간의 경과를 감시하는 비동기 스케줄링 서비스의 데이터베이스 검색 대상에서 명시적으로 제외했다. 일반 구독은 결제 기간 종료를 감지한 스케줄러가 새 청구서 생성을 유발하지만, 테스트 객체의 일정 조정과 실행 순서는 테스트 시계가 전적으로 통제한다.

6. 검증 범위와 개발 효과

동일한 실제 업무 로직을 실행하면서 시간을 빠르게 이동할 수 있으므로, 테스트 시계는 Billing 통합을 안전하고 엄격하게 검증하는 데 사용된다. Stripe도 Billing의 모든 새 기능을 시험하는 내부 도구로 테스트 시계를 활용한다고 밝힌다. 적용 대상에는 반복 구독, 유료 구독으로 전환되는 체험판, 비례 요금 조정, 갱신 결제 실패, 연체 구독, 기간 한정 할인, 구독 일정 등 여러 시간 의존 시나리오가 포함된다. 개발자는 실제 운영 주기를 기다리거나 운영과 다른 축약 설정을 만들지 않고도 상태 변화와 웹훅을 빠르게 확인할 수 있다. 이에 따라 기업은 자사의 결제 모델과 통합 동작을 더 짧은 시간 안에 검증하고 배포할 수 있으며, 제품 출시까지 걸리는 시간도 단축할 수 있다.

🧾 핵심 주장 / 시사점

테스트 전용 업무 로직을 따로 복제하지 않고 시간이라는 외부 의존성만 추상화했기 때문에, 테스트 결과와 실제 운영 동작 사이의 의미 차이를 최소화할 수 있다.
의미 있는 이벤트로 직접 이동하는 구조는 빠른 실행과 실제 로직 재사용을 함께 달성하며, 장기간의 결제 시나리오를 검증할 때 불필요한 시간 경과 계산을 줄인다.
테스트 객체를 현실 시간 기반 스케줄러에서 제외하는 처리는 두 시간 체계가 같은 객체를 동시에 실행하는 상황을 막고, 테스트 시계가 이벤트 순서를 일관되게 통제하도록 한다.