flights_web_raw/TASKS_56-59_README.md

# Tasks 56-59: Visual Regression Testing & Final Validation

## Overview

Tasks 56-59 comprise the final phase of the Angular→React migration, focusing on visual regression testing and comprehensive validation to ensure complete parity between the original Angular application and the new React implementation.

## Task Descriptions

### Task 56: Generate BackstopJS Baseline from Angular
**Objective:** Capture the Angular application as the immutable visual reference

**What Happens:**
1. Start Angular development server on `localhost:3000`
2. Run BackstopJS reference capture with `backstop-angular.json`
3. Capture screenshots of 4 major pages across 3 responsive viewports
4. Save 12 baseline PNG images to `e2e/backstop/bitmaps_reference/`
5. Commit baseline images to git

**Outcome:** Angular serves as the permanent visual baseline

**Duration:** ~20 minutes

---

### Task 57: Run BackstopJS Comparison on React
**Objective:** Compare React implementation against the Angular baseline

**What Happens:**
1. Start React development server on `localhost:3001` (Angular still running)
2. Run BackstopJS test comparison with `backstop-react.json`
3. Capture React screenshots at same locations and viewports
4. Compare pixel-by-pixel against Angular baseline
5. Generate HTML visual diff report
6. Document any visual differences found

**Outcome:** Identify all visual disparities between Angular and React

**Duration:** ~20 minutes

---

### Task 58: Fix Visual Differences (Iterative)
**Objective:** Update React CSS to achieve pixel-perfect visual parity

**What Happens:**
1. For each visual difference found in Task 57:
   - Identify affected React component
   - Compare CSS between Angular and React versions
   - Update React SCSS to match Angular
   - Re-run BackstopJS test for that scenario
   - Verify difference is resolved (0%)
2. Iterate until all scenarios pass at 0% difference

**Outcome:** Complete visual parity with Angular

**Duration:** Variable (30 min - 4 hours depending on differences)

---

### Task 59: Run Full Validation Suite
**Objective:** Execute comprehensive validation of complete parity

**What Happens:**
1. Run Cypress e2e test suite (1,225+ tests)
   - Test functional parity across all features
   - Verify navigation, interactions, responsiveness
   - Confirm accessibility and error handling
2. Run final BackstopJS visual validation
   - Verify all 12 scenarios at 0% difference
3. Generate comprehensive validation report
4. Commit all results to git

**Outcome:** Confirmed 100% functional and visual parity

**Duration:** ~25 minutes

---

## Files & Configuration

### BackstopJS Configuration Files
```
e2e/backstop/backstop-angular.json    - Angular baseline config (port 3000)
e2e/backstop/backstop-react.json      - React comparison config (port 3001)
```

### Engine Scripts
```
e2e/backstop/engine_scripts/puppet/runBefore.js   - Pre-capture setup
e2e/backstop/engine_scripts/puppet/runAfter.js    - Post-capture cleanup
e2e/backstop/engine_scripts/onBefore.js           - Additional setup
e2e/backstop/engine_scripts/onReady.js            - Ready state handling
```

### Test Output Directories
```
e2e/backstop/bitmaps_reference/       - Angular baseline images
e2e/backstop/bitmaps_test_react/      - React comparison images
e2e/backstop/html_report_react/       - Visual diff HTML report
e2e/cypress/screenshots/               - Cypress failure screenshots
e2e/cypress/videos/                    - Cypress recordings (if enabled)
```

### Test Files
```
e2e/cypress.config.ts                  - Cypress configuration
e2e/cypress/integration/               - Test suite files
e2e/package.json                       - E2E dependencies and scripts
```

## Test Scenarios

BackstopJS tests 4 major application pages across 3 responsive breakpoints:

| Page | Desktop | Tablet | Mobile | Notes |
|------|---------|--------|--------|-------|
| Start Page | ✓ | ✓ | ✓ | Home/landing page |
| Online Board - Arrivals | ✓ | ✓ | ✓ | Flight board display |
| Schedule Page | ✓ | ✓ | ✓ | Flight schedule |
| Flights Map | ✓ | ✓ | ✓ | Interactive map view |

