docs: add comprehensive Tasks 56-59 implementation guide

2026-04-05 19:23:45 +03:00
parent 95f49d7deb
commit 30cad656b4
1 changed files with 375 additions and 0 deletions
@@ -0,0 +1,375 @@
+# 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