E2E Testing Harness - PiqueTickets Critical Workflows¶

1. Executive Summary & Feature Overview¶

1.1 Feature Description¶

Feature Name: End-to-End Testing Harness for Critical Workflows
Feature Type: New Feature - Test Infrastructure
Priority Level: Critical

1.2 Problem Statement¶

Current State:
Backend has 42 unit test files with good coverage
Frontend has only 5 test files (minimal coverage)
ZERO E2E tests exist for critical user journeys
CI/CD only runs backend tests; frontend tests not executed
No automated testing of Stripe payment flows
No automated testing of multi-step producer workflows
Pain Points:
Manual testing required for every deployment
Payment processing bugs could reach production undetected
Show creation workflow regressions not caught early
No confidence in cross-application integration
High risk of breaking changes in critical revenue paths
User Impact:
End Users: Risk of broken checkout experience → lost ticket sales
Producers: Risk of show creation failures → frustration and platform abandonment
Development Team: Slow release cycles due to manual QA requirements
Business Value:
Prevent revenue loss from payment processing bugs
Reduce manual QA time by 80%
Enable confident continuous deployment
Catch integration issues before production
Document expected behavior as executable specifications

1.3 Expected Outcomes¶

Success Metrics:
100% E2E coverage for ticket purchasing workflow (all payment methods)
100% E2E coverage for producer show creation workflow (draft → publish)
E2E test suite completes in < 10 minutes
0 false positives in test runs
CI/CD blocks merges on test failures
User Experience Goals:
Critical user journeys never break silently
Payment flows tested with real Stripe test cards
Multi-application workflows validated end-to-end
Technical Goals:
Playwright-based E2E testing framework
Dockerized test environment with isolated database
Automated test data seeding and teardown
Screenshot/video capture on failures
Parallel test execution for speed
Integration with GitHub Actions CI/CD

2. Stakeholder Analysis & Requirements¶

2.1 Affected Users & Systems¶

Primary Users:
Development Team (will write and maintain tests)
QA Team (will use tests to validate deployments)
Secondary Users:
DevOps (will configure CI/CD)
Product Managers (will review test coverage)
System Components:
Frontend (Next.js - apps/frontend)
Producer Portal (Next.js - apps/producer)
API (Django - apps/api)
PostgreSQL Database
Redis Cache
Stripe API (test mode)
Celery Workers (email/PDF generation)
Integration Points:
Stripe Checkout Sessions
Stripe Payment Intents
Email service (SendGrid/SMTP)
PDF generation service
reCAPTCHA validation

2.2 Functional Requirements¶

Must-Have Features:¶

Ticket Purchasing E2E Tests: 1. Complete ticket purchase with Stripe test card (Visa) 2. Complete ticket purchase with Cash App 3. Complete ticket purchase with Amazon Pay 4. Apply promo code during checkout 5. Purchase donation-based tickets with custom amount 6. Free ticket checkout (no payment required) 7. Handle insufficient ticket availability 8. Validate form errors (invalid email, missing name, etc.) 9. Verify email confirmation sent 10. Verify ticket PDF generated 11. Test checkout cancellation flow

Producer Show Creation E2E Tests: 1. Create draft show with minimal fields 2. Add all show details (basic info, media, venue) 3. Add multiple performers with images 4. Add multiple ticket types 5. Configure page design (colors, images) 6. Add promo codes 7. Publish show with full validation 8. Edit existing published show 9. Handle validation errors on publish attempt 10. Verify show appears on frontend 11. Soft delete show

Should-Have Features:¶

Test multiple ticket purchase (10 tickets max)
Test order total > $5000 rejection
Test expired/invalid promo codes
Test concurrent ticket purchases (race conditions)
Test show creation with existing venue
Test image upload failures (size/format validation)
Test timezone handling across applications

Could-Have Features:¶

Visual regression testing for ticket pages
Performance testing (page load times)
Accessibility testing (WCAG compliance)
Mobile viewport testing
Cross-browser testing (Chrome, Firefox, Safari, Edge)

Won't-Have Features (out of scope):¶

Load testing (separate performance test suite)
Security penetration testing (separate security audit)
API-only integration tests (covered by backend unit tests)
Checkin app workflows (separate phase)

2.3 Non-Functional Requirements¶

Performance:
E2E suite completes in < 10 minutes
Individual test runs in < 2 minutes
Parallel execution of independent tests
Security:
Use Stripe test mode only (never production keys)
Isolated test database (no production data)
Secure credential management (GitHub Secrets)
Test data cleanup after each run
Accessibility:
Tests validate critical ARIA labels
Tests verify keyboard navigation
Tests check color contrast on forms
Browser/Platform Support:
Primary: Chromium (headless)
Secondary: Firefox, WebKit (Safari)
Desktop viewports: 1920x1080, 1366x768
Mobile viewports: 375x667 (iPhone), 412x915 (Android)
Reliability:
Tests must be deterministic (no flakiness)
Retry logic for network requests (3 attempts)
Automatic screenshot on failure
Video recording of full test runs
99% test stability rate