**Total Scenarios:** 12 (4 pages × 3 viewports)

### Viewport Sizes
- **Desktop:** 1440×900 (primary)
- **Tablet:** 768×1024 (secondary)
- **Mobile:** 375×667 (tertiary)

## Key Dependencies

### NPM Packages
- `backstopjs`: ^6.3.0 - Visual regression testing
- `cypress`: ^13.6.0 - E2E testing
- `puppeteer`: (via backstopjs) - Browser automation

### Development Servers
- **Angular:** Port 3000 (reference implementation)
- **React:** Port 3001 (test target)

### Required Data-TestID Attributes
Both Angular and React must include these attributes:
```html
<!-- Page ready selectors -->
<div data-testid="page-loaded">...</div>
<div data-testid="board-page-loaded">...</div>
<div data-testid="schedule-page-loaded">...</div>
<div data-testid="flights-map-loaded">...</div>

<!-- Test element selectors -->
<button data-testid="search-button">...</button>
<input data-testid="search-input" />
<!-- etc. -->
```

## Execution Flow

### Pre-Execution
1. Verify Tasks 1-55 complete
2. Verify all dependencies installed
3. Verify ports 3000 and 3001 available
4. Verify data-testid attributes in both apps

### During Tasks 56-59
```
START
  ↓
Task 56: Generate Angular Baseline
  ├─ Start Angular on :3000
  ├─ Run BackstopJS reference
  ├─ Verify 12+ images created
  └─ Commit baseline
  ↓
Task 57: Compare React to Baseline
  ├─ Start React on :3001
  ├─ Run BackstopJS test
  ├─ Review HTML report
  └─ Document differences
  ↓
Task 58: Fix Visual Differences (ITERATIVE)
  ├─ For each difference:
  │  ├─ Identify component
  │  ├─ Update React CSS
  │  ├─ Test scenario
  │  └─ Commit fix
  └─ Repeat until 0% difference
  ↓
Task 59: Full Validation
  ├─ Run Cypress (1,225+ tests)
  ├─ Run BackstopJS final
  ├─ Generate validation report
  └─ Commit all results
  ↓
END
```

## Documentation Reference

### Quick Start
- **[TASKS_56-59_QUICK_REFERENCE.md](./TASKS_56-59_QUICK_REFERENCE.md)** - Checklist and quick commands

### Detailed Guides
- **[RUN_TASKS_56-59.md](./RUN_TASKS_56-59.md)** - Step-by-step execution instructions

### Background & Rationale
- **[TASKS_56-59_IMPLEMENTATION.md](./TASKS_56-59_IMPLEMENTATION.md)** - Detailed implementation guide

### Project Status
- **[IMPLEMENTATION_STATUS.md](./IMPLEMENTATION_STATUS.md)** - Overall project status and progress

## Success Criteria

### Task 56 ✅
- [ ] Angular baseline images exist (12+)
- [ ] Files in `e2e/backstop/bitmaps_reference/`
- [ ] Commit created with message: "test: generate BackstopJS baseline from Angular version"

### Task 57 ✅
- [ ] React test images exist (12+)
- [ ] HTML report generated at `e2e/backstop/html_report_react/index.html`
- [ ] Report accessible and shows comparison results
- [ ] Commit created with message: "test: run BackstopJS comparison - React vs Angular baseline"

### Task 58 ✅
- [ ] All visual differences from Task 57 identified
- [ ] React CSS updated for each difference
- [ ] Each scenario re-tested and shows 0% difference
- [ ] Git commits created for each CSS fix

### Task 59 ✅
- [ ] Cypress: 1,225+ tests ALL PASSING
- [ ] BackstopJS: 12 scenarios ALL PASSING (0% visual difference)
- [ ] Validation report created (`e2e/VALIDATION_REPORT.txt`)
- [ ] Commit created with message: "test: complete full validation suite - Angular/React parity verified"

## Common Issues & Solutions

### Issue: Port Already in Use
```bash
# Kill existing process
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9
```

