VALIDATION_CHECKLIST.md

Stale-Write Conflict Handling - Validation Checklist

Code Quality Checks

TypeScript Type Checking

npm run typecheck

Expected Result: No errors What it validates:

• All TypeScript types are correct
• ApiConflictError properly extends Error
• WithRevision<T> generic type works correctly
• Hook return types match usage
• Component props align with implementations

Linting

npm run lint

Expected Result: No errors (may have warnings for unused variables) What it validates:

• Code follows ESLint rules
• No unused imports
• Proper formatting
• No console logs left behind (except intentional logging)

Build Compilation

npm run build

Expected Result: Build succeeds What it validates:

• All code compiles to JavaScript
• No runtime errors in type inference
• All imports resolve correctly
• CSS/styling loads properly

Test Validation

Run Conflict Handling Tests Only

npm run test -- \
  --testPathPattern="conflict|revision-tracking" \
  --run

Expected Result: All tests pass Tests included:

• ResolveConflictDialog component tests
• useConflictResolution hook tests
• Organization list conflict tests
• Issuer list conflict tests
• Revision tracking utility tests

Run All Tests for Modified Components

npm run test -- \
  components/forms \
  components/organizations \
  components/issuers \
  hooks \
  lib/api \
  --run

Expected Result: All tests pass, no regressions Coverage targets:

• Component rendering and UI interaction
• Hook state management
• API layer with revision tracking
• Error handling and edge cases

Test Coverage Report (optional)

npm run test -- \
  --testPathPattern="conflict|revision-tracking" \
  --coverage \
  --run

Expected Result: Coverage above 80% for new code Metrics:

• Statements: ≥80%
• Branches: ≥75%
• Functions: ≥80%
• Lines: ≥80%

Feature Validation (Manual)

Organization Form Conflict Flow

1. Navigate to /settings/organizations
2. Open browser DevTools Network tab
3. Modify organization status
4. Simulate server change (manually edit response in DevTools)
5. Verify: Conflict dialog appears with server vs. local values
6. Actions to test:
   • Click "Keep Editing" → dialog closes, form unchanged
   • Click "Reload from Server" → fresh data loads
   • Click "Retry with My Changes" → submission retries with local values

Issuer Form Conflict Flow

1. Navigate to /settings/issuers
2. Repeat organization flow steps with issuer
3. Verify: Dialog shows issuer-specific fields
4. Verify: Organization relationship is preserved

Authorization/Permission Checks

1. Test with different user roles (ADMIN, ISSUER, WORKER)
2. Verify: Only authorized users see management UI
3. Verify: Conflict dialog respects field visibility
4. Verify: Read-only users don't see edit affordances

Accessibility Testing

1. Navigate dialogs with keyboard only (Tab, Shift+Tab, Enter, Escape)
2. Verify: Focus management works correctly
3. Verify: Escape key closes conflict dialog
4. Verify: Screen reader announces conflict title and field changes
5. Verify: Color contrast is sufficient for conflicting field warnings

Browser Compatibility

Test in:

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Verify: Dialog renders and functions correctly on all browsers

API Integration Validation

Current State (before backend changes)

# Conflicts won't occur yet, but infrastructure is in place
npm run test -- --testPathPattern="conflict" --run

Expected: Tests pass, showing conflict detection works when backend is ready

After Backend Adds 409 Support

1. Update backend to send 409 on revision mismatch
2. Include currentEntity in response body
3. Verify: Frontend detects conflict correctly
4. Verify: Dialog displays correct server vs. local comparison
5. Verify: Retry submissions include new revision

API Response Format Validation

Verify the backend sends proper 409 responses:

{
  "statusCode": 409,
  "code": "CONFLICT",
  "message": "Resource was modified after you loaded this form",
  "currentEntity": {
    "id": "org-123",
    "name": "Updated Name",
    "status": "SUSPENDED"
  },
  "submittedData": {
    "status": "ACTIVE"
  }
}

Regression Testing

Existing Form Flows (Non-Conflict)

1. Create new organization → Verify: Works as before
2. Update organization details → Verify: Submission succeeds without conflict
3. Update organization status → Verify: Status changes, no dialog appears
4. Create and manage issuers → Verify: No regressions
5. Navigation and routing → Verify: Settings pages load correctly

Error Handling (Non-Conflict Errors)

1. Simulate network error → Verify: Error toast shows (existing behavior)
2. Simulate 401 Unauthorized → Verify: Auth error handling works
3. Simulate 403 Forbidden → Verify: Permission error shows correctly
4. Simulate 500 Server Error → Verify: Generic error message shown

Performance Validation

Load Time Impact

1. Navigate to organization management page
2. Open DevTools Performance tab
3. Check time to interactive
4. Verify: No noticeable slowdown from revision tracking

Memory Usage

1. Open organization management page
2. Perform multiple updates
3. Open DevTools Memory profiler
4. Verify: No memory leaks from dialog/hook lifecycle

Bundle Size Impact

npm run build
# Check dist/static/js/ folder size

Expected: Minimal increase (new components/hook should add <20KB gzipped)

Documentation Validation

• STALE_WRITE_CONFLICT_PR_SUMMARY.md accurately describes implementation
• CONFLICT_HANDLING_GUIDE.md provides clear integration template
• Code comments explain complex logic (hash creation, conflict comparison)
• TypeScript JSDoc comments on public APIs

Pre-Merge Checklist

• All TypeScript checks pass (npm run typecheck)
• All linting passes (npm run lint)
• Build succeeds (npm run build)
• All unit tests pass (npm run test -- --run)
• Conflict handling tests specifically validated
• Manual feature testing completed
• No console errors or warnings
• Accessibility testing passed
• Browser compatibility verified
• Regression tests confirm no breakage
• Performance acceptable
• Documentation complete and accurate
• PR description includes validation output

Post-Merge Validation

• Deploy to staging environment
• Run end-to-end tests
• Monitor error logs for unexpected issues
• Check performance metrics (page load, interaction times)
• Verify in production-like environment

Known Limitations & Future Work

• Revision tracking uses JSON hash (will upgrade to ETags when backend ready)
• TrustedSource forms not yet implemented (template provided in guide)
• Merge strategies not yet supported (only overwrite or reload options)
• No conflict analytics (can be added later)

Sign-Off

• Reviewed by: [Code Reviewer]
• Date: [Date]
• Build Status: ✓ Passing
• Test Status: ✓ All tests passing
• Ready for merge: ✓ Yes