flights_web_raw/TASKS_56-59_QUICK_REFERENCE.md

Tasks 56-59 Quick Reference Checklist

Quick start guide for visual regression testing and validation

---

Pre-Execution Verification

Before starting Tasks 56-59, verify:

Tasks 1-55 Status:
  [ ] Task 1-3: Monorepo structure created
  [ ] Task 4-10: React components scaffolded
  [ ] Task 11-15: BackstopJS infrastructure ready
  [ ] Task 16-55: Test suite created (1,225+ tests)
  
Component Checklist:
  [ ] React pages mirror Angular functionality
  [ ] All data-testid attributes present in both apps:
      - [data-testid="page-loaded"]
      - [data-testid="board-page-loaded"]
      - [data-testid="schedule-page-loaded"]
      - [data-testid="flights-map-loaded"]
  
Environment Checklist:
  [ ] npm install (root)
  [ ] cd e2e && npm install
  [ ] cd apps/angular && npm install
  [ ] cd apps/react && npm install
  [ ] Ports 3000 and 3001 available
  
Files Ready:
  [ ] e2e/backstop/backstop-angular.json
  [ ] e2e/backstop/backstop-react.json
  [ ] e2e/backstop/engine_scripts/puppet/runBefore.js
  [ ] e2e/backstop/engine_scripts/puppet/runAfter.js

---

Task 56: Generate Angular Baseline

Quick Commands

# Terminal 1: Start Angular
cd apps/angular
npm start
# Wait: ~15 seconds for "✓ Compiled successfully"

# Terminal 2 (or same after Angular starts): Generate baseline
cd e2e
npm run backstop:reference
# Wait: ~1-3 minutes

Verification

ls -la backstop/bitmaps_reference/ | wc -l
# Should show: 15+ files (12 images + metadata)

Commit

git add e2e/backstop/bitmaps_reference/
git commit -m "test: generate BackstopJS baseline from Angular version"

Success Criteria

• Angular running on port 3000
• Baseline images in bitmaps_reference/
• 12+ PNG images created
• Committed to git

Time Estimate: 20 minutes

---

Task 57: Compare React to Baseline

Quick Commands

# Terminal 1: Angular still running (from Task 56)
# Keep it running on port 3000

# Terminal 2: Start React
cd apps/react
npm run dev
# Wait: ~10 seconds for "Local: http://localhost:3001"

# Terminal 3: Run comparison
cd e2e
npm run backstop:test
# Wait: ~2-4 minutes

View Report

open backstop/html_report_react/index.html

# Or view results summary
cat backstop/html_report_react/config.json | grep -i "results\|fail\|pass"

Document Differences

# Note any FAIL scenarios for Task 58
# Categories:
#   - Spacing/Padding
#   - Colors
#   - Typography
#   - Borders/Shadows
#   - Component Size
#   - Layout/Alignment

Commit

git add e2e/backstop/bitmaps_test_react/
git add e2e/backstop/html_report_react/
git commit -m "test: run BackstopJS comparison - React vs Angular baseline"

Success Criteria

• React running on port 3001
• BackstopJS test completed
• HTML report generated
• Test images in bitmaps_test_react/
• Differences documented
• Results committed

Time Estimate: 20 minutes

---

Task 58: Fix Visual Differences

For Each Failing Scenario

1. Identify
   [ ] Component name from diff report
   [ ] CSS file location
   [ ] Type of difference (spacing, color, etc.)

2. Compare
   [ ] React SCSS: apps/react/src/styles/...
   [ ] Angular SCSS: apps/angular/src/styles/...
   [ ] Identify differences

3. Update
   [ ] Edit React SCSS file
   [ ] Match Angular styling
   [ ] Save file (auto-rebuilds)

4. Test
   [ ] Wait for React rebuild
   [ ] Run single scenario test:
       npx backstop test --config=backstop/backstop-react.json --filter="Scenario Name"
   [ ] Check for 0% difference

5. Commit
   [ ] git add apps/react/src/styles/...
   [ ] git commit -m "fix: resolve [Component] visual differences"

6. Repeat for next failure

Common CSS Properties to Check

// Spacing Issues
padding: 16px;      // Match value
margin: 10px;       // Match value
gap: 8px;           // Flexbox gap
line-height: 1.5;   // Text spacing

// Color Issues
color: #000;        // Normalize hex (fff vs ffffff)
background: #fff;   // Check RGB vs hex
border: 1px solid;  // Verify thickness

