From 296baebe7fd42068168d8a700bf19502fc3033b8 Mon Sep 17 00:00:00 2001 From: gnezim Date: Sun, 5 Apr 2026 19:26:37 +0300 Subject: [PATCH] docs: add comprehensive README for Tasks 56-59 - 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 --- TASKS_56-59_README.md | 376 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 376 insertions(+) create mode 100644 TASKS_56-59_README.md diff --git a/TASKS_56-59_README.md b/TASKS_56-59_README.md new file mode 100644 index 000000000..4ba755a1d --- /dev/null +++ b/TASKS_56-59_README.md @@ -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 + +
...
+
...
+
...
+
...
+ + + + + +``` + +## 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 +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