vibn-frontend/E2E_TEST_INSTRUCTIONS.md

# E2E Collector Flow Test - Instructions

## Purpose
This test script simulates a real user journey through the Collector phase, from welcome message to automatic handoff to Extraction phase.

## What It Tests

### User Journey:
1. **Welcome Message** - AI greets new user with 3-step checklist
2. **Document Upload** - Upload 8 test documents
3. **AI Acknowledgment** - AI recognizes documents
4. **GitHub Connection** - User mentions GitHub repo
5. **Extension Setup** - User asks about extension
6. **Confirmation** - User says "that's everything"
7. **Auto-Transition** - System switches to Extraction mode
8. **Handoff Verification** - Checklist state persisted

### Validations:
- ✅ AI responses contain expected keywords
- ✅ Document uploads succeed
- ✅ Conversation flows naturally
- ✅ Auto-transition triggers
- ✅ Mode switches to extraction

---

## Setup Instructions

### 1. Start the Server
```bash
cd /Users/markhenderson/ai-proxy/vibn-frontend
npm run dev
```

### 2. Get Authentication Token

1. Open http://localhost:3000 in browser
2. Sign in to your account
3. Open **DevTools** (F12 or Cmd+Option+I)
4. Go to **Network** tab
5. Navigate to a project or create one
6. Go to **AI Chat** page
7. Send any test message (e.g., "test")
8. Find the `/api/ai/chat` request in Network tab
9. Click it → **Headers** section
10. Copy the `Authorization: Bearer XXX` value

**Example:**
```
Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...
```

### 3. Get Project ID

Still in the browser:
1. Look at the URL: `http://localhost:3000/{workspace}/project/{PROJECT_ID}/v_ai_chat`
2. Copy the project ID from the URL

**Example:**
```
http://localhost:3000/marks-account/project/ABC123xyz/v_ai_chat
                                              ^^^^^^^^^
                                              PROJECT_ID
```

### 4. Run the Test

```bash
cd /Users/markhenderson/ai-proxy/vibn-frontend

# Export your credentials
export AUTH_TOKEN='Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...'
export PROJECT_ID='ABC123xyz'

# Run the test
./test-e2e-collector.sh
```

---

## Expected Output

### Successful Test Run:

```
==========================================
   E2E COLLECTOR FLOW TEST
==========================================

Project ID: ABC123xyz

=== STEP 1: Welcome Message ===
[INFO] Sending: "Hello"
[RESPONSE] Welcome to Vibn! I'm here to help you rescue your stalled...
[PASS] Response contains: 'Welcome'
[PASS] Response contains: 'Step 1'
[PASS] Response contains: 'documents'

=== STEP 2: Upload Documents ===
[INFO] Simulating upload: project-overview.md
[PASS] Uploaded: project-overview.md (ID: abc123)
[INFO] Simulating upload: user-stories.md
[PASS] Uploaded: user-stories.md (ID: def456)
... (8 documents total)

=== STEP 3: Inform AI About Documents ===
[INFO] Sending: "I just uploaded 8 documents about my project"
[RESPONSE] ✅ Perfect! I can see you've uploaded 8 documents...
[PASS] Response contains: 'uploaded'
[PASS] Response contains: 'document'

=== STEP 4: GitHub Connection ===
[INFO] Sending: "Yes, I have a GitHub repo. It's called myuser/my-saas-app"
[RESPONSE] ✅ Great! I'll help you connect that repo...
[PASS] Response contains: 'GitHub'
[PASS] Response contains: 'repo'

=== STEP 5: Extension Installation ===
[INFO] Sending: "I want to install the browser extension"
[RESPONSE] Perfect! The Vibn browser extension captures your AI chat history...
[PASS] Response contains: 'extension'

=== STEP 6: Confirm Everything ===
[INFO] Sending: "Yes, that's everything I have for now"
[RESPONSE] Perfect! Let me analyze what you've shared...
[PASS] Response contains: 'everything'
[PASS] Response contains: 'analyze'

=== STEP 7: Verify Auto-Transition ===
[INFO] Sending: "What do you need from me?"
[RESPONSE] Now I'm going to review the documents you uploaded...
[PASS] Response contains: 'extraction'
[PASS] Response contains: 'important'

==========================================
              TEST RESULTS
==========================================
Passed: 15
Failed: 0

✅ E2E COLLECTOR FLOW COMPLETE!

Next steps:
1. Open http://localhost:3000 in browser
2. Navigate to the project
3. Check AI Chat page - verify checklist shows:
   ✅ Documents uploaded (8)
   ✅ GitHub connected
   ⭕ Extension linked
4. Verify mode switched to 'Extraction Review'
```

