[P1] Checkpoint UI fails to display seeded checkpoints - 4 E2E tests failing

[frankbria]

Problem

The Checkpoint UI is not displaying seeded checkpoint data. Tests expecting checkpoint items find neither the checkpoint items nor the empty state element.

Failing Tests (4)

1. test_checkpoint_ui.spec.ts:64 - should list existing checkpoints
2. test_checkpoint_ui.spec.ts:147 - should show restore confirmation dialog
3. test_checkpoint_ui.spec.ts:220 - should display checkpoint metadata
4. test_checkpoint_ui.spec.ts:247 - should allow deleting checkpoint

Error Messages

TimeoutError: page.waitForResponse: Timeout 10000ms exceeded while waiting for event "response"
- response.url().includes('/checkpoints') && response.status() === 200

Error: expect(locator).toBeVisible() failed
Locator: locator('[data-testid="checkpoint-empty-state"]')
Expected: visible
Error: element(s) not found

Symptoms

1. /checkpoints API call times out (test 1)
2. Neither [data-testid^="checkpoint-item-"] nor [data-testid="checkpoint-empty-state"] elements are visible (tests 2-4)
3. Seeded checkpoints (3 per project) are not being loaded/displayed

Seeding Verification

The seed script confirms checkpoints were created:

💾 Seeding checkpoints...
   ✅ Created checkpoint DB: checkpoint-001-db.sqlite
   ✅ Created context snapshot: checkpoint-001-context.json
   ✅ Created checkpoint DB: checkpoint-002-db.sqlite
   ...
✅ Seeded 3/3 checkpoints with files

Possible Root Causes

1. Checkpoint API endpoint not responding or returning wrong format
2. Frontend CheckpointPanel not rendering checkpoint items correctly
3. Test project (ID: 1) may be in wrong phase for checkpoint display
4. Missing data-testid attributes on checkpoint UI elements

Affected Files

• web-ui/src/components/CheckpointPanel.tsx
• codeframe/ui/routers/checkpoints.py
• tests/e2e/seed-test-data.py

[traycerai]

Plan

Observations

The checkpoint UI tests are failing because the /checkpoints API endpoint times out and neither checkpoint items nor empty state elements are rendered. The seed script successfully creates 3 checkpoints for the test project in the database with associated SQLite backup and JSON context files. The backend API endpoint is properly registered and requires authentication + project access authorization. The frontend CheckpointList component correctly implements data fetching, loading states, and conditional rendering for both populated and empty states.

Approach

The root cause is likely a mismatch between the test project setup flow and the checkpoint seeding. The global-setup creates a project via API (which sets user_id correctly), but the seed script only updates the project phase without ensuring the project record exists with proper ownership. Additionally, there may be timing issues where the checkpoint tab is accessed before the API is ready, or the authentication token isn't being properly passed in the E2E test context. The fix involves ensuring proper project ownership in the seed script, verifying API authentication in tests, and adding defensive error handling in the frontend component.

Implementation Steps

1. Verify and Fix Project Ownership in Seed Script

File: file:tests/e2e/seed-test-data.py

Update the seed_test_data function to ensure the project exists with correct user_id before seeding checkpoints:

• After the test user creation section (around line 120), add a project verification/creation step
• Use INSERT OR REPLACE INTO projects to ensure project exists with user_id=1 (the test user)
• Include all required fields: id, name, description, user_id, workspace_path, status, phase, created_at
• Set the workspace_path to match the E2E test structure: os.path.join(E2E_TEST_ROOT, ".codeframe", "workspaces", str(project_id))
• Create the workspace directory if it doesn't exist using os.makedirs(workspace_path, exist_ok=True)
• This ensures the project record is properly owned by user_id=1 regardless of how global-setup creates it

2. Add Checkpoint API Response Logging in Tests

File: file:tests/e2e/test_checkpoint_ui.spec.ts

Enhance error diagnostics in the failing tests (lines 64, 147, 220, 247):

