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

docs: add comprehensive README for Tasks 56-59

Browse Source 
- Overview of all 4 tasks and objectives
- File and configuration reference
- Test scenario breakdown
- Execution flow diagram
- Success criteria for each task
- Command reference
- Time estimates and next steps
This commit is contained in:
gnezim
2026-04-05 19:26:37 +03:00
parent 15028e0210
commit 296baebe7f
1 changed files with 376 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TASKS_56-59_README.md
+376
View File
@@ -0,0 +1,376 @@
# Tasks 56-59: Visual Regression Testing & Final Validation
## Overview
Tasks 56-59 comprise the final phase of the Angular→React migration, focusing on visual regression testing and comprehensive validation to ensure complete parity between the original Angular application and the new React implementation.
## Task Descriptions
### Task 56: Generate BackstopJS Baseline from Angular
**Objective:** Capture the Angular application as the immutable visual reference
**What Happens:**
1. Start Angular development server on `localhost:3000`
2. Run BackstopJS reference capture with `backstop-angular.json`
3. Capture screenshots of 4 major pages across 3 responsive viewports
4. Save 12 baseline PNG images to `e2e/backstop/bitmaps_reference/`
5. Commit baseline images to git
**Outcome:** Angular serves as the permanent visual baseline
**Duration:** ~20 minutes
---
### Task 57: Run BackstopJS Comparison on React
**Objective:** Compare React implementation against the Angular baseline
**What Happens:**
1. Start React development server on `localhost:3001` (Angular still running)
2. Run BackstopJS test comparison with `backstop-react.json`
3. Capture React screenshots at same locations and viewports
4. Compare pixel-by-pixel against Angular baseline
5. Generate HTML visual diff report
6. Document any visual differences found
**Outcome:** Identify all visual disparities between Angular and React
**Duration:** ~20 minutes
---
### Task 58: Fix Visual Differences (Iterative)
**Objective:** Update React CSS to achieve pixel-perfect visual parity
**What Happens:**
1. For each visual difference found in Task 57:
- Identify affected React component
- Compare CSS between Angular and React versions
- Update React SCSS to match Angular
- Re-run BackstopJS test for that scenario
- Verify difference is resolved (0%)
2. Iterate until all scenarios pass at 0% difference
**Outcome:** Complete visual parity with Angular
**Duration:** Variable (30 min - 4 hours depending on differences)
---
### Task 59: Run Full Validation Suite
**Objective:** Execute comprehensive validation of complete parity
**What Happens:**
1. Run Cypress e2e test suite (1,225+ tests)
- Test functional parity across all features
- Verify navigation, interactions, responsiveness
- Confirm accessibility and error handling
2. Run final BackstopJS visual validation
- Verify all 12 scenarios at 0% difference
3. Generate comprehensive validation report
4. Commit all results to git
**Outcome:** Confirmed 100% functional and visual parity
**Duration:** ~25 minutes
---
## Files & Configuration
### BackstopJS Configuration Files
```
e2e/backstop/backstop-angular.json - Angular baseline config (port 3000)
e2e/backstop/backstop-react.json - React comparison config (port 3001)
```
### Engine Scripts
```
e2e/backstop/engine_scripts/puppet/runBefore.js - Pre-capture setup
e2e/backstop/engine_scripts/puppet/runAfter.js - Post-capture cleanup
e2e/backstop/engine_scripts/onBefore.js - Additional setup
e2e/backstop/engine_scripts/onReady.js - Ready state handling
```
### Test Output Directories
```
e2e/backstop/bitmaps_reference/ - Angular baseline images
e2e/backstop/bitmaps_test_react/ - React comparison images
e2e/backstop/html_report_react/ - Visual diff HTML report
e2e/cypress/screenshots/ - Cypress failure screenshots
e2e/cypress/videos/ - Cypress recordings (if enabled)
```
### Test Files
```
e2e/cypress.config.ts - Cypress configuration
e2e/cypress/integration/ - Test suite files
e2e/package.json - E2E dependencies and scripts
```
## Test Scenarios
BackstopJS tests 4 major application pages across 3 responsive breakpoints:
| Page | Desktop | Tablet | Mobile | Notes |
|------|---------|--------|--------|-------|
| Start Page | ✓ | ✓ | ✓ | Home/landing page |
| Online Board - Arrivals | ✓ | ✓ | ✓ | Flight board display |
| Schedule Page | ✓ | ✓ | ✓ | Flight schedule |
| Flights Map | ✓ | ✓ | ✓ | Interactive map view |
**Total Scenarios:** 12 (4 pages × 3 viewports)
### Viewport Sizes
- **Desktop:** 1440×900 (primary)
- **Tablet:** 768×1024 (secondary)
- **Mobile:** 375×667 (tertiary)
## Key Dependencies
### NPM Packages
- `backstopjs`: ^6.3.0 - Visual regression testing
- `cypress`: ^13.6.0 - E2E testing
- `puppeteer`: (via backstopjs) - Browser automation
### Development Servers
- **Angular:** Port 3000 (reference implementation)
- **React:** Port 3001 (test target)
### Required Data-TestID Attributes
Both Angular and React must include these attributes:
```html
<!-- Page ready selectors -->
<div data-testid="page-loaded">...</div>
<div data-testid="board-page-loaded">...</div>
<div data-testid="schedule-page-loaded">...</div>
<div data-testid="flights-map-loaded">...</div>
<!-- Test element selectors -->
<button data-testid="search-button">...</button>
<input data-testid="search-input" />
<!-- etc. -->
```
## Execution Flow
### Pre-Execution
1. Verify Tasks 1-55 complete
2. Verify all dependencies installed
3. Verify ports 3000 and 3001 available
4. Verify data-testid attributes in both apps
### During Tasks 56-59
```
START
↓
Task 56: Generate Angular Baseline
├─ Start Angular on :3000
├─ Run BackstopJS reference
├─ Verify 12+ images created
└─ Commit baseline
↓
Task 57: Compare React to Baseline
├─ Start React on :3001
├─ Run BackstopJS test
├─ Review HTML report
└─ Document differences
↓
Task 58: Fix Visual Differences (ITERATIVE)
├─ For each difference:
│ ├─ Identify component
│ ├─ Update React CSS
│ ├─ Test scenario
│ └─ Commit fix
└─ Repeat until 0% difference
↓
Task 59: Full Validation
├─ Run Cypress (1,225+ tests)
├─ Run BackstopJS final
├─ Generate validation report
└─ Commit all results
↓
END
```
## Documentation Reference
### Quick Start
- **[TASKS_56-59_QUICK_REFERENCE.md](./TASKS_56-59_QUICK_REFERENCE.md)** - Checklist and quick commands
### Detailed Guides
- **[RUN_TASKS_56-59.md](./RUN_TASKS_56-59.md)** - Step-by-step execution instructions
### Background & Rationale
- **[TASKS_56-59_IMPLEMENTATION.md](./TASKS_56-59_IMPLEMENTATION.md)** - Detailed implementation guide
### Project Status
- **[IMPLEMENTATION_STATUS.md](./IMPLEMENTATION_STATUS.md)** - Overall project status and progress
## Success Criteria
### Task 56 ✅
- [ ] Angular baseline images exist (12+)
- [ ] Files in `e2e/backstop/bitmaps_reference/`
- [ ] Commit created with message: "test: generate BackstopJS baseline from Angular version"
### Task 57 ✅
- [ ] React test images exist (12+)
- [ ] HTML report generated at `e2e/backstop/html_report_react/index.html`
- [ ] Report accessible and shows comparison results
- [ ] Commit created with message: "test: run BackstopJS comparison - React vs Angular baseline"
### Task 58 ✅
- [ ] All visual differences from Task 57 identified
- [ ] React CSS updated for each difference
- [ ] Each scenario re-tested and shows 0% difference
- [ ] Git commits created for each CSS fix
### Task 59 ✅
- [ ] Cypress: 1,225+ tests ALL PASSING
- [ ] BackstopJS: 12 scenarios ALL PASSING (0% visual difference)
- [ ] Validation report created (`e2e/VALIDATION_REPORT.txt`)
- [ ] Commit created with message: "test: complete full validation suite - Angular/React parity verified"
## Common Issues & Solutions
### Issue: Port Already in Use
```bash
# Kill existing process
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9
```
### Issue: Data-TestID Attributes Missing
```bash
# Verify attributes exist
grep -r "data-testid=\"page-loaded\"" apps/react/
grep -r "data-testid=\"page-loaded\"" apps/angular/
```
### Issue: Visual Differences Not Resolving
```bash
# Compare CSS directly
diff apps/react/src/styles/pages/board.scss apps/angular/src/styles/pages/board.scss
# Check for CSS conflicts
grep -r "!important" apps/react/src/styles/
```
### Issue: Cypress Test Timeouts
```bash
# Increase timeout in e2e/cypress.config.ts
defaultCommandTimeout: 15000 // was 10000
```
### Issue: BackstopJS Report Not Accessible
```bash
# Verify report was generated
ls -la backstop/html_report_react/
# Check for errors in BackstopJS output
npx backstop test --config=backstop/backstop-react.json --debug
```
## Command Reference
### Start Servers
```bash
# Angular on port 3000
cd apps/angular && npm start
# React on port 3001
cd apps/react && npm run dev
```
### Run Tests
```bash
cd e2e
# Task 56: Generate baseline
npm run backstop:reference
# Tasks 57/59: Run comparison/validation
npm run backstop:test
# Task 59: Run Cypress tests
npm run cypress:run
npm run cypress:open # Interactive mode
# Run specific BackstopJS scenario
npx backstop test --config=backstop/backstop-react.json --filter="Start Page"
```
### Git Operations
```bash
# Check status
git status
# View recent commits
git log --oneline | head -10
# Add and commit
git add <files>
git commit -m "message"
# Push to remote
git push origin main
```
## Time Estimates
| Task | Duration | Variable |
|------|----------|----------|
| Setup & Verification | 10 min | No |
| Task 56 | 20 min | No |
| Task 57 | 20 min | No |
| Task 58 | 30 min - 4 hours | Yes (depends on differences) |
| Task 59 | 25 min | No |
| **Total** | **105 min - 3.5 hours** | **Task 58 dependent** |
## Post-Task Actions
1. **Code Review** - Have team review React implementation
2. **Performance Testing** - Compare React vs Angular metrics
3. **User Acceptance Testing** - Have stakeholders test
4. **Production Build** - `cd apps/react && npm run build`
5. **Production Deployment** - Follow deployment process
6. **Monitoring** - Monitor React app in production
## References
### Internal Documentation
- [TASKS_56-59_QUICK_REFERENCE.md](./TASKS_56-59_QUICK_REFERENCE.md) - Quick checklist
- [RUN_TASKS_56-59.md](./RUN_TASKS_56-59.md) - Detailed execution guide
- [TASKS_56-59_IMPLEMENTATION.md](./TASKS_56-59_IMPLEMENTATION.md) - Implementation details
- [IMPLEMENTATION_STATUS.md](./IMPLEMENTATION_STATUS.md) - Project status
### External Resources
- [BackstopJS Documentation](https://garris.github.io/BackstopJS/)
- [Cypress Documentation](https://docs.cypress.io/)
- [Angular Testing Guide](https://angular.io/guide/testing)
- [React Testing Guide](https://reactjs.org/docs/testing.html)
## Support
For issues or questions:
1. Check [TASKS_56-59_QUICK_REFERENCE.md](./TASKS_56-59_QUICK_REFERENCE.md) for quick fixes
2. Review [RUN_TASKS_56-59.md](./RUN_TASKS_56-59.md) for detailed steps
3. Check [TASKS_56-59_IMPLEMENTATION.md](./TASKS_56-59_IMPLEMENTATION.md) for technical details
4. Review git commit history for recent changes
5. Check BackstopJS and Cypress documentation
## Status
**Current:** Infrastructure prepared, awaiting Tasks 1-55 completion
- ✅ Tasks 1-10: Complete
- ⏳ Tasks 11-55: In progress
- ⏳ Tasks 56-59: Ready to execute
## Version
- **Document Version:** 1.0
- **Last Updated:** 2026-04-05
- **Status:** Ready for Tasks 56-59 Execution