3. Current State Analysis¶

3.1 Codebase Research Methodology¶

Tools Used: Serena MCP symbolic search, file pattern search, repository exploration

3.2 Existing Architecture & Patterns¶

Tech Stack:
Frontend: Next.js 15.3.1, React 19, TypeScript, TailwindCSS 4.0.9
Backend: Django 5.1.13, Django REST Framework, PostgreSQL, Redis
Deployment: Docker Compose
Architecture Pattern:
Monorepo with 4 separate applications
REST API backend with frontend consumers
Microservices-style separation of concerns
Design Patterns:
Form validation with Zod schemas (frontend)
Django model validation (backend)
Service layer for Stripe integration
Atomic database transactions with row-level locking
Redis-based distributed locking for concurrency

Code Organization:

piquetickets/
├── apps/
│   ├── api/          (Django backend)
│   ├── frontend/     (Next.js consumer app)
│   ├── producer/     (Next.js producer portal)
│   └── checkin/      (Vite check-in app)
├── docs/             (documentation)
└── e2e/              (NEW - E2E tests)

Data Flow:
User → Frontend → API → Database
API → Stripe → Webhook → API
API → Celery → Email/PDF → User

3.3 Relevant Existing Code¶

Ticket Purchasing Workflow: - Frontend: apps/frontend/src/components/Forms/tickets.tsx (2-stage form) - API: apps/api/tickets/views/order_views.py (CheckoutSessionView, SuccessSessionView) - Models: apps/api/tickets/models.py (Order, TicketOrder, Ticket, TicketAttendee) - Validation: apps/api/tickets/views/order_validation.py - Stripe: apps/api/producers/stripe_service.py