// Typography Issues
font-family: Arial;     // Verify font
font-size: 14px;        // Check size
font-weight: 500;       // Check weight
letter-spacing: 0.5px;  // Check tracking

// Layout Issues
display: flex;           // Verify layout type
flex-direction: column;  // Check direction
align-items: center;     // Verify alignment
justify-content: space-between;  // Check distribution

// Borders/Shadows
border: 1px solid #ddd;       // Check border
border-radius: 4px;           // Check radius
box-shadow: 0 1px 3px rgba(); // Check shadow

Iteration Loop

# Quick test cycle for one scenario
while [ $diff_percentage -gt 0 ]; do
  1. Edit SCSS file
  2. Save (auto-rebuild)
  3. Wait ~5 seconds
  4. npx backstop test --filter="Scenario"
  5. Check diff_percentage in report
done

Commit Examples

# Single component fix
git commit -m "fix: resolve Online Board spacing differences

- Adjust padding from 20px to 16px
- Update margin-bottom to match Angular
- Difference reduced from 2.5% to 0%"

# Multiple property fix
git commit -m "fix: resolve Schedule Page color and typography

- Update text color from #333 to #000
- Adjust font-size from 13px to 14px
- Fix line-height from 1.4 to 1.5
- Difference reduced from 1.8% to 0%"

Success Criteria

• All visual differences identified
• React CSS updated for each difference
• Individual scenario tests run and pass
• Final BackstopJS test shows 0% failures
• All fixes committed with clear messages

Time Estimate: Variable (depends on number of differences)

• 0-2 differences: ~30 minutes
• 3-5 differences: ~1-2 hours
• 6+ differences: ~2-4 hours

---

Task 59: Full Validation Suite

Quick Commands

# Terminal 1: Angular on port 3000
cd apps/angular
npm start

# Terminal 2: React on port 3001
cd apps/react
npm run dev

# Terminal 3: Run validation
cd e2e

# Run Cypress tests
npm run cypress:run
# Wait: ~15-20 minutes for 1,225+ tests

# Run final BackstopJS test
npm run backstop:test
# Wait: ~2-4 minutes

# View BackstopJS report
open backstop/html_report_react/index.html

Generate Validation Report

cat > e2e/VALIDATION_REPORT.txt << 'EOF'
# Aeroflot Flights Web - Validation Report
Date: $(date)

## Cypress E2E Tests
- Total: 1,225+
- Status: ALL PASSING ✓

## BackstopJS Visual Tests
- Scenarios: 12
- Status: ALL PASSING ✓ (0% difference)

## Conclusion
Angular → React migration VERIFIED COMPLETE
EOF

Commit Final Results

git add e2e/backstop/bitmaps_test_react/
git add e2e/backstop/html_report_react/
git add e2e/VALIDATION_REPORT.txt
git add e2e/cypress/screenshots/
git add e2e/cypress/videos/

git commit -m "test: complete full validation suite - Angular/React parity verified

- Cypress: 1,225+ tests ALL PASSING ✓
- BackstopJS: 12 scenarios ALL PASSING ✓ (0% visual difference)
- Full functional and visual parity confirmed
- Ready for production deployment"

Success Criteria

• Both servers running (3000 + 3001)
• Cypress tests: 1,225+ passing
• BackstopJS: 12 scenarios passing (0% difference)
• Validation report created
• All results committed
• Working directory clean

Time Estimate: 25-30 minutes

---

Complete Task Sequence (Fast Path)

If all setup is correct and no visual differences exist:

# ~90 minutes total

# Setup (once)
npm install && cd e2e && npm install && cd ..
cd apps/angular && npm install && cd ../..
cd apps/react && npm install && cd ../..

# Task 56 (20 min)
cd apps/angular && npm start &
sleep 15
cd ../..
cd e2e && npm run backstop:reference
git add e2e/backstop/bitmaps_reference/ && git commit -m "test: generate baseline"

# Task 57 (20 min)
cd apps/react && npm run dev &
sleep 10
cd ../..
cd e2e && npm run backstop:test
git add e2e/backstop/bitmaps_test_react/ e2e/backstop/html_report_react/
git commit -m "test: run comparison"

# Task 58 (5 min if no differences)
# (Review report - if 0% difference, skip fixes)

