Skip to main content

Source: ocean/docs/testing-billing.md | ✏️ Edit on GitHub

Billing System Testing Guide

This guide explains how to test the billing system using real Stripe test APIs.

Overview​

Our billing tests use real Stripe test mode APIs instead of mocks to ensure accurate testing and avoid false positives. The tests are organized into modular test suites for better maintainability.

Test Structure​

The billing tests are organized into the following modules:

1. billing-e2e-subscription.test.ts​

  • Complete subscription lifecycle (create, update, cancel)
  • Trial period functionality
  • Webhook synchronization

2. billing-e2e-payment-methods.test.ts​

  • Payment method management (add, remove, set default)
  • Multiple card type validation
  • Setup intent creation

3. billing-e2e-organization.test.ts​

  • Organization billing details updates
  • International billing support (tax IDs, addresses)
  • Role-based permission testing

4. billing-e2e-error-handling.test.ts​

  • Failed payment recovery
  • 3D Secure authentication flows
  • Invalid input handling
  • Webhook failure recovery
  • Rate limiting behavior

5. billing-test-setup.ts​

  • Shared test utilities and helpers
  • Environment variable validation
  • Test data creation and cleanup

Environment Setup​

  1. Copy the example environment file:

    cp .env.test.example .env.test

  2. Fill in your test environment variables:

    # Supabase Test Instance
    VITE_SUPABASE_URL=https://your-test-project.supabase.co
    VITE_SUPABASE_ANON_KEY=your-test-anon-key
    VITE_SUPABASE_SERVICE_KEY=your-test-service-key

    # Stripe Test Keys (use test mode keys only!)
    VITE_STRIPE_PUBLIC_KEY=pk_test_...
    VITE_STRIPE_SECRET_KEY=sk_test_...

    Important: Only use Stripe test mode keys! Never use live keys in tests.

Running Tests​

Run all billing tests​

pnpm test billing-e2e

Run specific test suites​

# Subscription tests only
pnpm test billing-e2e-subscription

# Payment method tests only
pnpm test billing-e2e-payment-methods

# Organization tests only
pnpm test billing-e2e-organization

# Error handling tests only
pnpm test billing-e2e-error-handling

Test Data Isolation​

  • Each test run uses unique timestamps to prevent conflicts
  • Test data is automatically cleaned up after each test suite
  • Organization names and emails include timestamps for uniqueness

Test Cards​

The following test cards are available in TEST_CONFIG:

  • Default test card: 4242424242424242 - Always succeeds
  • 3D Secure card: 4000002500003155 - Requires authentication
  • Declined card: 4000000000000002 - Always fails

Debugging Tests​

Enable debug output​

DEBUG=true pnpm test billing-e2e

Increase test timeout​

TEST_TIMEOUT=60000 pnpm test billing-e2e

Check Stripe Dashboard​

  • Log into your Stripe test mode dashboard
  • View test payments, subscriptions, and webhook events
  • Use the event logs to debug webhook issues

Best Practices​

  1. Always use environment variables - Never hardcode secrets in tests
  2. Clean up test data - Use the cleanup utilities to avoid accumulating test data
  3. Test with real APIs - Avoid mocks to catch integration issues early
  4. Isolate test runs - Use timestamps to prevent conflicts between parallel runs
  5. Handle async operations - Use waitForWebhook helper for webhook-dependent tests
  6. Test error scenarios - Include tests for declined cards and API failures

Troubleshooting​

Missing environment variables​

If you see "Missing required test environment variables", ensure all required variables are set in .env.test.

Webhook timeouts​

If webhook tests fail with timeouts:

  1. Check your Stripe webhook endpoint configuration
  2. Ensure the Edge Function is deployed and running
  3. Verify database permissions for webhook processing

Authentication errors​

If you get "Insufficient permissions" errors:

  1. Verify the test user has the correct role (owner/admin)
  2. Check RLS policies on billing tables
  3. Ensure GraphQL resolvers have proper authorization checks

Adding New Tests​

When adding new billing tests:

  1. Decide which module the test belongs to (subscription, payment, org, or error)
  2. Use the shared utilities from billing-test-setup.ts
  3. Follow the existing test patterns for consistency
  4. Clean up any test data created during the test
  5. Document any new test scenarios in this guide