From 9174cae4060f8aa7a77d99f7048e2d9733bcee80 Mon Sep 17 00:00:00 2001 From: gnezim Date: Sun, 5 Apr 2026 19:26:06 +0300 Subject: [PATCH] docs: add quick reference checklist for Tasks 56-59 - Pre-execution verification checklist - Quick commands for each task - Common issues and fixes - Success criteria and time estimates - Final validation checklist --- TASKS_56-59_QUICK_REFERENCE.md | 541 +++++++++++++++++++++++++++++++++ 1 file changed, 541 insertions(+) create mode 100644 TASKS_56-59_QUICK_REFERENCE.md diff --git a/TASKS_56-59_QUICK_REFERENCE.md b/TASKS_56-59_QUICK_REFERENCE.md new file mode 100644 index 000000000..2f5773a0e --- /dev/null +++ b/TASKS_56-59_QUICK_REFERENCE.md @@ -0,0 +1,541 @@ +# Tasks 56-59 Quick Reference Checklist + +**Quick start guide for visual regression testing and validation** + +--- + +## Pre-Execution Verification + +Before starting Tasks 56-59, verify: + +``` +Tasks 1-55 Status: + [ ] Task 1-3: Monorepo structure created + [ ] Task 4-10: React components scaffolded + [ ] Task 11-15: BackstopJS infrastructure ready + [ ] Task 16-55: Test suite created (1,225+ tests) + +Component Checklist: + [ ] React pages mirror Angular functionality + [ ] All data-testid attributes present in both apps: + - [data-testid="page-loaded"] + - [data-testid="board-page-loaded"] + - [data-testid="schedule-page-loaded"] + - [data-testid="flights-map-loaded"] + +Environment Checklist: + [ ] npm install (root) + [ ] cd e2e && npm install + [ ] cd apps/angular && npm install + [ ] cd apps/react && npm install + [ ] Ports 3000 and 3001 available + +Files Ready: + [ ] e2e/backstop/backstop-angular.json + [ ] e2e/backstop/backstop-react.json + [ ] e2e/backstop/engine_scripts/puppet/runBefore.js + [ ] e2e/backstop/engine_scripts/puppet/runAfter.js +``` + +--- + +## Task 56: Generate Angular Baseline + +### Quick Commands +```bash +# Terminal 1: Start Angular +cd apps/angular +npm start +# Wait: ~15 seconds for "✓ Compiled successfully" + +# Terminal 2 (or same after Angular starts): Generate baseline +cd e2e +npm run backstop:reference +# Wait: ~1-3 minutes +``` + +### Verification +```bash +ls -la backstop/bitmaps_reference/ | wc -l +# Should show: 15+ files (12 images + metadata) +``` + +### Commit +```bash +git add e2e/backstop/bitmaps_reference/ +git commit -m "test: generate BackstopJS baseline from Angular version" +``` + +### Success Criteria +- [ ] Angular running on port 3000 +- [ ] Baseline images in `bitmaps_reference/` +- [ ] 12+ PNG images created +- [ ] Committed to git + +**Time Estimate:** 20 minutes + +--- + +## Task 57: Compare React to Baseline + +### Quick Commands +```bash +# Terminal 1: Angular still running (from Task 56) +# Keep it running on port 3000 + +# Terminal 2: Start React +cd apps/react +npm run dev +# Wait: ~10 seconds for "Local: http://localhost:3001" + +# Terminal 3: Run comparison +cd e2e +npm run backstop:test +# Wait: ~2-4 minutes +``` + +### View Report +```bash +open backstop/html_report_react/index.html + +# Or view results summary +cat backstop/html_report_react/config.json | grep -i "results\|fail\|pass" +``` + +### Document Differences +```bash +# Note any FAIL scenarios for Task 58 +# Categories: +# - Spacing/Padding +# - Colors +# - Typography +# - Borders/Shadows +# - Component Size +# - Layout/Alignment +``` + +### Commit +```bash +git add e2e/backstop/bitmaps_test_react/ +git add e2e/backstop/html_report_react/ +git commit -m "test: run BackstopJS comparison - React vs Angular baseline" +``` + +### Success Criteria +- [ ] React running on port 3001 +- [ ] BackstopJS test completed +- [ ] HTML report generated +- [ ] Test images in `bitmaps_test_react/` +- [ ] Differences documented +- [ ] Results committed + +**Time Estimate:** 20 minutes + +--- + +## Task 58: Fix Visual Differences + +### For Each Failing Scenario + +``` +1. Identify + [ ] Component name from diff report + [ ] CSS file location + [ ] Type of difference (spacing, color, etc.) + +2. Compare + [ ] React SCSS: apps/react/src/styles/... + [ ] Angular SCSS: apps/angular/src/styles/... + [ ] Identify differences + +3. Update + [ ] Edit React SCSS file + [ ] Match Angular styling + [ ] Save file (auto-rebuilds) + +4. Test + [ ] Wait for React rebuild + [ ] Run single scenario test: + npx backstop test --config=backstop/backstop-react.json --filter="Scenario Name" + [ ] Check for 0% difference + +5. Commit + [ ] git add apps/react/src/styles/... + [ ] git commit -m "fix: resolve [Component] visual differences" + +6. Repeat for next failure +``` + +### Common CSS Properties to Check + +```scss +// Spacing Issues +padding: 16px; // Match value +margin: 10px; // Match value +gap: 8px; // Flexbox gap +line-height: 1.5; // Text spacing + +// Color Issues +color: #000; // Normalize hex (fff vs ffffff) +background: #fff; // Check RGB vs hex +border: 1px solid; // Verify thickness + +// Typography Issues +font-family: Arial; // Verify font +font-size: 14px; // Check size +font-weight: 500; // Check weight +letter-spacing: 0.5px; // Check tracking + +// Layout Issues +display: flex; // Verify layout type +flex-direction: column; // Check direction +align-items: center; // Verify alignment +justify-content: space-between; // Check distribution + +// Borders/Shadows +border: 1px solid #ddd; // Check border +border-radius: 4px; // Check radius +box-shadow: 0 1px 3px rgba(); // Check shadow +``` + +### Iteration Loop +```bash +# Quick test cycle for one scenario +while [ $diff_percentage -gt 0 ]; do + 1. Edit SCSS file + 2. Save (auto-rebuild) + 3. Wait ~5 seconds + 4. npx backstop test --filter="Scenario" + 5. Check diff_percentage in report +done +``` + +### Commit Examples +```bash +# Single component fix +git commit -m "fix: resolve Online Board spacing differences + +- Adjust padding from 20px to 16px +- Update margin-bottom to match Angular +- Difference reduced from 2.5% to 0%" + +# Multiple property fix +git commit -m "fix: resolve Schedule Page color and typography + +- Update text color from #333 to #000 +- Adjust font-size from 13px to 14px +- Fix line-height from 1.4 to 1.5 +- Difference reduced from 1.8% to 0%" +``` + +### Success Criteria +- [ ] All visual differences identified +- [ ] React CSS updated for each difference +- [ ] Individual scenario tests run and pass +- [ ] Final BackstopJS test shows 0% failures +- [ ] All fixes committed with clear messages + +**Time Estimate:** Variable (depends on number of differences) +- 0-2 differences: ~30 minutes +- 3-5 differences: ~1-2 hours +- 6+ differences: ~2-4 hours + +--- + +## Task 59: Full Validation Suite + +### Quick Commands +```bash +# Terminal 1: Angular on port 3000 +cd apps/angular +npm start + +# Terminal 2: React on port 3001 +cd apps/react +npm run dev + +# Terminal 3: Run validation +cd e2e + +# Run Cypress tests +npm run cypress:run +# Wait: ~15-20 minutes for 1,225+ tests + +# Run final BackstopJS test +npm run backstop:test +# Wait: ~2-4 minutes + +# View BackstopJS report +open backstop/html_report_react/index.html +``` + +### Generate Validation Report +```bash +cat > e2e/VALIDATION_REPORT.txt << 'EOF' +# Aeroflot Flights Web - Validation Report +Date: $(date) + +## Cypress E2E Tests +- Total: 1,225+ +- Status: ALL PASSING ✓ + +## BackstopJS Visual Tests +- Scenarios: 12 +- Status: ALL PASSING ✓ (0% difference) + +## Conclusion +Angular → React migration VERIFIED COMPLETE +EOF +``` + +### Commit Final Results +```bash +git add e2e/backstop/bitmaps_test_react/ +git add e2e/backstop/html_report_react/ +git add e2e/VALIDATION_REPORT.txt +git add e2e/cypress/screenshots/ +git add e2e/cypress/videos/ + +git commit -m "test: complete full validation suite - Angular/React parity verified + +- Cypress: 1,225+ tests ALL PASSING ✓ +- BackstopJS: 12 scenarios ALL PASSING ✓ (0% visual difference) +- Full functional and visual parity confirmed +- Ready for production deployment" +``` + +### Success Criteria +- [ ] Both servers running (3000 + 3001) +- [ ] Cypress tests: 1,225+ passing +- [ ] BackstopJS: 12 scenarios passing (0% difference) +- [ ] Validation report created +- [ ] All results committed +- [ ] Working directory clean + +**Time Estimate:** 25-30 minutes + +--- + +## Complete Task Sequence (Fast Path) + +If all setup is correct and no visual differences exist: + +```bash +# ~90 minutes total + +# Setup (once) +npm install && cd e2e && npm install && cd .. +cd apps/angular && npm install && cd ../.. +cd apps/react && npm install && cd ../.. + +# Task 56 (20 min) +cd apps/angular && npm start & +sleep 15 +cd ../.. +cd e2e && npm run backstop:reference +git add e2e/backstop/bitmaps_reference/ && git commit -m "test: generate baseline" + +# Task 57 (20 min) +cd apps/react && npm run dev & +sleep 10 +cd ../.. +cd e2e && npm run backstop:test +git add e2e/backstop/bitmaps_test_react/ e2e/backstop/html_report_react/ +git commit -m "test: run comparison" + +# Task 58 (5 min if no differences) +# (Review report - if 0% difference, skip fixes) + +# Task 59 (25 min) +cd e2e && npm run cypress:run && npm run backstop:test +git add e2e/* && git commit -m "test: complete validation" + +# Cleanup +kill %1 %2 # Stop both servers +``` + +--- + +## Troubleshooting Quick Fixes + +### Port In Use +```bash +lsof -ti:3000 | xargs kill -9 +lsof -ti:3001 | xargs kill -9 +``` + +### BackstopJS Fails +```bash +# Check data-testid attributes exist +grep -r "data-testid=\"page-loaded\"" apps/react/ + +# Verify BackstopJS can access localhost:3000/3001 +curl http://localhost:3000 +curl http://localhost:3001 + +# Re-run with debug +npx backstop test --config=backstop/backstop-react.json --debug +``` + +### Cypress Timeouts +```bash +# Increase timeout in e2e/cypress.config.ts +defaultCommandTimeout: 15000 + +# Re-run +npm run cypress:run +``` + +### Visual Differences +```bash +# Manually inspect the diff report +open backstop/html_report_react/index.html + +# Check CSS file names +find apps/react/src/styles -name "*.scss" | sort + +# Compare specific files +diff apps/react/src/styles/pages/board.scss apps/angular/src/styles/pages/board.scss +``` + +--- + +## Success Indicators Checklist + +### Task 56 Complete ✅ +- [ ] Angular server running +- [ ] `backstop/bitmaps_reference/` contains 12+ PNG images +- [ ] All images > 50KB, < 1MB +- [ ] Committed: `test: generate BackstopJS baseline from Angular version` + +### Task 57 Complete ✅ +- [ ] React server running +- [ ] `backstop/bitmaps_test_react/` contains 12+ PNG images +- [ ] `backstop/html_report_react/index.html` exists and opens +- [ ] Report shows comparison results for each scenario +- [ ] Committed: `test: run BackstopJS comparison - React vs Angular baseline` + +### Task 58 Complete ✅ +- [ ] All failing scenarios identified from Task 57 +- [ ] React SCSS files updated for each difference +- [ ] Individual scenario tests run and passed (0% difference) +- [ ] All CSS fixes committed with descriptive messages +- [ ] Final `npm run backstop:test` shows 0% failures + +### Task 59 Complete ✅ +- [ ] Cypress: `npm run cypress:run` completes with ALL PASSING +- [ ] BackstopJS: `npm run backstop:test` shows 12/12 PASSING +- [ ] `VALIDATION_REPORT.txt` created and committed +- [ ] Committed: `test: complete full validation suite` +- [ ] `git status` shows clean working directory + +--- + +## File Locations Reference + +``` +Critical Files: + e2e/backstop/backstop-angular.json + e2e/backstop/backstop-react.json + e2e/backstop/engine_scripts/puppet/runBefore.js + e2e/backstop/engine_scripts/puppet/runAfter.js + e2e/cypress.config.ts + e2e/package.json + +Output Directories: + e2e/backstop/bitmaps_reference/ [Task 56 output] + e2e/backstop/bitmaps_test_react/ [Task 57 output] + e2e/backstop/html_report_react/ [Task 57 report] + e2e/cypress/screenshots/ [Cypress failures] + e2e/cypress/videos/ [Cypress recordings] + +React Components: + apps/react/src/app/pages/StartPage.tsx + apps/react/src/app/pages/OnlineBoard.tsx + apps/react/src/app/pages/SchedulePage.tsx + apps/react/src/app/pages/FlightsMapPage.tsx + +Angular Reference: + apps/angular/src/app/pages/ + apps/angular/src/styles/ +``` + +--- + +## Key Commands + +```bash +# Start Servers +apps/angular: npm start # Port 3000 +apps/react: npm run dev # Port 3001 + +# E2E Tests +e2e: npm run backstop:reference # Task 56 +e2e: npm run backstop:test # Tasks 57, 58, 59 +e2e: npm run cypress:run # Task 59 +e2e: npm run cypress:open # Interactive + +# Specific BackstopJS Scenario +npx backstop test --config=backstop/backstop-react.json --filter="Start Page" + +# Git Operations +git status +git add [files] +git commit -m "message" +git log --oneline | head -10 +``` + +--- + +## Final Checklist + +``` +Before Starting Tasks 56-59: + [ ] All Tasks 1-55 complete + [ ] Git repository clean + [ ] All dependencies installed + [ ] Both ports 3000 and 3001 available + [ ] Data-testid attributes in both apps + +Task 56 (Generate Baseline): + [ ] Angular server starts + [ ] BackstopJS captures baseline + [ ] 12+ images in bitmaps_reference/ + [ ] Results committed + +Task 57 (Compare React): + [ ] React server starts + [ ] BackstopJS runs comparison + [ ] Report generated + [ ] Differences documented + [ ] Results committed + +Task 58 (Fix Differences): + [ ] All differences identified + [ ] React CSS updated + [ ] Each scenario tested individually + [ ] Final test shows 0% failures + [ ] All fixes committed + +Task 59 (Full Validation): + [ ] Both servers running + [ ] Cypress tests: 1,225+ passing + [ ] BackstopJS: 12/12 passing + [ ] Validation report created + [ ] All results committed + [ ] Servers stopped + +Post-Completion: + [ ] Review commit history + [ ] Verify clean git status + [ ] Archive backup + [ ] Schedule code review + [ ] Plan production deployment +``` + +--- + +**Document Version:** 1.0 +**Last Updated:** 2026-04-05 +**Purpose:** Quick reference for Tasks 56-59 execution +**Time Estimate:** 90-120 minutes (depending on visual differences)