guideai-app 0.3.5 → 0.4.2

package/VISIT_COUNT_TESTING.md

@@ -0,0 +1,453 @@
+# Visit Count Testing - Manual Test Checklist
+
+This document contains manual testing procedures for scenarios that cannot be fully automated in unit/integration tests.
+
+## Prerequisites
+
+Before testing, ensure you have:
+- [ ] Built the GuideAI package (`npm run build`)
+- [ ] Access to the test site
+- [ ] Multiple browsers installed (Chrome, Firefox, Safari, Edge)
+- [ ] Mobile device or browser DevTools mobile emulation
+- [ ] Browser DevTools open to inspect localStorage
+
+## Understanding Visit Count Behavior
+
+**Expected Behavior:**
+- `visitCount` starts at `1` on first visit
+- `visitCount` increments when user returns after **30+ minutes**
+- `visitCount` persists in `localStorage` (survives browser close/reopen)
+- `sessionId` is stored in `sessionStorage` (cleared on browser/tab close)
+
+**When visitCount resets to 1 (treated as first-time user):**
+1. ✅ Switching browsers (Chrome → Firefox)
+2. ✅ Using incognito/private browsing mode
+3. ✅ Switching devices (Desktop → Mobile)
+4. ✅ Clearing browser data
+
+---
+
+## Test Suite 1: Cross-Browser Testing
+
+### Test 1.1: Chrome to Firefox Switch
+
+**Purpose:** Verify that switching browsers treats user as first-time user.
+
+**Steps:**
+1. Open Chrome browser
+2. Navigate to test site
+3. Open DevTools → Console
+4. Check visitCount: `localStorage.getItem('guideai_user_metadata')`
+   - **Expected:** `visitCount: 1`
+5. Note the sessionId
+6. Close Chrome
+7. Open Firefox browser
+8. Navigate to same test site
+9. Check visitCount in Firefox DevTools
+   - **Expected:** `visitCount: 1` (treated as new user)
+   - **Expected:** Different sessionId
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Notes:**
+```
+Chrome visitCount: ___
+Firefox visitCount: ___
+```
+
+---
+
+### Test 1.2: Chrome to Safari Switch
+
+**Purpose:** Verify cross-browser isolation.
+
+**Steps:**
+1. Open Chrome, visit test site
+2. Manually increment visitCount (login or wait 31+ min and reload)
+3. Verify visitCount is now `2` or higher in Chrome
+4. Open Safari, visit test site
+5. Check visitCount in Safari
+   - **Expected:** `visitCount: 1` (Safari has its own localStorage)
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Notes:**
+```
+Chrome visitCount: ___
+Safari visitCount: ___
+```
+
+---
+
+## Test Suite 2: Incognito/Private Mode
+
+### Test 2.1: Regular to Incognito Switch
+
+**Purpose:** Verify incognito mode always treats user as first-time user.
+
+**Steps:**
+1. Open Chrome in regular mode
+2. Visit test site
+3. Check visitCount
+   - **Expected:** `visitCount: 1`
+4. Manually increment visitCount to `3`: 
+   ```javascript
+   window.GuideAI.metadata.trackVisitManually()
+   window.GuideAI.metadata.trackVisitManually()
+   ```
+5. Verify visitCount is now `3`
+6. Open Chrome in Incognito mode (Cmd/Ctrl + Shift + N)
+7. Visit same test site
+8. Check visitCount in incognito
+   - **Expected:** `visitCount: 1`
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 2.2: Multiple Incognito Sessions
+
+**Purpose:** Verify each incognito window is isolated.
+
+**Steps:**
+1. Open Incognito Window 1
+2. Visit test site, verify visitCount = 1
+3. Increment visitCount to 2
+4. Close Incognito Window 1
+5. Open new Incognito Window 2
+6. Visit test site
+7. Check visitCount
+   - **Expected:** `visitCount: 1` (fresh incognito = fresh storage)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 3: Mobile and Desktop
+
+### Test 3.1: Desktop to Mobile Device Switch
+
+**Purpose:** Verify different devices have separate visitCount.
+
+**Steps:**
+1. On Desktop Chrome, visit test site
+2. Increment visitCount to `3`
+3. Note the visitCount and firstVisit timestamp
+4. On Mobile device (actual phone), visit same test site
+5. Check visitCount on mobile
+   - **Expected:** `visitCount: 1` (different device = different localStorage)
+6. On Mobile, increment visitCount to `2`
+7. Return to Desktop, refresh page
+8. Check visitCount on desktop
+   - **Expected:** Still `3` (unchanged by mobile activity)
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Notes:**
+```
+Desktop visitCount: ___
+Mobile visitCount: ___
+```
+
+---
+
+### Test 3.2: Desktop to Mobile Browser Emulation
+
+**Purpose:** Verify behavior using DevTools mobile emulation.
+
+**Steps:**
+1. Open Chrome DevTools → Device Toolbar (Cmd/Ctrl + Shift + M)
+2. Select iPhone or Android device
+3. Visit test site
+4. Check visitCount
+   - **Expected:** Reads from same localStorage as desktop (should be same count)
+   - **Note:** DevTools emulation does NOT create separate storage
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Important:** This test demonstrates that DevTools emulation ≠ real mobile device testing.
+
+---
+
+## Test Suite 4: Clearing Browser Data
+
+### Test 4.1: Clear All Browsing Data
+
+**Purpose:** Verify clearing data resets visitCount.
+
+**Steps:**
+1. Visit test site, increment visitCount to `5`
+2. Go to Chrome Settings → Privacy → Clear browsing data
+3. Select "All time" and check "Cookies and other site data" + "Cached images and files"
+4. Click "Clear data"
+5. Revisit test site
+6. Check visitCount
+   - **Expected:** `visitCount: 1` (treated as first-time user)
+   - **Expected:** New firstVisit timestamp
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 4.2: Clear Only Cookies (Keep Cache)
+
+**Purpose:** Verify visitCount is tied to localStorage (cookies).
+
+**Steps:**
+1. Visit test site, visitCount = 1
+2. Clear only "Cookies and other site data" (NOT cache)
+3. Revisit test site
+4. Check visitCount
+   - **Expected:** `visitCount: 1` (localStorage cleared with cookies)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 5: Real-World User Flows
+
+### Test 5.1: Morning Visit, Evening Visit (Same Day)
+
+**Purpose:** Verify visitCount behavior across a single day.
+
+**Steps:**
+1. **Morning (9 AM):** Visit test site, visitCount = 1
+2. **Afternoon (2 PM, 5 hours later):** 
+   - Close browser completely
+   - Reopen browser, visit test site
+   - **Expected:** visitCount still = 1 (within 30-min window from last activity)
+3. **Evening (10 PM, 8 hours after afternoon visit):**
+   - Reopen browser (ensure 30+ min since last visit)
+   - Visit test site
+   - **Expected:** visitCount = 2 (exceeded 30-min timeout)
+
+**Result:** ☐ PASS ☐ FAIL
+
+**Alternative:** Speed up using DevTools:
+```javascript
+// Manually set lastVisit to 31 minutes ago
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'));
+data.metadata.lastVisit = Date.now() - (31 * 60 * 1000);
+localStorage.setItem('guideai_user_metadata', JSON.stringify(data));
+// Refresh page - visitCount should increment
+```
+
+---
+
+### Test 5.2: Multiple Tabs Open Simultaneously
+
+**Purpose:** Verify visitCount is shared across tabs.
+
+**Steps:**
+1. Open Tab 1, visit test site
+2. Check visitCount in Tab 1
+   - **Expected:** `visitCount: 1`
+3. Open Tab 2 (Cmd/Ctrl + T), visit test site
+4. Check visitCount in Tab 2
+   - **Expected:** `visitCount: 1` (shared localStorage)
+5. In Tab 1, run:
+   ```javascript
+   window.GuideAI.metadata.trackVisitManually()
+   ```
+6. In Tab 2, refresh page
+7. Check visitCount in Tab 2
+   - **Expected:** `visitCount: 2` (sees update from Tab 1)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 5.3: User Login Flow
+
+**Purpose:** Verify login correctly increments visitCount.
+
+**Steps:**
+1. Visit test site (not logged in), visitCount = 1
+2. Simulate login:
+   ```javascript
+   window.GuideAI.metadata.resetSessionVisitTracking()
+   window.GuideAI.metadata.trackVisitManually()
+   window.GuideAI.metadata.trackLogin({ email: 'test@example.com' })
+   ```
+3. Check visitCount
+   - **Expected:** `visitCount: 2`
+4. Check loginCount
+   - **Expected:** `loginCount: 1`
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 6: Edge Cases
+
+### Test 6.1: Rapid Page Refreshes
+
+**Purpose:** Verify rapid refreshes don't inflate visitCount.
+
+**Steps:**
+1. Visit test site, visitCount = 1
+2. Press F5 (refresh) 10 times rapidly
+3. Check visitCount after each refresh
+   - **Expected:** `visitCount: 1` (unchanged)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+### Test 6.2: Browser Crash Recovery
+
+**Purpose:** Verify visitCount persists after browser crash.
+
+**Steps:**
+1. Visit test site, visitCount = 1
+2. Increment to visitCount = 3
+3. Force browser crash (Task Manager → End Task on browser)
+4. Reopen browser
+5. Visit test site
+6. Check visitCount
+   - **Expected:** `visitCount: 3` (persisted in localStorage)
+   - Within 30 min: stays at 3
+   - After 30+ min: increments to 4
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Test Suite 7: POC First-Time User Detection
+
+### Test 7.1: First-Time User Onboarding
+
+**Purpose:** Verify first-time user detection for onboarding flow.
+
+**Steps:**
+1. Clear all browser data
+2. Visit test site
+3. Check if onboarding appears (based on `visitCount === 1`)
+   - **Expected:** Onboarding shown
+4. Close browser, reopen within 30 min
+5. Visit test site again
+6. Check if onboarding appears
+   - **Expected:** Onboarding STILL shown (visitCount still 1)
+7. Wait 31+ minutes (or manually set lastVisit to 31 min ago)
+8. Visit test site
+9. Check visitCount
+   - **Expected:** `visitCount: 2`
+   - **Expected:** Onboarding NOT shown (returning user)
+
+**Result:** ☐ PASS ☐ FAIL
+
+---
+
+## Utility Commands
+
+### Inspect localStorage
+```javascript
+// Get full metadata
+JSON.parse(localStorage.getItem('guideai_user_metadata'))
+
+// Get just visitCount
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+console.log('visitCount:', data.metadata.visitCount)
+
+// Get sessionId
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+console.log('sessionId:', data.metadata.sessionId)
+```
+
+### Manually Set visitCount
+```javascript
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+data.metadata.visitCount = 5
+localStorage.setItem('guideai_user_metadata', JSON.stringify(data))
+location.reload()
+```
+
+### Simulate 31 Minutes Ago
+```javascript
+const data = JSON.parse(localStorage.getItem('guideai_user_metadata'))
+data.metadata.lastVisit = Date.now() - (31 * 60 * 1000)
+localStorage.setItem('guideai_user_metadata', JSON.stringify(data))
+location.reload() // visitCount should increment
+```
+
+### Force Visit Increment
+```javascript
+window.GuideAI.metadata.trackVisitManually()
+```
+
+### Clear All Data
+```javascript
+localStorage.clear()
+sessionStorage.clear()
+location.reload()
+```
+
+---
+
+## Summary Checklist
+
+After completing all tests, verify these scenarios PASS:
+
+- [ ] **Cross-Browser:** Chrome → Firefox = visitCount resets to 1
+- [ ] **Incognito Mode:** Always treated as first-time user (visitCount = 1)
+- [ ] **Mobile → Desktop:** Separate visitCount on different devices
+- [ ] **Clear Data:** Clearing browser data resets visitCount
+- [ ] **Same Browser, Multiple Sessions (< 30 min):** visitCount unchanged
+- [ ] **Same Browser, Multiple Sessions (> 30 min):** visitCount increments
+- [ ] **Multiple Tabs:** visitCount shared via localStorage
+- [ ] **Login Flow:** Login correctly increments visitCount
+- [ ] **First-Time User Detection:** `visitCount === 1` correctly identifies new users
+
+---
+
+## Test Results Summary
+
+| Test | Status | Notes |
+|------|--------|-------|
+| Cross-Browser (Chrome → Firefox) | ☐ PASS ☐ FAIL | |
+| Incognito Mode | ☐ PASS ☐ FAIL | |
+| Desktop → Mobile | ☐ PASS ☐ FAIL | |
+| Clear Browser Data | ☐ PASS ☐ FAIL | |
+| Same Session (< 30 min) | ☐ PASS ☐ FAIL | |
+| New Session (> 30 min) | ☐ PASS ☐ FAIL | |
+| Multiple Tabs | ☐ PASS ☐ FAIL | |
+| Login Flow | ☐ PASS ☐ FAIL | |
+| First-Time User Detection | ☐ PASS ☐ FAIL | |
+
+**Date Tested:** __________  
+**Tester Name:** __________  
+**Browser Versions Tested:**
+- Chrome: __________
+- Firefox: __________
+- Safari: __________
+- Mobile: __________
+
+---
+
+## Troubleshooting
+
+### visitCount not incrementing after 30+ minutes
+- Check that `trackVisits: true` in GuideAI config
+- Verify `sessionTimeout` is set to 30 * 60 * 1000 (default)
+- Check console for errors
+
+### visitCount incrementing on every page load
+- Check if localStorage is disabled in browser
+- Verify localStorage is not being cleared by extensions
+- Check for errors in browser console
+
+### Different visitCount in different tabs
+- This should NOT happen - localStorage is shared
+- If this occurs, check for localStorage corruption
+- Clear all data and retest
+
+---
+
+## Conclusion
+
+These manual tests complement the automated unit/integration tests and validate that visitCount behaves correctly in real-world scenarios. The current implementation is **"good enough"** for the POC if all tests pass, acknowledging that users will be treated as first-time users when:
+1. Switching browsers
+2. Using incognito mode
+3. Switching devices
+4. Clearing browser data
+

package/dist/GuideAI.d.ts

@@ -1,4 +1,3 @@
-import React from 'react';
 import { GuideAIProps } from './types/GuideAI.types';
-declare const GuideAI: (props: GuideAIProps) => React.JSX.Element | null;
+declare const GuideAI: (props: GuideAIProps) => import("react").JSX.Element | null;
 export default GuideAI;