dzinesco
aa81eb5adb
- Add comprehensive analytics components with export functionality - Implement territory management with manager performance tracking - Add seatmap components for venue layout management - Create customer management features with modal interface - Add advanced hooks for dashboard flags and territory data - Implement seat selection and venue management utilities - Add type definitions for ticketing and seatmap systems 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
288 lines
8.8 KiB
Markdown
288 lines
8.8 KiB
Markdown
# Scanner PWA Field Testing Suite
|
||
|
||
This comprehensive test suite simulates real-world mobile usage scenarios that gate staff will encounter when using the BCT Scanner PWA for extended periods during events.
|
||
|
||
## Test Categories
|
||
|
||
### 1. PWA Installation Tests (`pwa-field-test.spec.ts`)
|
||
Tests the Progressive Web App functionality and installation experience:
|
||
|
||
- **Manifest Validation**: Verifies PWA manifest loads correctly with proper configuration
|
||
- **Service Worker Registration**: Tests offline capability infrastructure
|
||
- **Add to Home Screen**: Tests PWA installation flow on mobile devices
|
||
- **Camera Permissions**: Validates camera access in PWA standalone mode
|
||
- **Storage Systems**: Tests IndexedDB and Cache API for offline functionality
|
||
- **Platform Integration**: Tests vibration, notifications, and wake lock APIs
|
||
|
||
**Run with:** `npm run test:pwa`
|
||
|
||
### 2. Offline Scenarios (`offline-scenarios.spec.ts`)
|
||
Tests comprehensive offline functionality for unreliable network conditions:
|
||
|
||
- **Airplane Mode Simulation**: Complete network disconnection with queue accumulation
|
||
- **Intermittent Connectivity**: Flaky network with connect/disconnect cycles
|
||
- **Optimistic Acceptance**: Offline scan acceptance with later server reconciliation
|
||
- **Conflict Resolution**: Handles offline success vs server "already_scanned" conflicts
|
||
- **Queue Persistence**: Verifies scan queue survives browser restart/refresh
|
||
- **Sync Recovery**: Tests failed sync recovery and batch operations
|
||
|
||
**Run with:** `npm run test:offline`
|
||
|
||
### 3. Battery & Performance Tests (`battery-performance.spec.ts`)
|
||
Tests extended usage scenarios and resource management:
|
||
|
||
- **15-Minute Continuous Scanning**: Endurance test with performance monitoring
|
||
- **Thermal Throttling**: Simulates device overheating and performance adaptation
|
||
- **Memory Leak Detection**: Monitors memory usage across extended sessions
|
||
- **Rate Limiting**: Tests 8 scans/second limit and "slow down" messaging
|
||
- **Resource Monitoring**: CPU/GPU usage patterns and optimization
|
||
- **Battery Management**: Power-saving features and wake lock handling
|
||
|
||
**Run with:** `npm run test:performance` (120 second timeout)
|
||
|
||
### 4. Mobile UX Tests (`mobile-ux.spec.ts`)
|
||
Tests mobile-specific user interface and hardware interactions:
|
||
|
||
- **Touch Interactions**: Proper touch target sizes and tactile feedback
|
||
- **Device Orientation**: Portrait/landscape adaptation and rotation handling
|
||
- **Camera Switching**: Front/rear camera detection and switching
|
||
- **Torch Functionality**: Flashlight toggle for low-light scanning
|
||
- **Permission Flows**: Camera and notification permission handling
|
||
- **Vibration Feedback**: Success/error patterns for scan results
|
||
|
||
**Run with:** `npm run test:mobile`
|
||
|
||
### 5. Real-World Gate Scenarios (`real-world-gate.spec.ts`)
|
||
Tests complex scenarios from actual gate operations:
|
||
|
||
- **Network Handoff**: WiFi to cellular transitions during scanning
|
||
- **Background/Foreground**: App lifecycle management during multitasking
|
||
- **Multi-Device Racing**: Simultaneous scanning by multiple gate staff
|
||
- **Rate Limiting**: Rapid scanning prevention and recovery
|
||
- **QR Code Quality**: Various formats, lighting conditions, and damage scenarios
|
||
- **Conflict Resolution**: Race conditions and duplicate scan prevention
|
||
|
||
**Run with:** `npm run test:gate`
|
||
|
||
## Test Execution
|
||
|
||
### Individual Test Suites
|
||
```bash
|
||
# PWA functionality
|
||
npm run test:pwa
|
||
|
||
# Offline scenarios
|
||
npm run test:offline
|
||
|
||
# Performance and battery
|
||
npm run test:performance
|
||
|
||
# Mobile UX
|
||
npm run test:mobile
|
||
|
||
# Gate scenarios
|
||
npm run test:gate
|
||
|
||
# Existing scanner tests
|
||
npm run test:scanner
|
||
```
|
||
|
||
### Combined Test Runs
|
||
```bash
|
||
# All field tests (comprehensive)
|
||
npm run test:field
|
||
|
||
# All scanner-related tests
|
||
npm run test:all-scanner
|
||
|
||
# Quick field test subset
|
||
npm run test:field -- --grep "should handle"
|
||
```
|
||
|
||
### With Visual Output
|
||
```bash
|
||
# Run with headed browser (see what's happening)
|
||
npm run test:field -- --headed
|
||
|
||
# Run with Playwright UI
|
||
npm run test:field -- --ui
|
||
|
||
# Generate and view report
|
||
npm run test:field && npx playwright show-report
|
||
```
|
||
|
||
## Mobile Device Simulation
|
||
|
||
Tests automatically configure mobile viewports and behaviors:
|
||
|
||
- **iPhone SE**: 375×667 (primary test device)
|
||
- **iPhone 12**: 390×844 (secondary mobile)
|
||
- **Pixel 5**: 393×851 (Android simulation)
|
||
- **Touch Events**: Tap, swipe, and gesture simulation
|
||
- **Device APIs**: Camera, vibration, orientation, wake lock
|
||
|
||
## Performance Monitoring
|
||
|
||
### Memory Usage
|
||
- Initial memory baseline recording
|
||
- Memory growth tracking during extended sessions
|
||
- Memory leak detection (>20MB growth triggers failure)
|
||
- Garbage collection simulation
|
||
|
||
### Network Quality
|
||
- Connection type detection
|
||
- Latency measurement and adaptation
|
||
- Offline/online transition handling
|
||
- Retry mechanism validation
|
||
|
||
### Resource Optimization
|
||
- Frame rate monitoring (>15 FPS required)
|
||
- CPU usage pattern analysis
|
||
- Battery API integration testing
|
||
- Thermal throttling simulation
|
||
|
||
## Offline Testing Features
|
||
|
||
### Queue Management
|
||
- IndexedDB persistence testing
|
||
- Queue survival across browser restarts
|
||
- Batch sync operation validation
|
||
- Conflict resolution workflows
|
||
|
||
### Network Simulation
|
||
- Complete offline mode (`page.setOffline(true)`)
|
||
- Intermittent connectivity patterns
|
||
- Poor cellular network simulation
|
||
- API request failure/retry cycles
|
||
|
||
### Optimistic UI
|
||
- Immediate scan feedback when offline
|
||
- Server reconciliation upon reconnection
|
||
- Conflict handling for "offline success" vs "server denied"
|
||
- Visual feedback for sync status
|
||
|
||
## Real-World Scenarios
|
||
|
||
### Gate Operations
|
||
- Multiple staff members scanning simultaneously
|
||
- Network handoff during peak usage
|
||
- Extended scanning sessions (15+ minutes)
|
||
- Various QR code qualities and conditions
|
||
|
||
### Edge Cases
|
||
- Camera permission denied/granted flows
|
||
- App backgrounding during active scanning
|
||
- Device rotation during scan operations
|
||
- Very rapid scanning attempts (>8/second)
|
||
|
||
### Recovery Testing
|
||
- Network reconnection after extended offline periods
|
||
- Camera reinitialization after app backgrounding
|
||
- Queue sync after failed attempts
|
||
- Memory cleanup after intensive usage
|
||
|
||
## Test Data & Screenshots
|
||
|
||
### Evidence Collection
|
||
All field tests automatically capture:
|
||
- Screenshots on test failures
|
||
- Full-page screenshots for mobile layouts
|
||
- Video recordings of complex interactions
|
||
- Performance metrics and console logs
|
||
|
||
### Test Artifacts
|
||
```
|
||
test-results/
|
||
├── screenshots/ # Failure screenshots
|
||
├── videos/ # Test execution videos
|
||
├── traces/ # Detailed execution traces
|
||
└── results.json # Test results summary
|
||
```
|
||
|
||
### Viewing Results
|
||
```bash
|
||
# Open HTML report with artifacts
|
||
npx playwright show-report
|
||
|
||
# View specific test traces
|
||
npx playwright show-trace test-results/trace.zip
|
||
```
|
||
|
||
## CI/CD Integration
|
||
|
||
### GitHub Actions Configuration
|
||
```yaml
|
||
- name: Run Field Tests
|
||
run: |
|
||
npm run test:field -- --reporter=github
|
||
env:
|
||
CI: true
|
||
```
|
||
|
||
### Performance Thresholds
|
||
- Memory growth: <20MB over 15 minutes
|
||
- Average FPS: >15 during scanning
|
||
- Scan processing: <1000ms average
|
||
- Queue sync: <5 seconds for 10 items
|
||
|
||
### Mobile Testing in CI
|
||
Tests run on:
|
||
- Chromium with mobile emulation
|
||
- WebKit (Safari simulation)
|
||
- Firefox mobile viewport
|
||
|
||
## Troubleshooting
|
||
|
||
### Common Issues
|
||
|
||
1. **Camera Permission Tests Failing**
|
||
- Ensure browser allows camera access in headless mode
|
||
- Use `--headed` flag to see permission dialogs
|
||
|
||
2. **Performance Tests Timeout**
|
||
- Increase timeout: `--timeout=180000` (3 minutes)
|
||
- Run individually: `npm run test:performance`
|
||
|
||
3. **Mobile Viewport Issues**
|
||
- Tests set viewport automatically
|
||
- Check `page.setViewportSize()` calls in test logs
|
||
|
||
4. **Offline Tests Not Working**
|
||
- Verify `page.setOffline()` support
|
||
- Check navigator.onLine overrides in test logs
|
||
|
||
### Debug Mode
|
||
```bash
|
||
# Debug specific test
|
||
npm run test:field -- --debug --grep "airplane mode"
|
||
|
||
# Headed mode with slow motion
|
||
npm run test:field -- --headed --slowMo=500
|
||
|
||
# Full trace collection
|
||
npm run test:field -- --trace=on
|
||
```
|
||
|
||
## Best Practices
|
||
|
||
### Test Organization
|
||
- Each test file focuses on one aspect of field usage
|
||
- Tests are grouped by real-world scenarios
|
||
- Clear naming conventions for easy identification
|
||
|
||
### Mock Data
|
||
- Realistic QR codes and scan scenarios
|
||
- Variable network conditions and response times
|
||
- Edge case simulation for robust testing
|
||
|
||
### Assertions
|
||
- Performance thresholds based on real device testing
|
||
- User experience validation (touch targets, feedback)
|
||
- Accessibility compliance verification
|
||
|
||
### Maintenance
|
||
- Regular updates for new mobile device specifications
|
||
- Performance threshold adjustments based on field feedback
|
||
- Network condition updates for realistic simulation
|
||
|
||
This comprehensive field testing suite ensures the Scanner PWA will perform reliably in actual gate operations, handling the full spectrum of mobile device challenges and network conditions that staff will encounter during live events. |