# Tasks 56-59: Angular→React Migration - Visual Regression Testing and Final Validation

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

**Date:** April 5, 2026

## Executive Summary

This document describes the implementation status of Tasks 56-59, which focus on visual regression testing and final validation of the Angular→React migration. The prerequisite infrastructure has been prepared to enable these tasks once Tasks 1-55 are completed.

## Current Status

### Completed Work

**Tasks 1-10:** ✅ Completed
- Monorepo structure created
- Core React components scaffolded
- React Router configuration
- Test helper infrastructure
- Git commits: 13 total (Initial commit through Task 10)

**Tasks 11-55:** ⏳ Pending
- Complete e2e test suite (1,225+ tests)
- Advanced component implementations
- BackstopJS scenario definitions
- Supporting test infrastructure

### Tasks 56-59 Infrastructure: ✅ Prepared

The following infrastructure files have been created to support Tasks 56-59:

#### 1. BackstopJS Configuration Files

**File:** `e2e/backstop/backstop-angular.json`
- Defines visual regression testing scenarios for Angular baseline
- Target URL: `http://localhost:3000` (Angular development server)
- 3 viewports: desktop (1440x900), tablet (768x1024), mobile (375x667)
- 10 test scenarios covering major application pages and viewports
- Zero-difference threshold for pixel-perfect comparison

**File:** `e2e/backstop/backstop-react.json`
- Mirrors Angular configuration for React comparison
- Target URL: `http://localhost:3001` (React development server)
- Same 10 scenarios and 3 viewports for consistent testing
- Reports to separate `bitmaps_test_react/` and `html_report_react/` directories

#### 2. Engine Scripts

**File:** `e2e/backstop/engine_scripts/onBefore.js`
- Executes before each scenario capture
- Handles page navigation and viewport setup
- Waits for network idle state
- Includes animation wait times

**File:** `e2e/backstop/engine_scripts/onReady.js`
- Executes after page ready but before screenshot
- Waits for ready selectors
- Handles dynamic content loading
- Supports element hiding and removal for consistent captures
- Implements hover and click interactions

#### 3. Directory Structure

```
e2e/backstop/
├── backstop-angular.json          [NEW] Angular baseline config
├── backstop-react.json            [NEW] React comparison config
├── engine_scripts/
│   ├── onBefore.js               [NEW] Pre-capture hook
│   └── onReady.js                [NEW] Post-ready hook
├── bitmaps_reference/            [READY] Angular baseline images
├── bitmaps_test/                 [READY] Temporary test images
├── bitmaps_test_react/           [READY] React comparison images
├── html_report_react/            [READY] React visual diff report
└── results/                      [READY] Test results archive
```

## Scenario Coverage

The BackstopJS configurations test the following pages/features:

### Desktop (1440x900)
1. Home Page
2. Search Page
3. Flight Details
4. Flight Map
5. Online Board

### Tablet (768x1024)
6. Home Page
7. Search Page
8. Flight Details

### Mobile (375x667)
9. Home Page
10. Search Page

**Total Scenarios:** 10 × 2 (Angular + React) = 20 baseline + comparison captures

## Configuration Details

### BackstopJS Settings
- **Engine:** Puppeteer with sandbox disabled
- **Async Capture Limit:** 5 concurrent captures
- **Async Compare Limit:** 50 concurrent comparisons
- **Pixel Match Threshold:** 0.1 (99.9% match required)
- **Alpha Channel:** 0.1 (slight anti-aliasing tolerance)
- **Reports:** Browser and CI formats

### Ready Selectors
Each scenario waits for a data-testid attribute on the main container:
- `[data-testid='app-container']` - Home page
- `[data-testid='search-container']` - Search page
- `[data-testid='flight-details-container']` - Flight details
- `[data-testid='flights-map-container']` - Flight map
- `[data-testid='online-board-container']` - Online board

These selectors **must be present** in both Angular and React components for tests to work properly.

## Task 56: Generate BackstopJS Baseline from Angular