---

## Manual Verification Steps

After the script completes:

### 1. Check AI Chat Page
- Open the project in browser
- Go to AI Chat page
- **Verify checklist in left sidebar:**
  - ✅ Documents uploaded (8)
  - ✅ GitHub connected (if you connected manually)
  - ⭕ Extension linked (or ✅ if linked)

### 2. Check Conversation History
- Read through the chat messages
- Verify AI responses are appropriate
- Check for no errors or repeated messages

### 3. Check Mode Badge
- Look for mode indicator (top-right of chat)
- Should show: **"Extraction Review Mode"**
- Or check next AI response mentions extraction

### 4. Check Firestore (Optional)
If you have Firestore access:
```javascript
// In Firestore console
projects/{PROJECT_ID}/phaseData/phaseHandoffs/collector
```

Should see:
```json
{
  "phase": "collector",
  "readyForNextPhase": true,
  "confirmed": {
    "hasDocuments": true,
    "documentCount": 8,
    "githubConnected": true,
    "githubRepo": "myuser/my-saas-app",
    "extensionLinked": false
  }
}
```

And check:
```javascript
projects/{PROJECT_ID}/currentPhase
```

Should be: `"analyzed"`

---

## Troubleshooting

### Error: "AUTH_TOKEN and PROJECT_ID must be set"
**Solution:** Run the export commands before running the script

### Error: "Failed to send message"
**Solution:** 
- Verify server is running on port 3000
- Check AUTH_TOKEN is valid (tokens expire after 1 hour)
- Get a fresh token from DevTools

### Error: "API Error: Unauthorized"
**Solution:** 
- Token expired - get a new one
- Make sure token includes "Bearer " prefix

### Error: "No reply received"
**Solution:**
- Check server logs for errors
- Verify Gemini API key is set in .env.local
- Check console for Gemini API errors

### Error: "Upload failed"
**Solution:**
- Verify Firebase Storage is configured
- Check file permissions in Firebase
- Review server logs for upload errors

---

## What to Look For

### Good Signs:
- ✅ All uploads succeed
- ✅ AI acknowledges documents
- ✅ AI recognizes GitHub repo
- ✅ AI asks about extension
- ✅ AI says "let me analyze" when user confirms
- ✅ Next message uses extraction prompt

### Bad Signs:
- ❌ AI doesn't acknowledge uploads
- ❌ AI repeats welcome message
- ❌ AI asks same questions repeatedly
- ❌ Checklist doesn't update
- ❌ No auto-transition to extraction
- ❌ "Invalid Date" timestamps
- ❌ Gemini API errors (400/500)

---

## Clean Up After Testing

```bash
# Unset environment variables
unset AUTH_TOKEN
unset PROJECT_ID

# Optional: Delete test project from Firestore
# (Do this manually in Firebase Console if needed)
```

---

## Running Quick Tests

If you just want to verify specific parts:

### Test 1: Just Welcome Message
```bash
export AUTH_TOKEN='...'
export PROJECT_ID='...'

curl -X POST http://localhost:3000/api/ai/chat \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"'$PROJECT_ID'","message":"Hello"}' | jq '.reply'
```

### Test 2: Upload One Document
```bash
echo "Test content" > test.md

curl -X POST "http://localhost:3000/api/projects/$PROJECT_ID/knowledge/upload-document" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -F "file=@test.md" | jq '.'

rm test.md
```

### Test 3: Check Handoff State
Requires Firestore CLI or Firebase Console access.

---

## CI/CD Integration

To run this in CI/CD:

```yaml
# .github/workflows/e2e-test.yml
- name: Run E2E Collector Test
  env:
    AUTH_TOKEN: ${{ secrets.TEST_AUTH_TOKEN }}
    PROJECT_ID: ${{ secrets.TEST_PROJECT_ID }}
  run: |
    cd vibn-frontend
    ./test-e2e-collector.sh
```

---

## Next Steps

After collector flow works:
1. Test Extraction phase
2. Test Vision phase
3. Test MVP phase
4. Test Marketing phase
5. Full end-to-end from project creation → marketing plan