gnezim/flights_web_raw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive Tasks 56-59 implementation guide

Browse Source
This commit is contained in:
gnezim
2026-04-05 19:23:45 +03:00
parent 95f49d7deb
commit 30cad656b4
1 changed files with 375 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TASKS_56-59_IMPLEMENTATION.md
+375
View File
@@ -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