### Objectives
1. Start Angular development server on `localhost:3000`
2. Run BackstopJS reference capture with `backstop-angular.json` config
3. Verify 10+ baseline images created in `bitmaps_reference/`
4. Commit baseline images as immutable reference

### Expected Outcomes
- `e2e/backstop/bitmaps_reference/` populated with 20 baseline PNG files
- Each scenario captured in each viewport
- File naming: `{scenario-label}_{viewport}_{platform}.png`

### Preconditions
- Angular development server must be running on port 3000
- All dependencies installed (`npm install` in root and e2e/)
- BackstopJS installed (`npm install` in e2e/)

### Execution Script Template
```bash
cd apps/angular
npm start &
ANGULAR_PID=$!
sleep 15
cd ../..
cd e2e
npx backstop reference --config=backstop/backstop-angular.json
```

## Task 57: Run BackstopJS Comparison on React

### Objectives
1. Start React development server on `localhost:3001` (Angular still running)
2. Run BackstopJS test comparison against baseline
3. Generate visual diff HTML report
4. Document any visual differences found
5. Commit test results and report

### Expected Outcomes
- React screenshots captured in `bitmaps_test_react/`
- Diff images showing pixel differences in `html_report_react/`
- HTML report viewable at `e2e/backstop/html_report_react/index.html`

### Report Analysis
The HTML report will show:
- **PASS:** Scenarios with 0% difference
- **FAIL:** Scenarios exceeding 0.1% pixel threshold
- Visual diffs highlighting changed pixels
- Side-by-side comparison of Angular vs React

### Execution Script Template
```bash
cd apps/react
npm run dev &
REACT_PID=$!
sleep 10
cd ../..
cd e2e
npx backstop test --config=backstop/backstop-react.json
```

## Task 58: Fix Any Visual Differences

### Iterative Process
For each failed scenario:

1. **Identify the difference:** Review `html_report_react/index.html`
2. **Locate the component:** Determine which React component/page has the difference
3. **Compare CSS:** Check SCSS in Angular vs React
4. **Update React styles:** Modify React component SCSS to match Angular
5. **Rebuild app:** React app auto-rebuilds on save
6. **Retest scenario:** Run BackstopJS test filter for that scenario

### Expected Outcomes
- All visual differences resolved
- React CSS matches Angular styling
- Final BackstopJS report shows 0% failure rate

### Common Difference Categories
- **Spacing/Padding:** Adjust SCSS margin/padding values
- **Font rendering:** Verify font-family and font-weight settings
- **Colors:** Check hex/rgba values against Angular version
- **Border/Shadow:** Ensure box-shadow and border styling match
- **Component size:** Verify width/height and dimension properties
- **Animation state:** Ensure no animations captured mid-frame

## Task 59: Run Full Validation Suite

### Comprehensive Validation
This final task executes all validation checks:

1. **Cypress E2E Tests:** 1,225+ functional tests across all features
   - Search functionality
   - Navigation workflows
   - Component interactions
   - Responsive design
   - Accessibility
   - Error handling
   - Internationalization
   - Performance

2. **BackstopJS Visual Tests:** Complete visual regression suite
   - 10 major scenarios
   - 3 viewport sizes
   - Pixel-perfect comparison
   - Angular vs React parity

3. **Validation Report:** Generate summary document
   - Test execution timestamps
   - Pass/fail counts
   - Visual diff analysis
   - Parity checklist completion

### Expected Outcomes
- All Cypress tests passing
- All BackstopJS tests at 0% difference
- Validation report documenting complete parity
- Final commit with all results

### Validation Report Location
- **Cypress Results:** `e2e/cypress/videos/` and `e2e/cypress/screenshots/`
- **BackstopJS Report:** `e2e/backstop/html_report_react/index.html`
- **Summary Report:** `e2e/validation-report.txt`

## Implementation Dependencies