• Before page.waitForResponse calls, add a response listener to capture all /checkpoints responses regardless of status
• Log the response status, headers, and body for debugging
• Use page.on('response', ...) to capture failed responses (401, 403, 404, 500)
• Add a try-catch around the waitForResponse with detailed error message including the captured response data
• This will help identify if the issue is authentication (401/403), not found (404), or server error (500)

3. Verify Authentication Token in Checkpoint Requests

File: file:web-ui/src/api/checkpoints.ts

Add defensive logging and error handling to the listCheckpoints function:

• The function already uses authFetch which should handle authentication
• Verify that authFetch is properly reading the token from localStorage
• Add error handling to catch and log specific HTTP status codes (401, 403, 404, 500)
• Return an empty array with a console warning if the request fails, rather than throwing
• This prevents the UI from breaking completely if the API is temporarily unavailable

File: file:web-ui/src/lib/api-client.ts (if it exists)

• Verify the authFetch implementation includes the Authorization header
• Ensure it reads from localStorage.getItem('auth_token')
• Add retry logic for transient failures (network errors, 5xx responses)
• Log authentication failures clearly for debugging

4. Add Loading and Error States to CheckpointList

File: file:web-ui/src/components/checkpoints/CheckpointList.tsx

The component already has loading and error states, but enhance them:

• Add a timeout mechanism (15-20 seconds) for the initial load
• If loading exceeds timeout, show an error message with retry button
• Add data-testid="checkpoint-loading" to the loading spinner (line 277-283)
• Add data-testid="checkpoint-error" to the error message (line 300-304)
• This allows tests to detect and diagnose loading vs error states

5. Add Checkpoint Tab Visibility Check

File: file:tests/e2e/test_checkpoint_ui.spec.ts

In the beforeEach hook (lines 18-43), add verification that the checkpoint tab is actually clickable:

• After waiting for checkpoint-tab to be visible, verify it's not disabled
• Add a small delay (500ms) after clicking the tab before waiting for the panel
• Wait for the /checkpoints API call to complete before proceeding with test assertions
• Add a fallback: if the API call times out, check if there's an error message in the UI
• This ensures the test doesn't proceed until the checkpoint data is loaded or an error is shown

6. Verify Database Checkpoint Records

File: file:tests/e2e/seed-test-data.py

Add verification after checkpoint seeding (around line 1128):

• After seeding checkpoints, query the database to verify records were inserted
• Check that project_id matches the expected value
• Verify the checkpoint files exist at the specified paths
• Log the checkpoint IDs, names, and file paths for debugging
• If verification fails, print detailed error message and exit with non-zero status
• This ensures the seed script fails fast if checkpoints aren't created properly

7. Add API Endpoint Health Check

File: file:tests/e2e/test_checkpoint_ui.spec.ts

Before the main test suite, add a health check test:

• Create a new test: test('checkpoint API endpoint is accessible', ...)
• Make a direct API call to /api/projects/${PROJECT_ID}/checkpoints using page.request.get()
• Include the Authorization header with the token from localStorage
• Verify the response status is 200 and the response body has a checkpoints array
• Log the response for debugging
• This test will fail fast if the API endpoint is not working, making it easier to diagnose

8. Check for CORS or Network Issues

File: file:tests/e2e/test_checkpoint_ui.spec.ts

Add network monitoring to the beforeEach hook:

• Use page.on('requestfailed', ...) to capture failed requests
• Log any failed requests to /checkpoints with the failure reason
• Check for CORS errors, connection refused, or timeout errors
• This helps identify if the issue is network-related rather than application logic

Verification Steps

After implementing the fixes:

1. Run the seed script manually: uv run python tests/e2e/seed-test-data.py <db_path> 1
2. Verify checkpoint records in database: sqlite3 <db_path> "SELECT * FROM checkpoints WHERE project_id=1"
3. Verify checkpoint files exist: ls -la tests/e2e/.codeframe/checkpoints/
4. Start the backend server and verify the endpoint: curl -H "Authorization: Bearer <token>" http://localhost:8080/api/projects/1/checkpoints
5. Run the E2E tests: npm run test:e2e -- test_checkpoint_ui.spec.ts
6. Check test output for detailed error messages and API response logs

