From 30cad656b49822d12fa21427dc34146b9f8fe2e0 Mon Sep 17 00:00:00 2001 From: gnezim Date: Sun, 5 Apr 2026 19:23:45 +0300 Subject: [PATCH] docs: add comprehensive Tasks 56-59 implementation guide --- TASKS_56-59_IMPLEMENTATION.md | 375 ++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 TASKS_56-59_IMPLEMENTATION.md diff --git a/TASKS_56-59_IMPLEMENTATION.md b/TASKS_56-59_IMPLEMENTATION.md new file mode 100644 index 000000000..88b71ffe6 --- /dev/null +++ b/TASKS_56-59_IMPLEMENTATION.md @@ -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