### Required for Tasks 56-59
- ✅ BackstopJS 6.3.0+ (in e2e/package.json)
- ✅ Cypress 13.6.0+ (in e2e/package.json)
- ✅ BackstopJS config files (created)
- ✅ Engine scripts (created)
- ⏳ Tasks 1-55 completion
- ⏳ React components with data-testid attributes
- ⏳ Angular and React development servers running

### Environment Setup
```bash
# Root directory
npm install

# E2E directory
cd e2e
npm install
cd ..

# Apps - Angular
cd apps/angular
npm install
cd ../..

# Apps - React
cd apps/react
npm install
cd ../..
```

## Key Considerations

### 1. Baseline Immutability
The Angular baseline (`bitmaps_reference/`) is the reference point and **must never be regenerated**. All differences must be fixed in React to match Angular.

### 2. Port Assignments
- Angular development server: `localhost:3000`
- React development server: `localhost:3001`
- Both servers run simultaneously during Task 57

### 3. Data-TestID Requirements
All major components must include `data-testid` attributes matching the `readySelector` values in the configurations:
- App container: `data-testid="app-container"`
- Search page: `data-testid="search-container"`
- Flight details: `data-testid="flight-details-container"`
- Flight map: `data-testid="flights-map-container"`
- Online board: `data-testid="online-board-container"`

### 4. Visual Diff Interpretation
- **0% difference:** Scenarios are pixel-perfect matches
- **0.1% difference:** Acceptable variations (anti-aliasing, subpixel rendering)
- **> 0.1% difference:** Requires investigation and fixes

### 5. Timing Considerations
- Network idle waits: 500-2000ms
- Animation waits: 500ms default
- Page load timeouts: 5000ms
- Screenshot capture: After all dynamic content loads

## Success Criteria

### Task 56 Success
- [ ] Angular development server starts successfully
- [ ] BackstopJS captures 10 baseline scenarios
- [ ] 20 baseline images created in `bitmaps_reference/`
- [ ] Git commit includes baseline images

### Task 57 Success
- [ ] React development server starts on port 3001
- [ ] BackstopJS compares all 10 scenarios
- [ ] HTML report generated at expected location
- [ ] Report shows comparison status for each scenario

### Task 58 Success
- [ ] All visual differences identified
- [ ] React SCSS updated to match Angular
- [ ] Final BackstopJS test shows 0% failures
- [ ] Git commits document each fix

### Task 59 Success
- [ ] Cypress test suite execution completes
- [ ] All 1,225+ tests pass
- [ ] BackstopJS final validation passes
- [ ] Validation report generated and committed
- [ ] Complete parity verified

## File Locations

### Core Configuration Files
- `e2e/backstop/backstop-angular.json` - Angular baseline config
- `e2e/backstop/backstop-react.json` - React comparison config
- `e2e/package.json` - Scripts: `backstop:reference` and `backstop:test`
- `e2e/cypress.config.ts` - Cypress configuration

### Engine Scripts
- `e2e/backstop/engine_scripts/onBefore.js` - Pre-capture setup
- `e2e/backstop/engine_scripts/onReady.js` - Post-ready interactions

### Application Servers
- `apps/angular/` - Angular 12 development server (npm start)
- `apps/react/` - React 18 development server (npm run dev)

### Test Results Directories
- `e2e/backstop/bitmaps_reference/` - Angular baseline images
- `e2e/backstop/bitmaps_test_react/` - React test images
- `e2e/backstop/html_report_react/` - Visual diff HTML report
- `e2e/cypress/` - Cypress test files and results

## Next Steps

1. **Complete Tasks 11-55** - Implement remaining components, test suite, and BackstopJS scenarios
2. **Prepare Angular baseline** - Ensure all data-testid attributes present in Angular components
3. **Mirror in React** - Verify React components have matching data-testid attributes
4. **Execute Task 56** - Generate Angular baseline images
5. **Execute Task 57** - Run React visual comparison
6. **Fix differences** - Iterate through Task 58 as needed
7. **Final validation** - Complete Task 59 validation suite

## References

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

---

**Document Version:** 1.0
**Last Updated:** 2026-04-05
**Author:** Implementation System