Expected Outcome

After these changes:

• The seed script will ensure project ownership is correct
• Tests will have better error diagnostics showing exactly why the API call fails
• The frontend will handle API failures gracefully with clear error messages
• The checkpoint UI will display either the seeded checkpoints or a clear error state
• All 4 failing tests should pass, showing the 3 seeded checkpoints with proper metadata

Import In IDE

🤖 Prompt for AI Agents

## Observations

The checkpoint UI tests are failing because the `/checkpoints` API endpoint times out and neither checkpoint items nor empty state elements are rendered. The seed script successfully creates 3 checkpoints for the test project in the database with associated SQLite backup and JSON context files. The backend API endpoint is properly registered and requires authentication + project access authorization. The frontend `CheckpointList` component correctly implements data fetching, loading states, and conditional rendering for both populated and empty states.

## Approach

The root cause is likely a mismatch between the test project setup flow and the checkpoint seeding. The global-setup creates a project via API (which sets `user_id` correctly), but the seed script only updates the project phase without ensuring the project record exists with proper ownership. Additionally, there may be timing issues where the checkpoint tab is accessed before the API is ready, or the authentication token isn't being properly passed in the E2E test context. The fix involves ensuring proper project ownership in the seed script, verifying API authentication in tests, and adding defensive error handling in the frontend component.

## Implementation Steps

### 1. Verify and Fix Project Ownership in Seed Script

**File**: `file:tests/e2e/seed-test-data.py`

Update the `seed_test_data` function to ensure the project exists with correct `user_id` before seeding checkpoints:

- After the test user creation section (around line 120), add a project verification/creation step
- Use `INSERT OR REPLACE INTO projects` to ensure project exists with `user_id=1` (the test user)
- Include all required fields: `id`, `name`, `description`, `user_id`, `workspace_path`, `status`, `phase`, `created_at`
- Set the workspace_path to match the E2E test structure: `os.path.join(E2E_TEST_ROOT, ".codeframe", "workspaces", str(project_id))`
- Create the workspace directory if it doesn't exist using `os.makedirs(workspace_path, exist_ok=True)`
- This ensures the project record is properly owned by user_id=1 regardless of how global-setup creates it

### 2. Add Checkpoint API Response Logging in Tests

**File**: `file:tests/e2e/test_checkpoint_ui.spec.ts`

Enhance error diagnostics in the failing tests (lines 64, 147, 220, 247):

- Before `page.waitForResponse` calls, add a response listener to capture all `/checkpoints` responses regardless of status
- Log the response status, headers, and body for debugging
- Use `page.on('response', ...)` to capture failed responses (401, 403, 404, 500)
- Add a try-catch around the waitForResponse with detailed error message including the captured response data
- This will help identify if the issue is authentication (401/403), not found (404), or server error (500)

### 3. Verify Authentication Token in Checkpoint Requests

**File**: `file:web-ui/src/api/checkpoints.ts`

Add defensive logging and error handling to the `listCheckpoints` function:

- The function already uses `authFetch` which should handle authentication
- Verify that `authFetch` is properly reading the token from localStorage
- Add error handling to catch and log specific HTTP status codes (401, 403, 404, 500)
- Return an empty array with a console warning if the request fails, rather than throwing
- This prevents the UI from breaking completely if the API is temporarily unavailable

**File**: `file:web-ui/src/lib/api-client.ts` (if it exists)

- Verify the `authFetch` implementation includes the Authorization header
- Ensure it reads from `localStorage.getItem('auth_token')`
- Add retry logic for transient failures (network errors, 5xx responses)
- Log authentication failures clearly for debugging

### 4. Add Loading and Error States to CheckpointList

**File**: `file:web-ui/src/components/checkpoints/CheckpointList.tsx`

The component already has loading and error states, but enhance them:

- Add a timeout mechanism (15-20 seconds) for the initial load
- If loading exceeds timeout, show an error message with retry button
- Add `data-testid="checkpoint-loading"` to the loading spinner (line 277-283)
- Add `data-testid="checkpoint-error"` to the error message (line 300-304)
- This allows tests to detect and diagnose loading vs error states

### 5. Add Checkpoint Tab Visibility Check

**File**: `file:tests/e2e/test_checkpoint_ui.spec.ts`

In the `beforeEach` hook (lines 18-43), add verification that the checkpoint tab is actually clickable:

- After waiting for `checkpoint-tab` to be visible, verify it's not disabled
- Add a small delay (500ms) after clicking the tab before waiting for the panel
- Wait for the `/checkpoints` API call to complete before proceeding with test assertions
- Add a fallback: if the API call times out, check if there's an error message in the UI
- This ensures the test doesn't proceed until the checkpoint data is loaded or an error is shown

### 6. Verify Database Checkpoint Records

**File**: `file:tests/e2e/seed-test-data.py`

Add verification after checkpoint seeding (around line 1128):

- After seeding checkpoints, query the database to verify records were inserted
- Check that `project_id` matches the expected value
- Verify the checkpoint files exist at the specified paths
- Log the checkpoint IDs, names, and file paths for debugging
- If verification fails, print detailed error message and exit with non-zero status
- This ensures the seed script fails fast if checkpoints aren't created properly

### 7. Add API Endpoint Health Check

**File**: `file:tests/e2e/test_checkpoint_ui.spec.ts`

Before the main test suite, add a health check test:

- Create a new test: `test('checkpoint API endpoint is accessible', ...)`
- Make a direct API call to `/api/projects/${PROJECT_ID}/checkpoints` using `page.request.get()`
- Include the Authorization header with the token from localStorage
- Verify the response status is 200 and the response body has a `checkpoints` array
- Log the response for debugging
- This test will fail fast if the API endpoint is not working, making it easier to diagnose

### 8. Check for CORS or Network Issues

**File**: `file:tests/e2e/test_checkpoint_ui.spec.ts`

Add network monitoring to the `beforeEach` hook:

- Use `page.on('requestfailed', ...)` to capture failed requests
- Log any failed requests to `/checkpoints` with the failure reason
- Check for CORS errors, connection refused, or timeout errors
- This helps identify if the issue is network-related rather than application logic

## Verification Steps

After implementing the fixes:

1. Run the seed script manually: `uv run python tests/e2e/seed-test-data.py <db_path> 1`
2. Verify checkpoint records in database: `sqlite3 <db_path> "SELECT * FROM checkpoints WHERE project_id=1"`
3. Verify checkpoint files exist: `ls -la tests/e2e/.codeframe/checkpoints/`
4. Start the backend server and verify the endpoint: `curl -H "Authorization: Bearer <token>" http://localhost:8080/api/projects/1/checkpoints`
5. Run the E2E tests: `npm run test:e2e -- test_checkpoint_ui.spec.ts`
6. Check test output for detailed error messages and API response logs

## Expected Outcome

After these changes:
- The seed script will ensure project ownership is correct
- Tests will have better error diagnostics showing exactly why the API call fails
- The frontend will handle API failures gracefully with clear error messages
- The checkpoint UI will display either the seeded checkpoints or a clear error state
- All 4 failing tests should pass, showing the 3 seeded checkpoints with proper metadata

---

Execution Information

Branch: main
Commit: ff1c08b

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

⚠️ Possible Duplicate Issue

• Fix checkpoint panel visibility - CheckpointList not rendering items #85

🔗 Related PRs

#93 - fix(e2e): Fix dashboard and metrics tests for tab-based UI rendering [merged]
#182 - fix(checkpoints): Unwrap API response to prevent sort error on empty projects [merged]
#191 - feat(e2e): Enable conditional tests and fix discovery startup [merged]
#221 - feat(api): add manual task generation endpoint [merged]
#229 - feat(e2e): add state reconciliation tests for late-joining users [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!