myworkspace/Linkding Browser Extension/LinkdingSync/docs/test-usage.md

# LinkdingSync Test Usage Guide

## Quick Start

### Step 1: Load Test Files in Firefox DevTools

1. Open Firefox and navigate to your Linkding instance
2. Open DevTools (`F12`) and go to the **Console** tab
3. Copy the entire contents of `tests/orchestrator.js`
4. Paste into the console (Ctrl+Shift+V)
5. Press Enter

You should see:
```
LinkdingSync Test Orchestrator loaded

Commands:
  runAllTests()        - Run all tests
  runAllTestsWithReset() - Run with cleanup first
  runModule("name")    - Run specific test module
  reset()              - Clean up test bookmarks
```

### Step 2: Configure Credentials

The `tests/utils.js` file already contains your credentials from `.creds.txt`:

```javascript
const CONFIG = {
  serverUrl: 'https://links.blabber1565.com',
  workApiKey: '4108e3aff26fb82bf074f5d4dfa4757763520b06',
  workUser: 'linkdingsync_tester',
  workBundle: 'work',
  personalApiKey: '9b80accd3b9b4b91c2a7adc3dcf41621b025329a',
  personalUser: 'linkdingsync_tester_2',
  personalBundle: 'personal',
  cleanupAfterTests: true
};
```

If you need to modify credentials, edit `tests/utils.js` directly.

### Step 3: Run Tests

#### Run All Tests

```javascript
runAllTests()
```

This will execute all 8 test scenarios and display results in the console.

#### Run with Reset First

```javascript
runAllTestsWithReset()
```

This cleans up any existing test bookmarks before running tests.

#### Run Specific Module

```javascript
runModule('isolation')  // Tests 1-2: API Key & User Isolation
runModule('conflicts')  // Tests 3-4: Conflict Resolution
runModule('deletion')   // Tests 5-6: Delete Propagation
runModule('bundles')    // Tests 7-8: Bundle Filtering
```

#### Reset Test Bookmarks

```javascript
reset()
```

Or run `runAllTestsWithReset()` which includes reset automatically.

---

## Test Scenarios

| Module | Tests | Purpose |
|--------|-------|---------|
| **isolation** | 1-2 | Verify API key and user isolation |
| **conflicts** | 3-4 | Conflict resolution behavior |
| **deletion** | 5-6 | Delete propagation behavior |
| **bundles** | 7-8 | Bundle tag filtering |

---

## Expected Output

Each test module produces output like:

```
=== Test 1: Same URL, Different API Keys, Same User ===
Purpose: Verify if API keys provide isolation within same user
  Created: ID=test-0585-ab
  Created: ID=test-0585-ac

  Work bookmark ID: test-0585-ab
  Personal bookmark ID: test-0585-ac

  [Test 1] ✓ PASS Different bookmark IDs - API keys provide isolation
  → Different API keys create separate bookmarks

=== Test 2: Different Users - Verify Isolation ===
  Bookmark created by work user: ID=test-0586-ab
  
  Work user sees bookmark: Test: test-0586-ab
  
  Personal user sees 1 bookmarks
  
  [Test 2] ✓ PASS Proper user isolation exists
  → Can use different API keys for isolation
```

---

## Interpreting Results

### Isolation Tests

- **PASS**: Different API keys create separate bookmarks
- **FAIL**: Same bookmark ID means API keys don't provide isolation

### Conflict Resolution Tests

- **PASS**: Server creates separate bookmarks per API key
- **WARN**: Unexpected behavior detected

### Delete Propagation Tests

- **PASS**: Each bookmark exists independently
- **FAIL**: Delete propagates (same bookmark)

### Bundle Tests

- **PASS**: Bundles provide logical separation
- **WARN**: Bundle filtering unclear

---

## Debugging

### View All Test Bookmarks

```javascript
LinkdingSyncTests.Helpers.getAllBookmarks()
```

### Check a Specific Bookmark

```javascript
LinkdingSyncTests.Helpers.fetchBookmark('bookmark-id')
```

### Parse Bookmark Notes

```javascript
LinkdingSyncTests.Helpers.parseNotes(bookmark.notes)
```

### Reset Everything

```javascript
reset()
```

---

## Next Steps After Phase 0

Once tests complete:

1. **Review Results**: Check which tests pass/fail
2. **Document Findings**: Update `docs/test-results.md`
3. **Finalize Design**: Create new architecture based on test results
4. **Redesign Extension**: Implement new LinkdingSync based on findings
5. **Write Unit Tests**: Add tests to `tests/` directory

---

## Common Commands

```javascript
// Run all tests
runAllTestsWithReset()

// Run isolation tests only
runModule('isolation')

// Check current bookmarks
LinkdingSyncTests.Helpers.getAllBookmarks()

// Reset before running
reset()
```

---

## Troubleshooting

### Tests Not Running

- **Check**: Console shows "Orchestrator loaded"
- **Solution**: Load `orchestrator.js` first, then modules

### Credentials Not Working

- **Check**: `CONFIG` in `utils.js` has correct values
- **Solution**: Verify API keys work in Linkding UI

### Tests Creating Duplicate Bookmarks

- **Expected**: This is the test behavior
- **Solution**: Run `reset()` to clean up

---

## File Structure

```
LinkdingSync/
├── tests/
│   ├── utils.js              # Shared utilities
│   ├── orchestrator.js       # Main test runner
│   ├── test-isolation.js     # Isolation tests
│   ├── test-conflicts.js     # Conflict tests
│   ├── test-deletion.js      # Deletion tests
│   └── test-bundles.js       # Bundle tests
├── docs/
│   ├── phase0-plan.md        # Phase 0 planning
│   ├── test-usage.md         # This file
│   └── phase0-test-scenarios.md
├── test-runner.js            # Legacy (can be deleted after migration)
└── .creds.txt                # Test credentials
```

---

## Security Notes

- API keys stored in Firefox session (cleared when browser closes)
- Test bookmarks have unique testId prefix
- All test bookmarks are cleaned up automatically
- No sensitive data in test bookmarks

---

## Support

For issues, check:
1. Console output for error messages
2. `.creds.txt` for correct credentials
3. Linkding server logs for API errors