### Issue: Data-TestID Attributes Missing
```bash
# Verify attributes exist
grep -r "data-testid=\"page-loaded\"" apps/react/
grep -r "data-testid=\"page-loaded\"" apps/angular/
```

### Issue: Visual Differences Not Resolving
```bash
# Compare CSS directly
diff apps/react/src/styles/pages/board.scss apps/angular/src/styles/pages/board.scss

# Check for CSS conflicts
grep -r "!important" apps/react/src/styles/
```

### Issue: Cypress Test Timeouts
```bash
# Increase timeout in e2e/cypress.config.ts
defaultCommandTimeout: 15000  // was 10000
```

### Issue: BackstopJS Report Not Accessible
```bash
# Verify report was generated
ls -la backstop/html_report_react/

# Check for errors in BackstopJS output
npx backstop test --config=backstop/backstop-react.json --debug
```

## Command Reference

### Start Servers
```bash
# Angular on port 3000
cd apps/angular && npm start

# React on port 3001
cd apps/react && npm run dev
```

### Run Tests
```bash
cd e2e

# Task 56: Generate baseline
npm run backstop:reference

# Tasks 57/59: Run comparison/validation
npm run backstop:test

# Task 59: Run Cypress tests
npm run cypress:run
npm run cypress:open  # Interactive mode

# Run specific BackstopJS scenario
npx backstop test --config=backstop/backstop-react.json --filter="Start Page"
```

### Git Operations
```bash
# Check status
git status

# View recent commits
git log --oneline | head -10

# Add and commit
git add <files>
git commit -m "message"

# Push to remote
git push origin main
```

## Time Estimates

| Task | Duration | Variable |
|------|----------|----------|
| Setup & Verification | 10 min | No |
| Task 56 | 20 min | No |
| Task 57 | 20 min | No |
| Task 58 | 30 min - 4 hours | Yes (depends on differences) |
| Task 59 | 25 min | No |
| **Total** | **105 min - 3.5 hours** | **Task 58 dependent** |

## Post-Task Actions

1. **Code Review** - Have team review React implementation
2. **Performance Testing** - Compare React vs Angular metrics
3. **User Acceptance Testing** - Have stakeholders test
4. **Production Build** - `cd apps/react && npm run build`
5. **Production Deployment** - Follow deployment process
6. **Monitoring** - Monitor React app in production

## References

### Internal Documentation
- [TASKS_56-59_QUICK_REFERENCE.md](./TASKS_56-59_QUICK_REFERENCE.md) - Quick checklist
- [RUN_TASKS_56-59.md](./RUN_TASKS_56-59.md) - Detailed execution guide
- [TASKS_56-59_IMPLEMENTATION.md](./TASKS_56-59_IMPLEMENTATION.md) - Implementation details
- [IMPLEMENTATION_STATUS.md](./IMPLEMENTATION_STATUS.md) - Project status

### External Resources
- [BackstopJS Documentation](https://garris.github.io/BackstopJS/)
- [Cypress Documentation](https://docs.cypress.io/)
- [Angular Testing Guide](https://angular.io/guide/testing)
- [React Testing Guide](https://reactjs.org/docs/testing.html)

## Support

For issues or questions:

1. Check [TASKS_56-59_QUICK_REFERENCE.md](./TASKS_56-59_QUICK_REFERENCE.md) for quick fixes
2. Review [RUN_TASKS_56-59.md](./RUN_TASKS_56-59.md) for detailed steps
3. Check [TASKS_56-59_IMPLEMENTATION.md](./TASKS_56-59_IMPLEMENTATION.md) for technical details
4. Review git commit history for recent changes
5. Check BackstopJS and Cypress documentation

## Status

**Current:** Infrastructure prepared, awaiting Tasks 1-55 completion

- ✅ Tasks 1-10: Complete
- ⏳ Tasks 11-55: In progress
- ⏳ Tasks 56-59: Ready to execute

## Version

- **Document Version:** 1.0
- **Last Updated:** 2026-04-05
- **Status:** Ready for Tasks 56-59 Execution