bookhoard/TEST_DATA.md

# Test Data Documentation

This document describes the shared test data used across Go integration tests and Bruno API tests. Keeping these aligned makes it easier to verify issues and cross-reference between testing frameworks.

## Test Users

### Main Admin Test User
This is the primary test user used in most integration tests.

```json
{
  "email": "testuser@example.com",
  "username": "testuser",
  "password": "Test@Pass123!",
  "first_name": "Test",
  "last_name": "User",
  "role": "admin"
}
```

**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
{
  "email": "maxdevices@example.com",
  "username": "maxdevicesuser",
  "password": "Test@Pass123!",
  "first_name": "Test",
  "last_name": "User"
}
```

**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
{
  "email": "admin2@example.com",
  "username": "admin2",
  "password": "!Admin@123",
  "first_name": "Admin",
  "last_name": "User",
  "role": "admin"
}
```

**Used in:**
- Bruno: `user/admin/Register Admin User.yml`

## Test Libraries

### Standard Test Library
```json
{
  "name": "Test Library",
  "description": "A test library for ebooks",
  "type": "ebooks"
}
```

**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",
  "description": "Library for search tests",
  "type": "ebooks"
}
```

**Used in:**
- Go Tests: `cmd/server/tests/search_test.go`

## Test Books/Media Items

### Standard Test Ebook
```json
{
  "title": "Test Ebook",
  "author": "Test Author",
  "file_path": "/tmp/test.epub",
  "file_size": 1024,
  "mime_type": "application/epub+zip"
}
```

**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"
- "A Book", "B Book", "C Book" (for sorting tests)

## 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

## Test Collections

```json
{
  "name": "Test Collection",
  "description": "A test collection",
  "rules": {
    "operator": "AND",
    "conditions": [
      {
        "field": "media.title",
        "operator": "contains",
        "value": "Test"
      }
    ]
  }
}
```

## 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)
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

## Resetting Test Data

### Reset Database
```bash
# Stop containers and remove volumes
podman compose down -v

# Restart with fresh database
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

# Delete test user
DELETE FROM users WHERE email = 'testuser@example.com';

# Exit
\q
```

## Notes

- All test passwords use the bcrypt hash format in the database
- The password `Test@Pass123!` is used across most test users for consistency
- Test users are created with `role: "admin"` to enable full API access
- Tests automatically clean up their data, but manual testing may require database resets

## 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
4. Update both Go tests and Bruno collections for consistency