​

🔍 Wizard Retry Fix - Manual Validation Guide

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

---

​

🎯 What We’re Testing

Fix: Retry logic for readiness check after save to handle BigQuery eventual consistency Expected Behavior:

• Save succeeds → Readiness check retries if config not immediately queryable
• Wizard unblocks when businesses become ready
• Persisted config visible after page refresh

---

​

📋 Pre-Test Setup

1. Open Browser DevTools:
   • Press F12 or Right-click → Inspect
   • Go to Network tab
   • Go to Console tab
   • Clear console logs
2. Navigate to Wizard:
   • URL: https://payroll-pipeline-cbs.vercel.app/ingestion
   • Log in if needed
   • Complete Map Columns step if not already done

---

​

✅ Test 1: Save Business Configuration

​

Steps:

1. Navigate to Preflight step
2. Find a business showing “not ready” status
3. Click “Configure” button
4. In the drawer:
   • Set PEPM rate to 12.00
   • Click “Save”
5. Observe:
   • Drawer behavior (should stay open during refresh)
   • Network requests
   • Console logs

​

Expected Results:

Network Tab:

• ✅ PUT /api/v1/admin/onboarding/businesses/{id}/save → 200 OK
  • Headers include: x-org-id: cbs-main
  • Body includes: period_label: 2025-12-01
• ✅ GET /api/v1/intake/ingestion-wizard/readiness?... → 200 OK
  • Query params include: period_label=2025-12-01
  • May see multiple GET requests if retry logic triggers (up to 3)

Console Tab (Dev Mode):

• ✅ [handleDrawerSuccess] Readiness check succeeded after X retries (if retries needed)
• ✅ OR: No retry logs if config immediately queryable
• ✅ No errors

UI Behavior:

• ✅ Drawer stays open during preflight refresh
• ✅ Drawer closes after preflight refresh completes
• ✅ Success toast: “Business configured successfully”

Screenshot Locations:

• Network tab showing PUT + GET requests
• Console showing retry logs (if any)

---

​

✅ Test 2: Wizard Unblocks After Save

​

Steps:

1. After Test 1 completes (drawer closed)
2. Observe Preflight UI
3. Check business status
4. Check Processing button state

​

Expected Results:

UI Updates:

• ✅ Business that was saved now shows “ready” status
• ✅ Readiness summary updates (e.g., “5 businesses ready”)
• ✅ Processing button becomes enabled (if all businesses ready)
• ✅ No blocking message: “X businesses not ready”

Network Tab:

• ✅ GET /api/v1/intake/ingestion-wizard/preflight → 200 OK
  • Response includes updated classification arrays

Screenshot Locations:

• Preflight UI showing business as “ready”
• Processing button enabled (if applicable)

---

​

✅ Test 3: Persistence After Page Refresh

​

Steps:

1. After Test 1 completes
2. Hard refresh page: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
3. Navigate back to Preflight step
4. Click “Configure” on the same business that was saved

​

Expected Results:

UI Behavior:

• ✅ Business still shows as “ready” after refresh
• ✅ Opening drawer shows persisted PEPM configuration
• ✅ PEPM rate matches saved value (12.00)
• ✅ No need to reconfigure

Network Tab:

• ✅ GET /api/v1/admin/onboarding/businesses?... when opening drawer
  • Query params include: period_label=2025-12-01&search={business_id}
  • Response includes saved PEPM configuration

Screenshot Locations:

• Drawer showing persisted PEPM rate
• Network request showing GET with period_label

---

​

✅ Test 4: Retry Logic Behavior (Detailed)

​

Steps:

1. Save a business configuration
2. Monitor Network tab for readiness requests
3. Check Console for retry logs

​

Expected Scenarios:

Scenario A: Config Immediately Queryable

• ✅ Single GET /readiness request
• ✅ No retry logs in console
• ✅ Business shows as ready immediately

Scenario B: Config Not Immediately Queryable (Retry Needed)

• ✅ Multiple GET /readiness requests (up to 3)
• ✅ Console shows: [handleDrawerSuccess] Readiness check retry 1/3
• ✅ Console shows: [handleDrawerSuccess] Readiness check succeeded after X retries
• ✅ Business shows as ready after retry succeeds

Scenario C: All Retries Fail (Graceful Fallback)

• ✅ 3 GET /readiness requests
• ✅ Console shows: [handleDrawerSuccess] Readiness check completed after 3 retries - proceeding
• ✅ Wizard proceeds anyway (save succeeded, backend will catch up)
• ✅ User sees success toast

Screenshot Locations:

• Network tab showing multiple GET requests (if retries occur)
• Console showing retry logs

---

​

✅ 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 Results:

UI Behavior:

• ✅ First save completes successfully
• ✅ Second save completes successfully
• ✅ Both businesses show as ready
• ✅ No race conditions or stale state

Network Tab:

• ✅ Two PUT requests (one per save)
• ✅ Multiple GET /readiness requests (one per save, with retries if needed)

---

​

🐛 Troubleshooting

​

Issue: Wizard Still Blocks After Save

Check:

1. Network tab: Does readiness GET return is_ready: true?
2. Console: Are there retry logs?
3. Console: Any errors?

Possible Causes:

• Backend readiness endpoint not seeing saved config
• period_label mismatch between save and readiness query
• Backend eventual consistency longer than 1.5 seconds (3 retries × 500ms)

Fix:

• Increase retry delay or max retries if needed
• Verify backend readiness endpoint uses correct period_label

​

Issue: Drawer Shows Stale Data

Check:

1. Network tab: Does GET /admin/onboarding/businesses return fresh data?
2. Console: Does handleConfigureBusiness fetch complete?

Possible Causes:

• loadPreflight() not completing before drawer closes
• Business config fetch failing silently

Fix:

• Verify loadPreflight() completes before drawer closes
• Check error handling in handleConfigureBusiness

​

Issue: Retry Logic Not Triggering

Check:

1. Console: Are retry logs present?
2. Network tab: Multiple GET requests?

Possible Causes:

• Config immediately queryable (good!)
• Retry logic not executing (check code)

Fix:

• Verify retry logic code is deployed
• Check if savedBusinessId is set correctly

---

​

📊 Validation Checklist

Test Date: _______________
Tester: _______________
Browser: _______________
Environment: Production Overall Status: ⏳ PENDING VALIDATION

---

​

✅ 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

---

​

📝 Notes

• Retry logic only logs in dev mode (NODE_ENV !== 'production')
• Production builds won’t show retry logs (but retries still happen)
• If all retries fail, wizard proceeds anyway (save succeeded)
• Backend eventual consistency typically resolves within 500ms-1s

---

Next Steps: Run manual validation and update this document with results and screenshots.