docs: update comprehensive API documentation and project guides
This commit updates all documentation files throughout the project: - Updated IMPLEMENTATION_PLAN.md with new implementation details - Updated PROJECT_GUIDELINES.md with coding standards and practices - Updated README.md with current project information - Updated SCREENSHOT_AUTOMATION.md with new automation details - Added TEST_DATA.md with test fixtures data - Updated cover_image_serving_plan.md with static URL patterns Documentation API updates: - Updated API reference documentation for all endpoints including: - Authentication (login, logout, register, refresh_token) - Book matching (auto_link, bulk_link, link_book, search) - Collections (CRUD operations, shelf mappings, auto-assign rules) - Conflicts (bulk operations, resolve/dismiss) - Devices (registration, approval, shelf management) - Highlights (create, update, delete, get) - Kobo sync (bookmark, markup, initialization, sync) - KOReader sync (library, metadata, bookmarks, progress) - Libraries (CRUD, folders, media items, stats) - Media items (bulk operations, CRUD) - Notes (CRUD operations) - OPDS (acquisition, feeds, publication) - Progress (reading progress tracking) - Queue (device queue management) - Ratings (star ratings) - Scanner (watch mode, scan operations) - Sync protocols (Kobo, KOReader) - Users (profile, password, admin operations) - WebSocket protocols - Updated user guides (admin, dashboard, settings, sync) - Updated device setup guides (Kobo, KOReader) - Updated developer guides (testing, contributing, operations) - Updated scripts/README.md
This commit is contained in:
@@ -5,6 +5,7 @@ This document describes the shared test data used across Go integration tests an
|
||||
## Test Users
|
||||
|
||||
### Main Admin Test User
|
||||
|
||||
This is the primary test user used in most integration tests.
|
||||
|
||||
```json
|
||||
@@ -19,15 +20,18 @@ This is the primary test user used in most integration tests.
|
||||
```
|
||||
|
||||
**Used in:**
|
||||
|
||||
- Go Tests: `cmd/server/tests/test_helpers.go` (getTestUserID, loginTestUser)
|
||||
- Bruno: `user/auth/Login User.yml`, `user/auth/Register User.yml`
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Automatically created if doesn't exist
|
||||
- Deleted and recreated in tests to ensure fresh state
|
||||
- Used for authentication in most test scenarios
|
||||
|
||||
### Max Devices Test User
|
||||
|
||||
Used specifically for testing device limit functionality.
|
||||
|
||||
```json
|
||||
@@ -41,9 +45,11 @@ Used specifically for testing device limit functionality.
|
||||
```
|
||||
|
||||
**Used in:**
|
||||
|
||||
- Go Tests: `cmd/server/tests/device_cap_test.go` (createTestUserForMaxDevices)
|
||||
|
||||
### Secondary Admin Test User
|
||||
|
||||
Used for testing admin creation restrictions and multi-admin scenarios.
|
||||
|
||||
```json
|
||||
@@ -58,11 +64,13 @@ Used for testing admin creation restrictions and multi-admin scenarios.
|
||||
```
|
||||
|
||||
**Used in:**
|
||||
|
||||
- Bruno: `user/admin/Register Admin User.yml`
|
||||
|
||||
## Test Libraries
|
||||
|
||||
### Standard Test Library
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Test Library",
|
||||
@@ -72,10 +80,12 @@ Used for testing admin creation restrictions and multi-admin scenarios.
|
||||
```
|
||||
|
||||
**Used in:**
|
||||
|
||||
- Go Tests: `cmd/server/tests/test_helpers.go` (createTestEbookID)
|
||||
- Multiple test files for library management
|
||||
|
||||
### Search Test Library
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Search Test Library",
|
||||
@@ -85,11 +95,13 @@ Used for testing admin creation restrictions and multi-admin scenarios.
|
||||
```
|
||||
|
||||
**Used in:**
|
||||
|
||||
- Go Tests: `cmd/server/tests/search_test.go`
|
||||
|
||||
## Test Books/Media Items
|
||||
|
||||
### Standard Test Ebook
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Test Ebook",
|
||||
@@ -101,10 +113,13 @@ Used for testing admin creation restrictions and multi-admin scenarios.
|
||||
```
|
||||
|
||||
**Used in:**
|
||||
|
||||
- Go Tests: `cmd/server/tests/test_helpers.go` (createTestEbookID)
|
||||
|
||||
### Test Book Variants
|
||||
|
||||
Multiple test books with different titles for testing:
|
||||
|
||||
- "Test Book 1"
|
||||
- "Test Book 2"
|
||||
- "Test Book Title"
|
||||
@@ -113,6 +128,7 @@ Multiple test books with different titles for testing:
|
||||
## Test Devices
|
||||
|
||||
Test devices typically follow this pattern:
|
||||
|
||||
- Device ID: UUID format
|
||||
- Device Name: "Test Device" or descriptive names
|
||||
- User association: Linked to test users
|
||||
@@ -139,23 +155,28 @@ Test devices typically follow this pattern:
|
||||
## File Paths
|
||||
|
||||
### Container Paths (inside Docker container)
|
||||
|
||||
- Uploads: `/app/uploads`
|
||||
- Cache: `/app/cache/kepub`
|
||||
|
||||
### Host Paths (when running tests from host)
|
||||
|
||||
- Uploads: `./uploads`
|
||||
- Cache: Docker volume (not on host filesystem)
|
||||
|
||||
## How to Use This Data
|
||||
|
||||
### In Bruno Tests
|
||||
|
||||
1. Start the server: `podman compose up -d`
|
||||
2. Run "Register User" to create the test admin user
|
||||
3. Run "Login User" to get the JWT token
|
||||
4. Use the token for authenticated requests
|
||||
|
||||
### In Go Tests
|
||||
|
||||
The test helpers automatically create and clean up test data:
|
||||
|
||||
```go
|
||||
ts, db, cfg := setupTestServer(t)
|
||||
token := loginTestUser(t, ts, db)
|
||||
@@ -163,7 +184,9 @@ userID := getTestUserID(t, db)
|
||||
```
|
||||
|
||||
### Cross-Referencing
|
||||
|
||||
When you find a bug in Bruno tests:
|
||||
|
||||
1. Check the same scenario in Go tests using the same credentials
|
||||
2. Use the same email/password to debug
|
||||
3. Verify the database state matches expectations
|
||||
@@ -171,6 +194,7 @@ When you find a bug in Bruno tests:
|
||||
## Resetting Test Data
|
||||
|
||||
### Reset Database
|
||||
|
||||
```bash
|
||||
# Stop containers and remove volumes
|
||||
podman compose down -v
|
||||
@@ -180,7 +204,9 @@ podman compose up -d
|
||||
```
|
||||
|
||||
### Reset Specific Test User
|
||||
|
||||
If you need to recreate just the test user:
|
||||
|
||||
```bash
|
||||
# Login to database
|
||||
podman exec -it bookhoard_db psql -U postgres -d bookhoard
|
||||
@@ -202,6 +228,7 @@ DELETE FROM users WHERE email = 'testuser@example.com';
|
||||
## Adding New Test Data
|
||||
|
||||
When adding new test data:
|
||||
|
||||
1. Choose descriptive names following the pattern "Test X"
|
||||
2. Use consistent email format: `testpurpose@example.com`
|
||||
3. Document in this file for cross-reference
|
||||
|
||||
Reference in New Issue
Block a user