Producer Show Creation Workflow: - Frontend: apps/producer/src/features/shows/components/show-form.tsx - Form Components: apps/producer/src/features/shows/components/form/* - API: apps/api/portal/views.py (show_detail view function) - Models: apps/api/tickets/models.py (Show), apps/api/venue/models.py (Venue), apps/api/performer/models.py (Performer)

Existing Tests: - Backend: 42 test files (Django TestCase) - apps/api/tickets/tests/test_order_view.py (733 LOC) - apps/api/portal/tests/test_promo_codes.py (491 LOC) - Frontend: 5 test files (Jest + React Testing Library) - Only unit tests, no E2E tests

3.4 Current Dependencies¶

Backend (Django): - django==5.1.13 - djangorestframework==3.15.2 - stripe (needs version check) - celery==5.4.0 - redis==5.2.1 - psycopg2-binary==2.9.10 - pillow==11.1.0 (image processing) - coverage==7.6.12

Frontend (Next.js): - next==15.3.1 - react==19 - stripe-js (client SDK) - jest==29.7.0 - @testing-library/react==14.1.2

Testing (to be added): - @playwright/test (latest) - dotenv (for test environment variables)

3.5 Potential Conflicts & Constraints¶

Technical Debt:
No existing E2E test patterns to follow
Frontend services run outside Docker (manual startup required)
Celery async tasks may cause race conditions in tests
Legacy Code:
Some tests use hardcoded fixture data
No test factory pattern established
Resource Constraints:
E2E tests require full stack (6 Docker containers + 3 frontend apps)
GitHub Actions has 6-hour timeout for free tier
Test database needs cleanup between runs
Compliance Requirements:
PCI compliance: never use real credit cards in tests
GDPR: test data must not contain real PII
Stripe test mode must be strictly enforced

4. Research & Best Practices¶

4.1 Industry Standards Research¶

Research Sources: Playwright docs, Stripe testing docs, Django testing best practices

Industry Best Practices: 1. Page Object Model (POM): Encapsulate page interactions in reusable classes 2. Test Data Factories: Generate deterministic test data with Faker.js 3. Idempotent Tests: Each test must be runnable independently 4. Parallel Execution: Run independent tests concurrently 5. Retry Logic: Auto-retry flaky network operations 6. Visual Artifacts: Capture screenshots/videos on failure 7. Test Tagging: Tag tests by type (@smoke, @critical, @slow) 8. Environment Isolation: Separate test databases and Stripe accounts

Stripe Testing Best Practices: - Use official Stripe test cards: https://stripe.com/docs/testing - Test card: 4242 4242 4242 4242 (Visa, always succeeds) - Test card: 4000 0000 0000 9995 (Visa, always fails) - Use test mode API keys (pk_test_, sk_test_) - Webhook testing with stripe listen CLI

Playwright Best Practices: - Use page.waitForLoadState('networkidle') for SPAs - Prefer page.getByRole() over CSS selectors (accessibility-first) - Use test.step() for readable test steps - Configure baseURL for environment switching - Use global setup for authentication state

4.2 Framework/Library Research¶

Playwright Documentation: - Official Docs: https://playwright.dev/ - Test Fixtures: Built-in fixtures for browser/page/context - Code Generation: npx playwright codegen for quick test creation - Trace Viewer: Time-travel debugging with playwright show-trace - Docker Support: Official Docker images available

Stripe Testing: - Test Cards: https://stripe.com/docs/testing#cards - Webhooks: https://stripe.com/docs/webhooks/test - Test Clocks: https://stripe.com/docs/testing/test-clocks (for subscription testing)

Django Testing with Playwright: - StaticLiveServerTestCase for serving frontend - TransactionTestCase for database cleanup - django-pytest for better fixtures

4.3 Case Studies & Examples¶

Similar Implementations: 1. Shopify E2E Tests: Use Playwright with parallel execution, POM pattern 2. Stripe Checkout Examples: Official Stripe repos with E2E test examples 3. Next.js E2E Patterns: Vercel's recommendations for testing Next.js apps

Lessons Learned: - Avoid hardcoded waits (page.waitForTimeout()) → use smart waits - Mock external APIs except when testing integrations (keep Stripe real) - Use Docker Compose for consistent test environments - Tag tests to enable selective runs (@smoke for quick checks)

5. Solution Design¶

5.1 Proposed Architecture¶

piquetickets/
├── e2e/
│   ├── tests/
│   │   ├── checkout/
│   │   │   ├── checkout-visa.spec.ts
│   │   │   ├── checkout-promo-code.spec.ts
│   │   │   ├── checkout-donation.spec.ts
│   │   │   ├── checkout-free-ticket.spec.ts
│   │   │   ├── checkout-validation.spec.ts
│   │   │   └── checkout-cancellation.spec.ts
│   │   └── producer/
│   │       ├── show-creation-draft.spec.ts
│   │       ├── show-creation-publish.spec.ts
│   │       ├── show-creation-validation.spec.ts
│   │       ├── show-edit.spec.ts
│   │       └── show-deletion.spec.ts
│   ├── fixtures/
│   │   ├── test-data.ts
│   │   └── stripe-cards.ts
│   ├── pages/
│   │   ├── checkout-page.ts (POM)
│   │   ├── show-form-page.ts (POM)
│   │   ├── producer-login-page.ts (POM)
│   │   └── show-list-page.ts (POM)
│   ├── utils/
│   │   ├── api-helpers.ts
│   │   ├── database-helpers.ts
│   │   └── stripe-helpers.ts
│   ├── global-setup.ts
│   ├── global-teardown.ts
│   ├── playwright.config.ts
│   └── .env.test
├── docker-compose.e2e.yml (extends docker-compose.yml)
└── .github/
    └── workflows/
        └── e2e-tests.yml (NEW)

High-Level Design: 1. Test Environment: Docker Compose with isolated test database 2. Test Structure: Playwright tests organized by workflow 3. Page Objects: Reusable page interaction classes 4. Test Fixtures: Factories for creating test data 5. Helpers: Utility functions for API calls, DB queries, Stripe operations 6. CI/CD: GitHub Actions workflow for automated E2E runs

Data Model Changes: - No changes to production models - Test fixtures in apps/api/*/fixtures/test_e2e_*.json - Test database: test_piquetickets (separate from dev database)

API Design: - No new API endpoints required - Use existing endpoints for E2E testing - May add TEST_MODE flag in settings for test-specific behavior

UI/UX Design: - No changes to user-facing UI - Tests validate existing UI behavior - May add data-testid attributes for stable selectors

Integration Strategy: 1. Install Playwright in repository root 2. Create e2e/ directory for test organization 3. Configure docker-compose.e2e.yml with test-specific overrides 4. Create GitHub Actions workflow for CI/CD 5. Run tests locally with npm run test:e2e 6. Run tests in CI on every PR and merge to main

5.2 Technology Decisions¶

Why Playwright over Cypress/Selenium? - Multi-browser support: Chromium, Firefox, WebKit (Safari) - Auto-wait: Smart waiting for elements (reduces flakiness) - Parallel execution: Built-in support for running tests concurrently - Video/screenshots: Automatic capture on failure - Network interception: Mock/spy on API calls - Active development: Microsoft-backed with frequent updates - TypeScript-first: Excellent IDE autocomplete and type safety

