myworkspace/Linkding Browser Extension/LinkdingSync/docs/phase0-plan.md

Phase 0: Testing & Server Behavior Validation

Overview

This document outlines the complete Phase 0 plan for testing Linkding server behavior before redesigning the LinkdingSync extension. The goal is to gather critical information about:

1. API Key Isolation: Do API keys provide bookmark isolation, or is the user account the only isolation boundary?
2. Conflict Resolution: How does Linkding handle same URL in different contexts (paths, notes)?
3. Delete Behavior: Does deletion via one API key affect bookmarks created by other keys?
4. Bundle Tag Filtering: How do bundles act as filters for bookmark queries?

Current Status

Item	Status
Review extension codebase	✅ Complete
Review Linkding source code	✅ Complete
Analyze TODOs.txt findings	✅ Complete
Create test scenarios doc	✅ Complete
Create test runner script	✅ Complete
Execute tests	⏳ Pending
Finalize design	⏳ Pending

---

Prerequisites

1. Create Test User Accounts

You need to create 2 user accounts on your Linkding instance:

user_work      - For work-related bookmarks
user_personal  - For personal bookmarks

2. Create API Keys

For each user, create at least 2 API keys (one per bundle):

User	Key Purpose	Example Name
user_work	Work bundle access	user_work_key_1
user_work	Work bundle access	user_work_key_2
user_personal	Personal bundle access	user_personal_key_1
user_personal	Personal bundle access	user_personal_key_2

How to create API keys:

1. Go to Linkding settings → Advanced
2. Click "Create new token"
3. Give it a descriptive name (e.g., "work-bundle-1")
4. Copy the generated key (it won't be shown again)

3. Create Bundles

Create bundles for filtering:

Bundle Name	Purpose
work	Filter work bookmarks
personal	Filter personal bookmarks

4. Firefox Configuration

Option A: Single Firefox Profile with Multiple API Keys

Create a Firefox profile that can hold multiple API keys for testing. This allows:

• Easy switching between work/personal contexts
• Running automated tests via DevTools console

Option B: Separate Firefox Profiles

Create two separate Firefox profiles:

• work-profile - Configured with work API key
• personal-profile - Configured with personal API key

This is simpler but requires switching profiles between tests.

---

Test Execution Instructions

Step 1: Load Test Runner

1. Open Firefox
2. Navigate to your Linkding settings page (any page works)
3. Open DevTools (press F12)
4. Go to the Console tab
5. Copy the entire contents of test-runner.js
6. Paste into the console (Ctrl+Shift+V)
7. Press Enter

You should see:

LinkdingSync Test Runner loaded successfully

Step 2: Configure Credentials

In the console, modify the CONFIG object:

const CONFIG = {
  serverUrl: 'https://links.blabber1565.com',
  workApiKey: 'your_work_api_key_here',      // Paste API key
  personalApiKey: 'your_personal_api_key_here',
  workUser: 'user_work',
  personalUser: 'user_personal',
  workBundle: 'work',
  personalBundle: 'personal',
  cleanupAfterTests: true
};

Security Note:

• API keys are stored in the Firefox session (cleared when Firefox closes)
• Consider creating a separate .creds.txt file for manual reference if needed

Step 3: Run Tests

Execute the test suite:

runTestSuite()

This will run all 6 test scenarios and display results in the console.

Step 4: Analyze Results

Each test will output:

• Setup information
• API responses
• Result analysis with ✓ or ✗ indicators

Example output:

=== Scenario 1: Same URL, Different API Keys, Same User ===
  ✓ Created: ID=123, URL=https://example.com
  ✓ Created: ID=456, URL=https://example.com

Results:
  Bookmark 1 ID: 123
  Bookmark 2 ID: 456
  ✅ RESULT: Different bookmark IDs - API keys provide isolation

Step 5: Cleanup (Optional)

After tests complete, clean up test bookmarks:

cleanup()

Or disable automatic cleanup in CONFIG:

cleanupAfterTests: false

---

Expected Test Outcomes

Test 1: API Key Isolation

Possible Results:

• Same ID: API keys don't provide isolation - user account is the only boundary
• Different IDs: API keys provide isolation within same user

Decision Impact:

• If keys don't isolate → Use separate users for work/personal isolation
• If keys do isolate → Can use same user with different API keys

Test 2: Cross-User Visibility

Possible Results:

• User B sees User A's bookmarks: Sharing enabled or same underlying user
• User B cannot see User A's bookmarks: Proper isolation

Decision Impact:

• Need separate users with sharing disabled for true isolation

Test 3: Path Conflict Resolution

Possible Results:

• Same ID: Server merges by URL, last-write-wins for path/notes
• Different IDs: Server creates separate bookmarks

Decision Impact:

• If merges → Need path merge strategy (keep both, prompt user, etc.)
• If separate → Can use duplicate bookmarks for different contexts

Test 4: Title/Description Merge

Possible Results:

• Last-write-wins: Most recent update wins
• Merge: Both values combined somehow
• No conflict: Different titles preserved

Decision Impact:

• Determine merge strategy for conflict resolution

Test 5: Delete Propagation

Possible Results:

• Propagates: Deleting via one key deletes all
• Doesn't propagate: Separate bookmarks per key

Decision Impact:

• Aligns with Test 3 results

Test 6: Bundle Tag Filtering

Possible Results:

• Works: Tags filter bookmarks by tag
• Doesn't work: Tags don't provide isolation

Decision Impact:

• Bundle tags can provide logical separation

---

Test Results Analysis Template

After running tests, document results in docs/test-results.md:

# Test Results

## Test 1: API Key Isolation
- **Result**: [same/different] IDs
- **Conclusion**: API keys [do/don't] provide isolation
- **Implication**: Need [separate users OR same user strategy]

## Test 2: Cross-User Visibility  
- **Result**: User B [can/cannot] see User A's bookmarks
- **Conclusion**: Sharing is [enabled/disabled]
- **Implication**: [Use different users or different settings]

## Test 3: Path Conflict Resolution
- **Result**: [same/different] IDs
- **Conclusion**: Server [merges/creates separate] bookmarks
- **Implication**: [Merge paths OR keep separate]

## Test 4: Title/Description Conflict
- **Result**: [last-write-wins/merge/no-conflict]
- **Conclusion**: Server [uses last-write/merges/doesn't conflict]
- **Implication**: [Strategy for conflict resolution]

## Test 5: Delete Propagation
- **Result**: Delete [propagated/didn't propagate]
- **Conclusion**: Deletion [affects all OR affects specific]
- **Implication**: [Delete strategy]

## Test 6: Bundle Tag Filtering
- **Result**: Bundle tags [work/don't work]
- **Conclusion**: Tags [provide/isolate] bookmarks
- **Implication**: [Use tags OR use users]

## Final Strategy
Based on results:
- [User isolation approach]
- [Conflict resolution strategy]
- [Sync behavior]

---

Next Steps After Phase 0

Once tests complete:

1. Analyze Results: Review test outputs and document in test-results.md
2. Finalize Design: Create new design.md with confirmed behaviors
3. Redesign Extension: Implement new architecture based on test findings
4. Create Tests: Write unit tests in tests/ directory
5. Implement Features: Add UI improvements and scheduled sync
6. Document: Update README.md and API docs

---

Files Created

File	Purpose
docs/phase0-test-scenarios.md	Detailed test scenarios
test-runner.js	Automated test execution script
docs/phase0-plan.md	This document

---

Questions for You

Before you create the test accounts and run tests:

1. Firefox Setup: Which option do you prefer?

   • Single profile with multiple API keys (more complex, more flexible)
   • Separate profiles (simpler, less flexible)

2. API Key Count: Do you want to create:

   • 2 API keys per user (minimal for testing)
   • 4 API keys per user (more scenarios)

3. Bundles: Should we create:

   • 2 bundles (work, personal)
   • 4 bundles (more granular)

4. Test Execution: Will you run:

   • All tests at once (runTestSuite())
   • Individual tests as you discover issues

Let me know, and I can adjust the test runner accordingly. Once you're ready to create the test accounts, just let me know and I'll provide final instructions.