Skip to main content

​
Wizard Retry Fix - Validation Checklist

Deployment Date: 2026-02-06
Commit SHA: 7472c75
Frontend URL: https://payroll-pipeline-cbs.vercel.app/ingestion

​
✅ Manual Validation Steps

​
Prerequisites

  • Browser DevTools open (F12)
  • Network tab visible
  • Console tab visible
  • Logged in as admin user

​
Test 1: Save Business Configuration

Steps:
  1. Navigate to: https://payroll-pipeline-cbs.vercel.app/ingestion
  2. Complete Map Columns step
  3. Navigate to Preflight step
  4. Click “Configure” on a business that shows “not ready”
  5. Set PEPM rate (e.g., 12.00)
  6. Click “Save”
Expected Behavior:
  • ✅ PUT request to /api/v1/admin/onboarding/businesses/{id}/save returns 200
  • ✅ Drawer stays open during preflight refresh
  • ✅ Console shows retry attempts (if config not immediately queryable): 
    [handleDrawerSuccess] Readiness check retry 1/3 (config may not be queryable yet)
[handleDrawerSuccess] Readiness check succeeded after X retries
  • ✅ Drawer closes after preflight refresh completes
  • ✅ Success toast: “Business configured successfully”
Network Verification:
  • ✅ PUT request includes x-org-id header
  • ✅ PUT request includes period_label in body
  • ✅ GET request to /api/v1/intake/ingestion-wizard/readiness after save
  • ✅ GET request includes period_label query param
  • ✅ Multiple GET requests if retry logic triggers (up to 3 attempts)

​
Test 2: Wizard Unblocks After Save

Steps:
  1. After Test 1 completes
  2. Observe Preflight UI
  3. Check if businesses show as “ready”
  4. Verify Processing button becomes enabled
Expected Behavior:
  • ✅ Businesses that were saved now show as “ready”
  • ✅ Readiness summary updates (X businesses ready)
  • ✅ Processing step becomes available (if all businesses ready)
  • ✅ No “X businesses not ready” blocking message
UI Verification:
  • ✅ Business status changes from “not ready” to “ready”
  • ✅ Readiness map updates correctly
  • ✅ Auto-process gate passes (if all businesses ready)

​
Test 3: Persistence After Page Refresh

Steps:
  1. After Test 1 completes
  2. Hard refresh page (Ctrl+F5 / Cmd+Shift+R)
  3. Navigate back to Preflight step
  4. Click “Configure” on the same business that was saved
Expected Behavior:
  • ✅ Business still shows as “ready” after refresh
  • ✅ Opening drawer shows persisted PEPM configuration
  • ✅ PEPM rate matches what was saved (e.g., 12.00)
  • ✅ No need to reconfigure
Network Verification:
  • ✅ GET request to /api/v1/admin/onboarding/businesses when opening drawer
  • ✅ GET request includes period_label query param
  • ✅ Response includes saved PEPM configuration

​
Test 4: Retry Logic Behavior (If Needed)

Steps:
  1. Save a business configuration
  2. Monitor console logs
  3. Check Network tab for readiness requests
Expected Behavior:
  • ✅ If config is immediately queryable: No retries, single readiness check
  • ✅ If config not immediately queryable: Up to 3 retry attempts (500ms delay)
  • ✅ Console logs show retry attempts (dev mode only)
  • ✅ Wizard proceeds even if retries don’t succeed (save succeeded)
Console Verification:
  • ✅ [handleDrawerSuccess] Readiness check succeeded after X retries (when successful)
  • ✅ [handleDrawerSuccess] Readiness check retry X/3 (during retries)
  • ✅ [handleDrawerSuccess] Readiness check completed after 3 retries - proceeding (if all retries fail)

​
Test 5: Multiple Saves in Sequence

Steps:
  1. Save first business configuration
  2. Wait for drawer to close
  3. Save second business configuration
  4. Verify both show as ready
Expected Behavior:
  • ✅ First save completes successfully
  • ✅ Second save completes successfully
  • ✅ Both businesses show as ready
  • ✅ No race conditions or stale state

​
🐛 Known Issues / Edge Cases

​
If Retry Logic Doesn’t Work:

  • Check backend logs for readiness endpoint
  • Verify period_label matches between save and readiness query
  • Check BigQuery write → query lag (may need longer retry delay)

​
If Wizard Still Blocks:

  • Verify readiness endpoint returns correct is_ready status
  • Check if didLoadReadinessKeyRef is preventing re-fetch
  • Verify readinessMap state is updated correctly

​
If Drawer Shows Stale Data:

  • Verify handleConfigureBusiness fetches fresh config
  • Check if loadPreflight() completes before drawer closes
  • Verify preflightData arrays are updated

​
✅ Success Criteria

All tests pass when:
  • ✅ Save succeeds (PUT 200)
  • ✅ Readiness check retries if needed (up to 3 attempts)
  • ✅ Wizard unblocks after save (businesses show as ready)
  • ✅ Persistence works after page refresh
  • ✅ No console errors
  • ✅ No network errors

​
📝 Validation Results

Test Date: _______________
Tester: _______________
Environment: Production (https://payroll-pipeline-cbs.vercel.app)
TestStatusNotes
Test 1: Save Business Configuration⏳ Pending
Test 2: Wizard Unblocks After Save⏳ Pending
Test 3: Persistence After Page Refresh⏳ Pending
Test 4: Retry Logic Behavior⏳ Pending
Test 5: Multiple Saves in Sequence⏳ Pending
Overall Status: ⏳ PENDING VALIDATION
Next Steps: Run manual validation tests and update this document with results.