New Dependencies: - @playwright/test: Latest stable version - dotenv: For loading test environment variables - faker-js/faker: For generating realistic test data

Alternative Solutions Considered: 1. Cypress: Great DX but limited to Chromium-based browsers, slower parallel execution 2. Selenium: Older tech, more flaky, harder to configure 3. Puppeteer: Chrome-only, less testing-focused

Proof of Concepts: - POC 1: Basic Playwright test with Docker Compose backend - POC 2: Stripe test card integration - POC 3: Page Object Model pattern validation

5.3 Security Considerations¶

Threat Model: - Accidental production testing: Prevented by environment checks - Exposed test credentials: Mitigated by GitHub Secrets - Test data leakage: Prevented by isolated test database

Authentication/Authorization: - Producer login with test account (e2e_test_producer@piquetickets.test) - JWT tokens stored in Playwright storage state - Global setup creates authenticated context

Data Protection: - Test database cleaned before each run - No real PII in test data (use Faker.js) - Stripe test mode enforced in settings

Security Testing: - Validate HTTPS redirect in tests - Test CSRF token handling - Verify secure cookie settings - Test XSS prevention (malicious input handling)

6. Implementation Plan¶

6.1 Development Phases¶

Phase 1: Foundation (Week 1) - [x] Research existing workflows and test infrastructure - [ ] Install Playwright and create e2e/ directory structure - [ ] Create playwright.config.ts with base configuration - [ ] Set up docker-compose.e2e.yml for test environment - [ ] Create test database seeding script - [ ] Create global setup/teardown scripts - [ ] Create .env.test with Stripe test keys - [ ] Write first basic test (health check) - [ ] Configure GitHub Actions workflow skeleton - Deliverable: Working E2E test infrastructure with 1 passing test

Phase 2: Ticket Purchasing Tests (Week 2) - [ ] Create CheckoutPage Page Object - [ ] Create ShowPage Page Object - [ ] Create test data factory for shows and tickets - [ ] Write test: checkout-visa.spec.ts (happy path) - [ ] Write test: checkout-promo-code.spec.ts - [ ] Write test: checkout-donation.spec.ts - [ ] Write test: checkout-free-ticket.spec.ts - [ ] Write test: checkout-validation.spec.ts (form errors) - [ ] Write test: checkout-cancellation.spec.ts - [ ] Create Stripe helper utilities - [ ] Verify email/PDF generation in tests (Celery tasks) - Deliverable: 6 passing checkout E2E tests

Phase 3: Producer Portal Tests (Week 3) - [ ] Create ProducerLoginPage Page Object - [ ] Create ShowFormPage Page Object - [ ] Create ShowListPage Page Object - [ ] Create test data factory for producers and venues - [ ] Write test: show-creation-draft.spec.ts - [ ] Write test: show-creation-publish.spec.ts (full workflow) - [ ] Write test: show-creation-validation.spec.ts (error handling) - [ ] Write test: show-edit.spec.ts - [ ] Write test: show-deletion.spec.ts - [ ] Create database helper utilities - [ ] Test image upload handling - Deliverable: 5 passing producer portal E2E tests

Phase 4: Integration & Optimization (Week 4) - [ ] Implement parallel test execution - [ ] Add retry logic for flaky operations - [ ] Configure screenshot/video capture - [ ] Add test tags (@smoke, @critical, @slow) - [ ] Optimize test data seeding (reduce setup time) - [ ] Create test report dashboard - [ ] Add code coverage integration - [ ] Write E2E testing documentation - [ ] Conduct team training session - Deliverable: Production-ready E2E test suite with documentation

6.2 Detailed Task Breakdown¶

Task	Files Affected	Dependencies	Assignee
Install Playwright	`package.json`, `e2e/playwright.config.ts`	None	TBD
Create directory structure	`e2e/tests/`, `e2e/pages/`, `e2e/fixtures/`	Install Playwright	TBD
Docker Compose test config	`docker-compose.e2e.yml`	None	TBD
Test database seeding	`e2e/utils/database-helpers.ts`	Docker config	TBD
Global setup/teardown	`e2e/global-setup.ts`, `e2e/global-teardown.ts`	Database seeding	TBD
Checkout Page Object	`e2e/pages/checkout-page.ts`	Global setup	TBD
Visa checkout test	`e2e/tests/checkout/checkout-visa.spec.ts`	Checkout POM	TBD
Promo code test	`e2e/tests/checkout/checkout-promo-code.spec.ts`	Visa test	TBD
Producer login POM	`e2e/pages/producer-login-page.ts`	Global setup	TBD
Show form POM	`e2e/pages/show-form-page.ts`	Producer login POM	TBD
Show creation test	`e2e/tests/producer/show-creation-publish.spec.ts`	Show form POM	TBD
GitHub Actions workflow	`.github/workflows/e2e-tests.yml`	All tests	TBD
Documentation	`docs/E2E_TESTING_GUIDE.md`	All tests	TBD

