spliit/prds/add-e2e-tests.md

End-to-End Testing Plan for Spliit

Overview

This document outlines a comprehensive E2E testing strategy for Spliit, a expense splitting application. The plan prioritizes testing the most critical user workflows while ensuring good coverage of core features.

Application Features Analysis

Based on the codebase analysis, Spliit is a group expense management application with the following key features:

Core Features

• Group Management: Create, edit, and manage expense groups with participants
• Expense Management: Add, edit, delete expenses with various categories
• Split Modes: Multiple ways to split expenses (evenly, by shares, by percentage, by amount)
• Balance Tracking: View participant balances and what they owe/are owed
• Reimbursements: Handle payments between participants
• Recurring Expenses: Set up expenses that repeat (daily, weekly, monthly)
• Document Attachments: Attach receipts/documents to expenses
• Activity Tracking: View history of group activities
• Export Functionality: Export data in CSV/JSON formats
• Statistics: View spending analytics and trends

Technical Details

• Built with Next.js 14, TypeScript, tRPC, Prisma
• Uses PostgreSQL database
• Supports multiple currencies
• Internationalized (i18n) interface
• PWA capabilities

Implementation Constraints

Test ID Strategy

During the migration, the only modification allowed to application files is adding test IDs (data-testid attributes). This constraint ensures:

• Minimal impact on production code
• No risk of introducing bugs through test implementation
• Clean separation between test infrastructure and application logic
• Easy identification of test-specific elements

Test ID Naming Convention

• Use kebab-case format: data-testid="expense-card"
• Be descriptive and specific: data-testid="balance-amount-john"
• Include context when needed: data-testid="group-participant-list"
• Avoid generic names: prefer expense-title-input over input

Test ID Implementation Guidelines

1. Strategic Placement: Add test IDs only where needed for reliable element selection
2. Minimal Footprint: Don't add test IDs to every element, focus on key interaction points
3. Future-Proof: Choose stable elements that are unlikely to change frequently
4. Documentation: Maintain a registry of added test IDs for reference

Test Development Workflow

Mandatory Process: After writing any new test, the development process must run npm run test:e2e to verify that:

• The new test passes successfully
• No existing tests are broken
• All test interactions work as expected
• Test reliability is maintained

This validation step is required before continuing with additional test development or implementation work.

Priority-Based Testing Strategy

Priority 1: Critical User Journeys (Must Have)

These are the core workflows that users perform most frequently:

1. Group Creation and Management

• Test: group-lifecycle.spec.ts
• Coverage:
  • Create a new group with basic information
  • Add participants to the group
  • Edit group details (name, currency, information)
  • Navigate between group tabs (expenses, balances, information, stats, activity, settings)

2. Basic Expense Management

• Test: expense-basic.spec.ts
• Coverage:
  • Create simple expense (equal split)
  • Edit existing expense
  • Delete expense
  • View expense details
  • Add expense notes

3. Balance Calculation and Viewing

• Test: balances-and-reimbursements.spec.ts
• Coverage:
  • View participant balances after expenses
  • Verify balance calculations are correct
  • Create reimbursement from balance view
  • Mark reimbursements as completed

Priority 2: Advanced Features (Should Have)

4. Complex Expense Splitting

• Test: expense-splitting.spec.ts
• Coverage:
  • Split by shares
  • Split by percentage
  • Split by specific amounts
  • Exclude participants from expenses
  • Verify split calculations

5. Categories and Organization

• Test: categories-and-organization.spec.ts
• Coverage:
  • Assign categories to expenses
  • Filter expenses by category
  • View category-based statistics

6. Reimbursement Workflows

• Test: reimbursement-flows.spec.ts
• Coverage:
  • Create direct reimbursement
  • Generate reimbursement from suggestion
  • Track reimbursement status
  • Multiple reimbursement scenarios

Priority 3: Advanced Functionality (Could Have)

7. Recurring Expenses

• Test: recurring-expenses.spec.ts
• Coverage:
  • Set up daily recurring expense
  • Set up weekly recurring expense
  • Set up monthly recurring expense
  • Edit/cancel recurring expenses

8. Document Management

• Test: document-management.spec.ts
• Coverage:
  • Upload receipt to expense
  • View attached documents
  • Remove documents
  • Multiple document attachments

9. Data Export and Statistics

• Test: export-and-stats.spec.ts
• Coverage:
  • Export group data as CSV
  • Export group data as JSON
  • View spending statistics
  • Verify statistical calculations

