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:

<!-- 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 - Checklist and quick commands

Detailed Guides

• RUN_TASKS_56-59.md - Step-by-step execution instructions

Background & Rationale

• TASKS_56-59_IMPLEMENTATION.md - Detailed implementation guide

Project Status

• 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

# Kill existing process
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9

Issue: Data-TestID Attributes Missing

# Verify attributes exist
grep -r "data-testid=\"page-loaded\"" apps/react/
grep -r "data-testid=\"page-loaded\"" apps/angular/

Issue: Visual Differences Not Resolving

# 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

# Increase timeout in e2e/cypress.config.ts
defaultCommandTimeout: 15000  // was 10000

Issue: BackstopJS Report Not Accessible

# 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

# Angular on port 3000
cd apps/angular && npm start

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

Run Tests

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

# 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 - Quick checklist
• RUN_TASKS_56-59.md - Detailed execution guide
• TASKS_56-59_IMPLEMENTATION.md - Implementation details
• IMPLEMENTATION_STATUS.md - Project status

External Resources

• BackstopJS Documentation
• Cypress Documentation
• Angular Testing Guide
• React Testing Guide

Support

For issues or questions:

1. Check TASKS_56-59_QUICK_REFERENCE.md for quick fixes
2. Review RUN_TASKS_56-59.md for detailed steps
3. Check 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