# Task 59 (25 min)
cd e2e && npm run cypress:run && npm run backstop:test
git add e2e/* && git commit -m "test: complete validation"

# Cleanup
kill %1 %2  # Stop both servers

---

Troubleshooting Quick Fixes

Port In Use

lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9

BackstopJS Fails

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

# Verify BackstopJS can access localhost:3000/3001
curl http://localhost:3000
curl http://localhost:3001

# Re-run with debug
npx backstop test --config=backstop/backstop-react.json --debug

Cypress Timeouts

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

# Re-run
npm run cypress:run

Visual Differences

# Manually inspect the diff report
open backstop/html_report_react/index.html

# Check CSS file names
find apps/react/src/styles -name "*.scss" | sort

# Compare specific files
diff apps/react/src/styles/pages/board.scss apps/angular/src/styles/pages/board.scss

---

Success Indicators Checklist

Task 56 Complete ✅

• Angular server running
• backstop/bitmaps_reference/ contains 12+ PNG images
• All images > 50KB, < 1MB
• Committed: test: generate BackstopJS baseline from Angular version

Task 57 Complete ✅

• React server running
• backstop/bitmaps_test_react/ contains 12+ PNG images
• backstop/html_report_react/index.html exists and opens
• Report shows comparison results for each scenario
• Committed: test: run BackstopJS comparison - React vs Angular baseline

Task 58 Complete ✅

• All failing scenarios identified from Task 57
• React SCSS files updated for each difference
• Individual scenario tests run and passed (0% difference)
• All CSS fixes committed with descriptive messages
• Final npm run backstop:test shows 0% failures

Task 59 Complete ✅

• Cypress: npm run cypress:run completes with ALL PASSING
• BackstopJS: npm run backstop:test shows 12/12 PASSING
• VALIDATION_REPORT.txt created and committed
• Committed: test: complete full validation suite
• git status shows clean working directory

---

File Locations Reference

Critical Files:
  e2e/backstop/backstop-angular.json
  e2e/backstop/backstop-react.json
  e2e/backstop/engine_scripts/puppet/runBefore.js
  e2e/backstop/engine_scripts/puppet/runAfter.js
  e2e/cypress.config.ts
  e2e/package.json

Output Directories:
  e2e/backstop/bitmaps_reference/        [Task 56 output]
  e2e/backstop/bitmaps_test_react/       [Task 57 output]
  e2e/backstop/html_report_react/        [Task 57 report]
  e2e/cypress/screenshots/                [Cypress failures]
  e2e/cypress/videos/                     [Cypress recordings]

React Components:
  apps/react/src/app/pages/StartPage.tsx
  apps/react/src/app/pages/OnlineBoard.tsx
  apps/react/src/app/pages/SchedulePage.tsx
  apps/react/src/app/pages/FlightsMapPage.tsx

Angular Reference:
  apps/angular/src/app/pages/
  apps/angular/src/styles/

---

Key Commands

# Start Servers
apps/angular: npm start                    # Port 3000
apps/react:   npm run dev                  # Port 3001

# E2E Tests
e2e: npm run backstop:reference            # Task 56
e2e: npm run backstop:test                 # Tasks 57, 58, 59
e2e: npm run cypress:run                   # Task 59
e2e: npm run cypress:open                  # Interactive

# Specific BackstopJS Scenario
npx backstop test --config=backstop/backstop-react.json --filter="Start Page"

# Git Operations
git status
git add [files]
git commit -m "message"
git log --oneline | head -10

---

Final Checklist

Before Starting Tasks 56-59:
  [ ] All Tasks 1-55 complete
  [ ] Git repository clean
  [ ] All dependencies installed
  [ ] Both ports 3000 and 3001 available
  [ ] Data-testid attributes in both apps

Task 56 (Generate Baseline):
  [ ] Angular server starts
  [ ] BackstopJS captures baseline
  [ ] 12+ images in bitmaps_reference/
  [ ] Results committed

Task 57 (Compare React):
  [ ] React server starts
  [ ] BackstopJS runs comparison
  [ ] Report generated
  [ ] Differences documented
  [ ] Results committed

Task 58 (Fix Differences):
  [ ] All differences identified
  [ ] React CSS updated
  [ ] Each scenario tested individually
  [ ] Final test shows 0% failures
  [ ] All fixes committed

Task 59 (Full Validation):
  [ ] Both servers running
  [ ] Cypress tests: 1,225+ passing
  [ ] BackstopJS: 12/12 passing
  [ ] Validation report created
  [ ] All results committed
  [ ] Servers stopped

Post-Completion:
  [ ] Review commit history
  [ ] Verify clean git status
  [ ] Archive backup
  [ ] Schedule code review
  [ ] Plan production deployment

---

Document Version: 1.0
Last Updated: 2026-04-05
Purpose: Quick reference for Tasks 56-59 execution
Time Estimate: 90-120 minutes (depending on visual differences)