No More ‘Ship and Pray’: Playwright & Stripe 테스트 시계를 사용하여 SaaS 청구 시스템 테스트

사진: 당신은 방금 새로운 구독 청구 기능을 구현했습니다.당신의 사용자는 7 일 시험, 다음 $ 250 / 월 당신의 프로 계획.QA는 두려운 질문을 던집니다 : "우리는 어떻게 전체 청구 라이프 사이클을 테스트합니까?" 당신의 옵션은 제한된 것처럼 보입니다 : 실시간 테스트를 위해 7일 이상 기다리십시오 (다음 주기에 30일 이상 기다리십시오) 데이터베이스 타임스탬프를 수동으로 조작하십시오 (약하고 비현실적) 모든 것을 조롱하십시오 (그러나 실제 스트립 통합 문제를 놓치지 마십시오) 배와 기도 (우리는 모두 거기에 있었다 ) 7+일을 기다립니다. 데이터베이스 타임스탬프를 수동으로 조작 모든 것을 웃음 배와 기도 각 접근 방식에는 심각한 결함이 있습니다. 실시간 테스트는 CI/CD에 너무 느리다. 데이터베이스 조작은 웹 호크가 포함될 때 끊어집니다. 웃음은 실제 세계 스트립 행동을 놓치고. 그리고 테스트되지 않은 청구 코드를 배송합니까? 내가 당신에게 더 나은 방법이 있다고 말하면 어떨까요? 내가 당신에게 더 나은 방법이 있다고 말하면 어떨까요? The Game-Changer: Stripe 시계 테스트 + Playwright E2E 테스트 우리는 Stripe Test Clocks와 Playwright end-to-end 테스트를 결합하여 5 분 이내에 실행되는 포괄적 인 청구 검증 시스템을 만듭니다. 우리의 솔루션은 우리에게 : 몇 분 안에 완전한 청구 라이프 사이클 (시험 → 지불 → 갱신) 테스트 정확한 청구서 금액 및 구독 상태 전환을 확인 Webhook 처리 및 타이밍 시나리오 테스트 생산에 도달하기 전에 청구 버그를 잡으십시오. 모든 환경에서 작동하는 결정적인 테스트 실행 이것은 우리가 그것을 어떻게 만들었는지, 그리고 당신도 할 수있는 방법입니다. The Architecture: Environment-Isolated Time Manipulation에 대한 리뷰 보기 우리의 스트립 테스트 시계 구현은 세 가지 주요 구성 요소로 구성됩니다 : Backend API 레이어 다음을 처리하는 전용 테스트 시계 관리 API : 환경 안전: 테스트 시계는 테스트/개발 환경에서만 작동합니다. 리소스 관리: 테스트 시계 만들기, 진행 및 청소 Webhook 조정: Stripe webhook 처리 타이밍 관리 제2장 Frontend Test Helpers 테스트 시계 작업을 조정하는 TypeScript 유틸리티: 테스트 환경 만들기: 한 번에 완전한 청구 테스트 설정 Time Advancement: 시간을 앞두고 webhook 처리를 기다리십시오. 청구 검증: 포괄적 인 청구서 및 구독 검증 Playwright E2E 통합 완전한 사용자 여행을 검증하는 종료 테스트: End-to-end tests that verify the complete user journey: UI 상호 작용: 실제 사용자 등록 및 구독 흐름 시계 조작 테스트 : 무대 뒤의 시간 진행 청구 검증: 청구 이벤트의 자동 검증 Technical Deep-Dive: Implementation Details에 대한 정보 시계 관리 API Test Clock Management API 우리의 백엔드는 테스트 시계 작업을위한 포괄적 인 REST API를 제공합니다.여기에 핵심 구조가 있습니다: export const createTestClock = async (frozenTime, name = null) => { // Environment safety check ensureTestEnvironment(); const stripe = getStripeClient(); const frozenTimeUnix = Math.floor(frozenTime.getTime() / 1000); const testClock = await stripe.testHelpers.testClocks.create({ frozen_time: frozenTimeUnix, name: name || `test-${Date.now()}` }); logger.info('Created test clock', { testClockId: testClock.id, frozenTime: frozenTime.toISOString() }); return testClock; }; export const advanceTestClock = async (testClockId, targetTime) => { ensureTestEnvironment(); const stripe = getStripeClient(); const targetTimeUnix = Math.floor(targetTime.getTime() / 1000); const result = await stripe.testHelpers.testClocks.advance(testClockId, { frozen_time: targetTimeUnix }); logger.info('Advanced test clock', { testClockId, targetTime: targetTime.toISOString() }); return result; }; 서비스 레이어는 복잡한 작업을 조정합니다: The service layer orchestrates complex operations: // testClocks.service.js - Business process orchestration export const createBillingTestEnvironment = async ( accountId, tier, billingPeriod, frozenTime, options = {} ) => { return withTransaction(async (session) => { // Create test clock const testClock = await createTestClock(frozenTime, `billing-test-${accountId}-${Date.now()}`); // Create Stripe customer with test clock const customer = await createOrUpdateStripeCustomer(accountId, { test_clock: testClock.id }); // Create subscription with trial const priceId = getTierPriceId(tier, billingPeriod); const subscription = await stripe.subscriptions.create({ customer: customer.id, items: [{ price: priceId }], trial_period_days: options.trialDays || 7, payment_behavior: 'default_incomplete', payment_settings: { save_default_payment_method: 'on_subscription' } }); return { testClock: { id: testClock.id, frozenTime: frozenTime, frozenTimeUnix: testClock.frozen_time }, customer: { id: customer.id, accountId }, subscription: { id: subscription.id, status: subscription.status, trialStart: subscription.trial_start, trialEnd: subscription.trial_end } }; }); }; 모델 번호:TypeScript Test Helpers 우리의 프론트 엔드 도우미는 테스트 시계 작업을 위한 깨끗한 API를 제공합니다.Our frontend helpers provide a clean API for test clock operations: // stripe-test-helpers.ts export interface TestClockEnvironment { testClock: { id: string; frozenTime: string; frozenTimeUnix: number; }; customer: { id: string; accountId: string }; subscription: { id: string; status: string; trialStart?: string; trialEnd?: string; }; } export async function createTestClockEnvironment( page: Page, accountId: string, tier: string, billingPeriod: 'monthly' | 'yearly', frozenTime: string, options: { includeTrial?: boolean; trialDays?: number } = {} ): Promise { const authToken = await getAuthToken(page); const response = await page.request.post('/api/v1/billing/test/environments', { data: { accountId, tier, billingPeriod, frozenTime, includeTrial: options.includeTrial ?? true, trialDays: options.trialDays ?? 7 }, headers: { 'Authorization': `Bearer ${authToken}`, 'Content-Type': 'application/json' } }); const result = await response.json(); return result.data; } export async function advanceTestClockAndWaitForWebhooks( page: Page, testClockId: string, targetTime: string, webhookTimeout: number = 30000 ): Promise { const authToken = await getAuthToken(page); const response = await page.request.put( `/api/v1/billing/test/environments/${testClockId}/advance`, { data: { targetTime, webhookTimeout }, headers: { 'Authorization': `Bearer ${authToken}`, 'Content-Type': 'application/json' } } ); const result = await response.json(); console.log('✅ Test clock advanced:', { testClockId, targetTime, webhooksProcessed: result.data.processing.webhooksProcessed }); return result.data; } Advanced Webhook Processing 전략 테스트 시계의 가장 큰 도전 중 하나는 웹 호크 타이밍입니다. Stripe는 웹 호크를 비동기적으로 처리하므로 시간을 진행하면 즉각적인 웹 호크 배달이 보장되지 않습니다. export const waitForWebhookProcessing = async ( testClockId, timeout = 30000 ) => { const startTime = Date.now(); const pollInterval = 2000; while (Date.now() - startTime setTimeout(resolve, 3000)); return { completed: true, processingTime: Date.now() - startTime }; } await new Promise(resolve => setTimeout(resolve, pollInterval)); } throw new Error(`Webhook processing timeout after ${timeout}ms`); }; 광범위한 청구서 검사 우리의 검증 시스템은 청구 이벤트의 여러 측면을 검사합니다 : export interface BillingVerification { subscription: { status: string; statusMatches: boolean; currentPeriodStart: string; currentPeriodEnd: string; }; invoices: { total: number; hasInvoices: boolean; validBillingEvents: number; details: Array ; }; verification: { subscriptionStatusOK: boolean; invoicesCreatedOK: boolean; invoicesPaidOK: boolean; overallSuccess: boolean; }; } export async function verifyBillingLifecycle( page: Page, customerId: string, subscriptionId: string, expectations: { invoiceCreated?: boolean; invoicePaid?: boolean; subscriptionStatus?: string; } = {} ): Promise { const authToken = await getAuthToken(page); const response = await page.request.post('/api/v1/billing/test/verify', { data: { customerId, subscriptionId, expectations }, headers: { 'Authorization': `Bearer ${authToken}`, 'Content-Type': 'application/json' } }); const result = await response.json(); console.log('📊 Billing verification results:', { overallSuccess: result.data.verification.overallSuccess, subscriptionStatus: result.data.subscription.status, invoiceCount: result.data.invoices.total }); return result.data; } Real-World Example: Complete Billing Lifecycle 테스트 다음은 시험에서 두 번째 지불에 이르기까지 우리의 프로 계획 청구를 확인하는 완전한 Playwright 테스트입니다 (250 달러 / 달). test('should correctly charge invoice after trial period using test clocks', async () => { test.setTimeout(300000); // 5 minutes max const subscriptionPage = new SubscriptionManagementPage(page); let testEnvironment: TestClockEnvironment; // Step 1: Create test clock environment with trial await test.step('Create test clock environment', async () => { const frozenTime = new Date(); frozenTime.setHours(0, 0, 0, 0); // Start of today testEnvironment = await createTestClockEnvironment( page, accountId, 'pro', 'monthly', frozenTime.toISOString(), { includeTrial: true, trialDays: 7 } ); console.log('✅ Test environment created:', { testClockId: testEnvironment.testClock.id, customerId: testEnvironment.customer.id, subscriptionId: testEnvironment.subscription.id }); }); // Step 2: User upgrades through UI (with test clock injection) await test.step('User upgrades to Pro plan', async () => { // Intercept checkout API to inject test clock ID await page.route('**/api/v1/billing/checkout', async route => { const request = route.request(); if (request.method() === 'POST') { const originalData = request.postDataJSON(); const modifiedData = { ...originalData, testClockId: testEnvironment.testClock.id }; await route.continue({ postData: JSON.stringify(modifiedData), headers: { ...request.headers(), 'Content-Type': 'application/json' } }); } else { await route.continue(); } }); // Complete upgrade through UI await subscriptionPage.upgradeToProPlan('monthly'); await subscriptionPage.waitForStripeRedirect(); // Complete Stripe checkout await completeStripeCheckout(page, STRIPE_TEST_CARDS.VISA_SUCCESS); console.log('✅ Pro plan upgrade completed through UI'); }); // Step 3: Verify trial status ($0 invoice) await test.step('Verify trial status', async () => { const trialVerification = await verifyBillingLifecycle( page, testEnvironment.customer.id, testEnvironment.subscription.id, { subscriptionStatus: 'trialing' } ); // Should be in trial with $0 invoices expect(trialVerification.subscription.status).toBe('trialing'); const chargedInvoices = trialVerification.invoices.details.filter( invoice => invoice.amountDue > 0 || invoice.amountPaid > 0 ); expect(chargedInvoices.length).toBe(0); console.log('✅ Trial verified: No charges during trial period'); }); // Step 4: Advance time past trial (8 days) await test.step('Advance past trial period', async () => { const trialEndTime = new Date(); trialEndTime.setHours(0, 0, 0, 0); trialEndTime.setTime(trialEndTime.getTime() + (8 * 24 * 60 * 60 * 1000)); await advanceTestClockAndWaitForWebhooks( page, testEnvironment.testClock.id, trialEndTime.toISOString(), 90000 // 90 second webhook timeout ); console.log('✅ Time advanced 8 days past trial start'); }); // Step 5: Verify first $250 payment await test.step('Verify first Pro plan payment', async () => { const postTrialVerification = await verifyBillingLifecycle( page, testEnvironment.customer.id, testEnvironment.subscription.id, { subscriptionStatus: 'active' } ); // Should now be active (not trialing) expect(postTrialVerification.subscription.status).toBe('active'); // Should have $250 Pro plan charge const proInvoices = postTrialVerification.invoices.details.filter( inv => inv.isValidBillingEvent && inv.effectiveAmount === 25000 // $250 in cents ); expect(proInvoices.length).toBe(1); console.log('✅ First Pro plan payment verified: $250 charged'); }); // Step 6: Advance to second billing cycle (32 more days) await test.step('Advance to second billing cycle', async () => { const secondBillingTime = new Date(); secondBillingTime.setHours(0, 0, 0, 0); secondBillingTime.setTime(secondBillingTime.getTime() + (40 * 24 * 60 * 60 * 1000)); await advanceTestClockAndWaitForWebhooks( page, testEnvironment.testClock.id, secondBillingTime.toISOString(), 90000 ); console.log('✅ Advanced to second billing cycle (40 days total)'); }); // Step 7: Verify second $250 payment await test.step('Verify second Pro plan payment', async () => { const secondBillingVerification = await verifyBillingLifecycle( page, testEnvironment.customer.id, testEnvironment.subscription.id, { subscriptionStatus: 'active' } ); // Should have 2 Pro plan billing events now const proInvoices = secondBillingVerification.invoices.details.filter( inv => inv.isValidBillingEvent && inv.effectiveAmount === 25000 ); expect(proInvoices.length).toBe(2); console.log('✅ Second Pro plan payment verified: Total $500 charged'); console.log('🎉 Complete billing lifecycle test passed!'); }); // Step 8: Cleanup test environment await test.step('Cleanup test environment', async () => { await cleanupTestClockEnvironment( page, testEnvironment.testClock.id, true // Cancel subscriptions ); console.log('✅ Test environment cleaned up'); }); }); 이 단일 테스트는 확인합니다 : $0 요금으로 시험 기간 시험 종료 후 첫 지불 (250 달러) 두 번째 월간 지불 (250 달러) 올바른 구독 상태 전환 Webhook 처리 및 타이밍 청구서 생성 및 지불 처리 전체 테스트 시간: 실시간으로 5분 미만 vs. 40일 이상 전체 테스트 시간: 실시간으로 5분 미만 vs. 40일 이상 Advanced Features: Beyond Basic Time Manipulation 부근의 호텔 환경 안전 메커니즘 우리의 구현의 중요한 측면 중 하나는 테스트 시계가 생산 중에 결코 실행되지 않도록 보장하는 것입니다. export const ensureTestEnvironment = () => { const nodeEnv = process.env.NODE_ENV; if (nodeEnv !== 'test' && nodeEnv !== 'development') { logger.error('Test clocks attempted in production', { nodeEnv }); throw new BadRequestError( 'Test clocks are only available in test and development environments', 'INVALID_ENVIRONMENT' ); } }; // Applied at multiple layers: // 1. Function level (every test clock operation) // 2. Route middleware (API endpoint protection) // 3. Environment variable validation (startup checks) 광범위한 리소스 청소 테스트 시계는 시간이 지남에 따라 축적 될 수 있으므로 강력한 청소 메커니즘을 구축했습니다. export const cleanupTestClockEnvironment = async ( testClockId, cancelSubscriptions = true ) => { const results = { overallSuccess: true, details: {} }; try { // Cancel associated subscriptions if (cancelSubscriptions) { const subscriptions = await getTestClockSubscriptions(testClockId); for (const subscription of subscriptions) { await stripe.subscriptions.cancel(subscription.id); } results.details.subscriptionsCanceled = subscriptions.length; } // Delete the test clock (automatically cleans up associated resources) await stripe.testHelpers.testClocks.del(testClockId); results.details.testClockDeleted = true; logger.info('Test clock environment cleaned up', { testClockId }); } catch (error) { results.overallSuccess = false; results.details.error = error.message; logger.warn('Test clock cleanup had issues', { testClockId, error }); } return results; }; // Automatic cleanup in test hooks test.afterAll(async () => { if (testEnvironment?.testClock?.id) { await cleanupTestClockEnvironment(testEnvironment.testClock.id); } }); 오류 처리 및 Retry Logic 청구 테스트에는 종종 외부 API 호출이 포함되어 있습니다.우리의 구현에는 포괄적 인 오류 처리가 포함됩니다. export async function advanceTestClockWithRetry( page: Page, testClockId: string, targetTime: string, maxRetries: number = 3 ): Promise { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await advanceTestClockAndWaitForWebhooks(page, testClockId, targetTime); } catch (error) { console.warn(`Attempt ${attempt}/${maxRetries} failed:`, error.message); if (attempt === maxRetries) { throw new Error(`Test clock advancement failed after ${maxRetries} attempts: ${error.message}`); } // Exponential backoff await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1))); } } } 성능 메트릭스 : 숫자는 거짓말하지 않는다 다음은 우리의 스트립 테스트 시계 구현이 제공하는 것입니다 : 시간 절약 전통적인 테스트: 전통적인 테스트: 전체 청구주기를 위한 40일 이상 실시간 테스트 우리의 솔루션: 4-5 분 자동 테스트 개선: 99.99 % 더 빠른 청구 확인 덮개 개선 이전: 행복한 경로만의 수동 테스트 : Automated testing of complete billing lifecycle including: After Trial periods and transitions Multiple billing cycles Payment failures and recovery Subscription upgrades/downgrades Webhook processing edge cases 신뢰성 이득 정체성 테스트 : 매번 동일한 결과 환경 고립: 테스트 사이에 간섭이 없음 포괄적 인 검증: 청구서 금액, 구독 상태, webhook 처리 초기 버그 탐지 : 생산 전에 청구 문제를 잡으십시오. 개발자 경험 간단한 API: 단일 라인 테스트 환경 만들기 TypeScript 지원: 전체 유형 보안 및 IntelliSense 자동 청소: 테스트 오염 또는 자원 유출 없음 Rich Logging: 자세한 테스트 실행 통찰력 배운 교훈 : 우리가 다르게 할 수있는 것 핵심 아키텍처 결정 1. Environment Isolation First 우리는 테스트 시계가 강력하고 잠재적으로 위험하다는 것을 일찍부터 배웠습니다. 2. Webhook Processing Strategy Stripe's webhook delivery is asynchronous and timing varies. 우리는 몇 가지 접근 방식을 시도했습니다: 고정된 지연 (신뢰할 수없는) 단일 투표 시도 (Low Webhooks Missed) ✅ 엑스포넌티브 백코프(Exponential Backoff)로 구성 가능한 투표 3. Resource Cleanup Design 테스트 시계는 개발 중에 빠르게 축적됩니다.We built cleanup into: 개별 테스트 Teardown 보관을 위한 대량 청소 엔드포인트 (Bulk Cleaning Endpoints) Orphaned Resource 탐지기 은혜로운 실패 처리 (cleanup shouldn't break tests) 도전을 극복 Challenge 1: Webhook Timing Coordination 스트립은 테스트 시계 진행 후 비동기적으로 웹 호크를 처리합니다.시기를 진행하고 즉시 결과를 확인하려는 초기 시도는 종종 실패했습니다. : 구성 가능한 타임 아웃과 여러 개의 리트리 전략을 포함한 투표 기반 검증을 구현했습니다. Solution Challenge 2: Test Environment Pollution 테스트 시계와 구독은 테스트 실행 사이에 지속되었으며 간섭과 가짜 긍정적 인 결과를 유발했습니다. : 테스트 호크 및 수동 청소 엔드포인트에서 자동 눈물 떨어지는 포괄적 인 청소 메커니즘. Solution Challenge 3: Complex Billing Event Detection Stripe는 다양한 청구서 유형 (시험 $0 청구서, 청구서 초안, 지불 청구서)을 생성하여 검증 논리를 복잡하게 만듭니다. : 유형에 따라 청구서를 분류하고 실제 청구 이벤트에 대한 "실적 금액"을 검증하는 향상된 청구 확인. Solution 결론 : 개발 속도로 테스트 신뢰할 수있는 구독 청구 시스템을 구축하는 것은 수동 테스트 및 생산 핫픽스의 수개월간의 시련이 될 필요가 없습니다.Stripe Test Clocks와 사려 깊은 E2E 테스트 아키텍처를 사용하면 몇 달이 아닌 몇 분 안에 복잡한 청구 수명주기를 확인할 수 있습니다. 우리의 구현은 올바른 추상과 안전 메커니즘으로 시간 조작 테스트가 강력하고 안전 할 수 있음을 보여줍니다. 환경 고립은 협상할 수 없습니다 - 안전 메커니즘을 먼저 구축하십시오. Webhook 처리에는 인내가 필요합니다 - 비동기 작업을 위한 디자인 리소스 청소가 중요하다 - 테스트 환경 관리 계획 Rich verification beats simple assertions - 포괄적 인 검증을 구축 개발자 경험은 중요합니다 - 간단한 API는 복잡한 테스트를 가능하게합니다. 그 결과는 ? 그들은 생산에 도달하기 전에 버그를 잡고 개발자가 현대 소프트웨어 개발의 속도로 청구 기능을 배송 할 수있는 자신감을 제공합니다. 99.99% faster billing verification 이 구현에 관하여 이 문서는 SaaS 플랫폼의 구독 청구 시스템을 테스트하는 실제 생산 구현을 기반으로합니다.The code examples are simplified for clarity but represent the actual architecture and patterns used in production.