Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation
This commit is contained in:
DavidSaylor
256
Linkding Browser Extension/LinkdingSync/docs/test-usage.md
Normal file
256
Linkding Browser Extension/LinkdingSync/docs/test-usage.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user