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
2026-04-05 19:26:06 +03:00
parent 358c31eafe
commit 9174cae406
1 changed files with 541 additions and 0 deletions
@@ -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)