10. Activity Tracking

• Test: activity-tracking.spec.ts
• Coverage:
  • View activity feed
  • Verify activity entries for various actions
  • Activity timestamp accuracy

Priority 4: Edge Cases and Error Handling (Nice to Have)

11. Error Scenarios

• Test: error-handling.spec.ts
• Coverage:
  • Invalid input validation
  • Network error recovery
  • Large group management
  • Currency formatting edge cases

12. Multi-User Workflows

• Test: multi-user-scenarios.spec.ts
• Coverage:
  • Multiple users in same group
  • Concurrent expense creation
  • Conflict resolution

Test Implementation Structure

Page Object Model (POM) Extensions

Extend the existing POM classes:

// Additional POM classes needed:
- BalancePage.ts          // For balance viewing and interactions
- ReimbursementPage.ts    // For reimbursement workflows
- StatisticsPage.ts       // For stats and analytics
- ActivityPage.ts         // For activity tracking
- ExportPage.ts          // For data export functionality
- SettingsPage.ts        // For group settings and management

Test Data Management

// test-data/
- groups.ts              // Test group configurations
- expenses.ts            // Various expense scenarios
- participants.ts        // Participant data sets
- currencies.ts          // Different currency formats

Utility Functions

// utils/
- calculations.ts        // Balance and split calculation helpers
- currency.ts           // Currency formatting utilities
- date.ts               // Date manipulation for recurring expenses
- validation.ts         // Input validation helpers

Test Execution Strategy

Test Suites Organization

1. Smoke Tests (smoke/): Critical path tests that run on every commit

   • Basic group creation
   • Simple expense creation
   • Balance viewing

2. Regression Tests (regression/): Full feature coverage

   • All Priority 1 and 2 tests
   • Run on PRs and releases

3. Extended Tests (extended/): Comprehensive coverage

   • All priorities including edge cases
   • Run nightly or on demand

Performance Considerations

• Parallel Execution: Group tests by functionality to run in parallel
• Test Isolation: Each test should create its own group/data
• Cleanup: Implement proper test data cleanup
• Database: Consider using test database with fast reset

Browser Coverage

• Primary: Chrome (latest)
• Secondary: Firefox, Safari, Edge
• Mobile: Mobile Chrome and Safari viewports

Success Metrics

Coverage Goals

• Critical Paths: 100% coverage
• Core Features: 95% coverage
• Advanced Features: 80% coverage
• Edge Cases: 60% coverage

Quality Gates

• All Priority 1 tests must pass for deployment
• No more than 2% flaky test rate
• Test execution time under 30 minutes for full suite
• 95% test reliability score

Implementation Timeline

Phase 1 (Week 1-2): Foundation

• Identify and add required test IDs to application components
• Extend POM architecture
• Implement Priority 1 tests
• Set up test data management
• Basic CI integration

Phase 2 (Week 3-4): Core Features

• Add additional test IDs for Priority 2 features
• Implement Priority 2 tests
• Add utility functions
• Enhance test reliability
• Performance optimization

Phase 3 (Week 5-6): Advanced Features

• Complete test ID coverage for remaining features
• Implement Priority 3 tests
• Cross-browser testing setup
• Test reporting and analytics
• Documentation completion

Phase 4 (Week 7-8): Polish and Maintenance

• Finalize test ID registry and documentation
• Priority 4 tests implementation
• Test suite optimization
• Maintenance procedures
• Team training

Maintenance and Evolution

Regular Reviews

• Monthly test suite review for relevance
• Quarterly performance optimization
• Bi-annual architecture assessment

Continuous Improvement

• Monitor test flakiness and fix root causes
• Add tests for new features immediately
• Update tests when UI/UX changes
• Regular dependency updates

Risk Mitigation

Common Pitfalls

• Over-testing: Focus on user value, not code coverage
• Flaky tests: Implement proper waits and retries
• Slow execution: Optimize test data and parallel execution
• Maintenance burden: Keep tests simple and focused

Mitigation Strategies

• Regular test review and cleanup
• Investment in test infrastructure
• Clear ownership and responsibility
• Automated test health monitoring
• Mandatory test validation: Always run npm run test:e2e after each new test implementation

This plan provides a structured approach to achieving comprehensive E2E test coverage for Spliit while prioritizing the most critical user workflows and maintaining sustainable test maintenance practices.