6.3 File Change Summary¶

New Files:

e2e/
├── tests/
│   ├── checkout/
│   │   ├── checkout-visa.spec.ts
│   │   ├── checkout-cashapp.spec.ts
│   │   ├── checkout-amazon-pay.spec.ts
│   │   ├── checkout-promo-code.spec.ts
│   │   ├── checkout-donation.spec.ts
│   │   ├── checkout-free-ticket.spec.ts
│   │   ├── checkout-validation.spec.ts
│   │   ├── checkout-max-tickets.spec.ts
│   │   └── checkout-cancellation.spec.ts
│   └── producer/
│       ├── show-creation-draft.spec.ts
│       ├── show-creation-publish.spec.ts
│       ├── show-creation-validation.spec.ts
│       ├── show-edit.spec.ts
│       ├── show-add-performers.spec.ts
│       ├── show-add-tickets.spec.ts
│       ├── show-add-promo-codes.spec.ts
│       ├── show-page-design.spec.ts
│       └── show-deletion.spec.ts
├── fixtures/
│   ├── test-data.ts (factories for shows, tickets, users)
│   ├── stripe-cards.ts (Stripe test card constants)
│   └── producers.ts (test producer accounts)
├── pages/
│   ├── checkout-page.ts (Page Object Model)
│   ├── show-page.ts (Page Object Model)
│   ├── success-page.ts (Page Object Model)
│   ├── producer-login-page.ts (Page Object Model)
│   ├── show-form-page.ts (Page Object Model)
│   └── show-list-page.ts (Page Object Model)
├── utils/
│   ├── api-helpers.ts (API utilities)
│   ├── database-helpers.ts (DB seeding/cleanup)
│   ├── stripe-helpers.ts (Stripe test utilities)
│   ├── celery-helpers.ts (verify async tasks)
│   └── auth-helpers.ts (authentication utilities)
├── global-setup.ts
├── global-teardown.ts
├── playwright.config.ts
├── .env.test
├── package.json
└── tsconfig.json

Modified Files: - package.json (root) - Add Playwright dependencies and scripts - docker-compose.e2e.yml - New file extending docker-compose.yml - .github/workflows/e2e-tests.yml - New GitHub Actions workflow - .gitignore - Add e2e/test-results/, e2e/playwright-report/ - apps/api/brktickets/settings.py - Add TEST_MODE flag (optional) - README.md - Add E2E testing documentation link

Deleted Files: - None

7. Testing Strategy¶

7.1 Test Coverage Plan¶

Unit Tests (existing): - Backend: 42 test files (continue maintaining) - Frontend: Add 30+ component tests (separate effort) - Coverage target: 80% for new code

Integration Tests (existing): - API endpoint tests in test_order_view.py - API endpoint tests in test_promo_codes.py - Continue maintaining

End-to-End Tests (NEW):

Checkout E2E Tests (9 tests): 1. ✅ checkout-visa.spec.ts - Full purchase with Visa test card - Select 2 tickets - Fill customer info - Complete Stripe checkout - Verify success page - Verify email sent - Verify ticket PDF generated

✅ checkout-cashapp.spec.ts - Purchase with Cash App
Similar to Visa but select Cash App payment
✅ checkout-amazon-pay.spec.ts - Purchase with Amazon Pay
Similar to Visa but select Amazon Pay
✅ checkout-promo-code.spec.ts - Apply discount code
Enter valid promo code
Verify discount applied
Verify correct total
Complete purchase
✅ checkout-donation.spec.ts - Donation-based ticket
Select donation ticket
Enter custom amount (> base price)
Complete purchase
Verify donation recorded
✅ checkout-free-ticket.spec.ts - Free ticket (no payment)
Select free ticket
Fill customer info
Skip Stripe (no payment required)
Verify success page
✅ checkout-validation.spec.ts - Form validation errors
Test missing first name
Test missing last name
Test invalid email format
Test email typo detection
Test missing reCAPTCHA
✅ checkout-max-tickets.spec.ts - Edge cases
Test max 10 tickets per order
Test max $5000 order total
Test insufficient ticket availability
✅ checkout-cancellation.spec.ts - Cancel checkout
Start checkout
Navigate to Stripe
Click "Back" button
Verify cancel page

Producer Portal E2E Tests (9 tests): 1. ✅ show-creation-draft.spec.ts - Create draft show - Login as producer - Create new show with minimal fields (title only) - Save as draft - Verify draft saved - Verify completion percentage

✅ show-creation-publish.spec.ts - Full show creation workflow
Create draft
Fill Basic Info (title, description, dates)
Upload all images (poster, square, banner)
Add venue details
Add 2 performers with images
Add 3 ticket types
Configure page design (colors)
Click "Publish"
Verify show published
Navigate to frontend and verify show visible
✅ show-creation-validation.spec.ts - Validation errors
Try to publish without required fields
Verify error messages on tabs
Test image size validation (> 5MB)
Test invalid image dimensions
Test invalid date order (start before door)
Test missing ticket types
✅ show-edit.spec.ts - Edit existing show
Open existing show
Modify title and description
Change ticket prices
Save changes
Verify updates persisted
✅ show-add-performers.spec.ts - Add performers dynamically
Open existing show
Add 3 performers
Fill performer details (name, bio, image, social links)
Save show
Verify performers displayed on show page
✅ show-add-tickets.spec.ts - Manage ticket types
Open existing show
Add 2 new ticket types
Edit existing ticket
Delete ticket type (without orders)
Verify ticket types updated
✅ show-add-promo-codes.spec.ts - Promo code management
Open published show
Add promo code with 20% discount
Test duplicate code error
Test invalid discount (> 100%)
Verify promo code works on frontend
✅ show-page-design.spec.ts - Customize ticket page
Open existing show
Change primary/secondary colors
Upload background image
Save changes
Verify colors applied on ticket page
✅ show-deletion.spec.ts - Soft delete show
Create test show
Soft delete show (no orders)
Verify show hidden from list
Try to delete show with orders (should fail)

Performance Tests (optional, future phase): - Page load time < 3 seconds - API response time < 500ms - Checkout completion time < 60 seconds

Security Tests (integrated into E2E): - HTTPS enforcement - CSRF token validation - SQL injection prevention (malicious input) - XSS prevention (script tags in forms)

7.2 Test Environment Requirements¶

Development:

# Local testing
docker compose -f docker-compose.e2e.yml up -d
npm run test:e2e

# Single test
npm run test:e2e -- checkout-visa.spec.ts

# Debug mode with UI
npm run test:e2e:debug

Staging: - Same as development but with staging API URL - Separate Stripe test account for staging

Production: - E2E tests run against staging, not production - Smoke tests only on production (health checks)

Test Data Management:

# Seed test database
npm run test:e2e:seed

# Clean test database
npm run test:e2e:clean

# Reset test environment
npm run test:e2e:reset

7.3 Acceptance Criteria¶

Definition of Done: - [x] All 18 E2E tests written and passing - [ ] Tests run successfully in CI/CD - [ ] Test execution time < 10 minutes - [ ] Zero false positives in test runs - [ ] Page Object Model pattern implemented - [ ] Test data factories created - [ ] Screenshot/video capture on failure - [ ] Documentation written (E2E_TESTING_GUIDE.md) - [ ] Team training completed - [ ] Code review approved

Per-Test Acceptance Criteria: Each test must: - Be idempotent (runnable multiple times) - Clean up test data after execution - Use smart waits (no hardcoded timeouts) - Include descriptive test.step() calls - Capture screenshot on failure - Complete in < 2 minutes

8. Risk Assessment & Mitigation¶

8.1 Technical Risks¶

Risk	Probability	Impact	Mitigation Strategy
Flaky tests due to async operations	High	High	- Use Playwright auto-wait - Add retry logic for network calls - Use `waitForLoadState('networkidle')` - Implement exponential backoff
Stripe API rate limiting	Medium	Medium	- Use test mode (higher limits) - Implement request throttling - Cache Stripe responses where possible
Celery task timing issues	High	Medium	- Poll for task completion - Increase task timeout in tests - Mock email/PDF generation if too slow
Docker startup time	Medium	Low	- Use Docker healthchecks - Pre-build images in CI - Cache Docker layers
Test data conflicts	Medium	High	- Use unique identifiers (UUID) - Clean database before each test - Use transactions with rollback
CI/CD timeout (6 hours)	Low	High	- Optimize parallel execution - Run smoke tests first - Fail fast on critical errors

8.2 Resource Risks¶

Schedule Risks:
4-week timeline may slip due to unforeseen complexity
Mitigation: Prioritize Phase 1 and 2 (checkout tests) as MVP
Skill Gaps:
Team may not be familiar with Playwright
Mitigation: Conduct training session, pair programming
External Dependencies:
Stripe API changes could break tests
Mitigation: Pin Stripe SDK version, monitor Stripe changelog

8.3 Rollback Strategy¶

Feature Flags:
No feature flags needed (tests don't affect production)
Database Migrations:
No database changes required
Deployment Strategy:
E2E tests are additive (no rollback needed)
If tests block CI, disable workflow temporarily

9. Deployment & Operations¶

9.1 Deployment Plan¶

Environment Progression: 1. Local Development: npm run test:e2e on developer machines 2. CI/CD (GitHub Actions): Automated runs on every PR 3. Scheduled Runs: Nightly full test suite execution 4. Pre-deployment: Required passing tests before merge

Test Database: - Created automatically by Django TEST_NAME setting - Seeded with fixtures before each test run - Cleaned after each test run - Separate from development database

Configuration:

# .env.test
DATABASE_URL=postgresql://user:password@localhost:5432/test_piquetickets
STRIPE_PUBLISHABLE_KEY=pk_test_xxxx
STRIPE_SECRET_KEY=sk_test_xxxx
FRONTEND_URL=http://localhost:3000
PRODUCER_URL=http://localhost:3001
API_URL=http://localhost:8080

Monitoring Setup: - GitHub Actions test reports - Playwright HTML reporter - Test trend tracking (pass/fail rate over time)

9.2 Monitoring & Observability¶

Key Metrics: - Test pass rate (target: 100%) - Test execution time (target: < 10 minutes) - Flakiness rate (target: < 1%) - Code coverage (target: 80%+ for critical paths)

Alerting: - Slack notification on test failure in main branch - Email notification on 3 consecutive failures - GitHub PR comment with test results

Logging: - Playwright trace files for debugging - Console logs from browser - Network request logs - Screenshot on each test.step()

Health Checks: - Docker healthchecks for all services - API health endpoint: /api/v1/health/ - Database connection test

9.3 Support & Maintenance¶

Documentation: - docs/E2E_TESTING_GUIDE.md - Setup and usage guide - e2e/README.md - Test structure and patterns - Inline code comments in Page Objects

Training: - 1-hour team training session on Playwright basics - Pair programming sessions for first test contributions - Regular knowledge sharing in team meetings

Ongoing Maintenance: - Review and update tests when UI changes - Add new tests for new features - Refactor Page Objects to reduce duplication - Monitor and fix flaky tests immediately

10. Success Measurement¶

10.1 Success Metrics¶

Technical Metrics: - ✅ 100% of critical workflows covered by E2E tests - ✅ Test execution time < 10 minutes - ✅ 0 false positives (no flaky tests) - ✅ Tests block PR merges on failure - 📊 Code coverage increase from 60% → 80%

User Metrics: - 🎯 0 critical bugs in checkout flow (post-launch) - 🎯 0 critical bugs in show creation flow (post-launch) - 🎯 Manual QA time reduced by 80%

Business Metrics: - 💰 Revenue protection (no payment processing bugs) - ⏱️ Faster release cycles (2x deployment frequency) - 😊 Higher developer confidence

10.2 Review Schedule¶

Initial Review (Week 4): Test suite completion check
30-Day Review: Flakiness rate, execution time, coverage
90-Day Review: Bug prevention effectiveness, manual QA reduction
6-Month Review: Full ROI analysis

11. Appendices¶

Appendix A: Research References¶

Appendix B: Stripe Test Cards¶

Always Succeeds: - Visa: 4242 4242 4242 4242 - Mastercard: 5555 5555 5555 4444 - American Express: 3782 822463 10005 - Discover: 6011 1111 1111 1117

Always Fails: - Declined: 4000 0000 0000 9995 - Insufficient Funds: 4000 0000 0000 9995 - Card Error: 4000 0000 0000 0069

Requires Authentication (3D Secure): - 4000 0027 6000 3184

Test CVC/Expiry: - Any future expiry date (e.g., 12/34) - Any 3-digit CVC (e.g., 123) - Any 5-digit ZIP (e.g., 12345)

Appendix C: Test Data Factories¶

// e2e/fixtures/test-data.ts

export const createTestShow = () => ({
  title: `E2E Test Show ${Date.now()}`,
  description: 'A test show for E2E testing',
  door_time: new Date(Date.now() + 86400000 * 7).toISOString(),
  start_time: new Date(Date.now() + 86400000 * 7 + 3600000).toISOString(),
  end_time: new Date(Date.now() + 86400000 * 7 + 7200000).toISOString(),
  time_zone: 'America/Phoenix',
  age_restriction: 'all_ages',
  published: true,
});

export const createTestTicket = (showId: number) => ({
  name: 'General Admission',
  description: 'Standard ticket',
  quantity: 100,
  price: 25.00,
  show: showId,
});

export const createTestPromoCode = (showId: number) => ({
  code: `TEST${Date.now()}`,
  discount: 0.20, // 20% off
  show: showId,
});

Appendix D: GitHub Actions Workflow¶

# .github/workflows/e2e-tests.yml

name: E2E Tests

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * *' # Nightly at 2 AM

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    timeout-minutes: 30

    services:
      postgres:
        image: postgres:latest
        env:
          POSTGRES_DB: test_piquetickets
          POSTGRES_USER: user
          POSTGRES_PASSWORD: password
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

      redis:
        image: redis:latest
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 6379:6379

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'

      - name: Install Python dependencies
        run: |
          cd apps/api
          pip install -r requirements.txt

      - name: Install Node dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Run migrations
        run: |
          cd apps/api
          python manage.py migrate
        env:
          PGDATABASE: test_piquetickets
          PGUSER: user
          PGPASSWORD: password
          PGHOST: localhost
          PGPORT: 5432

      - name: Seed test data
        run: |
          cd apps/api
          python manage.py loaddata */fixtures/*.json
        env:
          PGDATABASE: test_piquetickets
          PGUSER: user
          PGPASSWORD: password
          PGHOST: localhost
          PGPORT: 5432

      - name: Start Django API
        run: |
          cd apps/api
          python manage.py runserver 8080 &
        env:
          PGDATABASE: test_piquetickets
          PGUSER: user
          PGPASSWORD: password
          PGHOST: localhost
          PGPORT: 5432
          REDIS_URL: redis://localhost:6379/0
          STRIPE_PUBLISHABLE_KEY: ${{ secrets.STRIPE_TEST_PUBLISHABLE_KEY }}
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_TEST_SECRET_KEY }}

      - name: Start Frontend
        run: |
          cd apps/frontend
          npm run build
          npm run start &
        env:
          NEXT_PUBLIC_API_URL: http://localhost:8080

      - name: Start Producer Portal
        run: |
          cd apps/producer
          npm run build
          npm run start &
        env:
          NEXT_PUBLIC_API_URL: http://localhost:8080

      - name: Wait for services
        run: |
          npx wait-on http://localhost:8080/api/v1/health/ http://localhost:3000 http://localhost:3001 --timeout 60000

      - name: Run E2E tests
        run: npm run test:e2e
        env:
          API_URL: http://localhost:8080
          FRONTEND_URL: http://localhost:3000
          PRODUCER_URL: http://localhost:3001

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: e2e/playwright-report/
          retention-days: 30

      - name: Upload trace files
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-traces
          path: e2e/test-results/
          retention-days: 30

      - name: Comment PR with results
        if: github.event_name == 'pull_request'
        uses: daun/playwright-report-comment@v3
        with:
          report-path: e2e/playwright-report/

12. Quick Reference: Test Execution Commands¶

# Local Development
npm run test:e2e                    # Run all E2E tests
npm run test:e2e:headed             # Run with browser UI (debug mode)
npm run test:e2e:debug              # Run with Playwright Inspector
npm run test:e2e -- checkout-visa.spec.ts  # Run single test file
npm run test:e2e -- --grep @smoke  # Run tests with @smoke tag

# CI/CD (automatic)
# Runs on PR creation/update
# Runs on merge to main
# Runs nightly at 2 AM

# Test Data Management
npm run test:e2e:seed               # Seed test database
npm run test:e2e:clean              # Clean test database
npm run test:e2e:reset              # Reset test environment (clean + seed)

# Docker Commands
docker compose -f docker-compose.e2e.yml up -d     # Start test environment
docker compose -f docker-compose.e2e.yml down -v   # Stop and clean volumes
docker compose -f docker-compose.e2e.yml logs -f   # View logs

# Debugging
npx playwright show-report          # View HTML report
npx playwright show-trace trace.zip # View trace file

Document Information: - Created: 2025-10-25 - Last Updated: 2025-10-25 - Version: 1.0.0 - Author(s): Claude Code - Reviewers: TBD - Status: Draft - Ready for Review

Quick Checklist for Implementation¶

Phase 1: Foundation ✅¶

Phase 2: Checkout Tests¶

Phase 3: Producer Tests¶

Create Page Object Models (4 pages)
Create producer test data
Write 9 producer portal tests
Verify image uploads
Verify show appears on frontend

Phase 4: Integration¶

Review Phase¶

Estimated Timeline¶

Phase 1 (Foundation): 5 days
Phase 2 (Checkout Tests): 7 days
Phase 3 (Producer Tests): 7 days
Phase 4 (Integration): 5 days
Total: 24 working days (≈5 weeks with buffer)

Next Steps¶

✅ Review this plan with team and stakeholders
⏭️ Get approval to proceed with Phase 1
⏭️ Assign team members to tasks
⏭️ Schedule kickoff meeting
⏭️ Begin Phase 1 implementation