# Testing

This document describes how to run and write tests for Bookhoard.

## Test Users and Email Domains

### Test Email Domain

All integration tests use the email domain **`@tests.bookhoard.internal`** for test users. This domain is reserved exclusively for testing and will never be used in production.

**Why this domain?**

- Clear indication it's for testing only
- Won't conflict with real user emails (which use real domains like `@gmail.com`, `@example.com`, etc.)
- Safe cleanup: Tests can delete all users with this domain without risk to production data
- If a real user somehow uses `@tests.bookhoard.internal`, they are explicitly opting into test data deletion

### Standard Test Users

The test suite creates these standard users:

1. **Admin User**
   - Email: `testuser@tests.bookhoard.internal`
   - Username: `testuser`
   - Password: `Test@Pass123!`
   - Role: `admin`

2. **Regular User**
   - Email: `testregularuser@tests.bookhoard.internal`
   - Username: `testregularuser`
   - Password: `Test@Pass123!`
   - Role: `user`

### Test Lifecycle and Cleanup

Each test run:

1. **Deletes** all existing users with `@tests.bookhoard.internal` email
2. **Creates** fresh standard test users
3. **Runs** the test with clean state
4. **Cleans up** via `t.Cleanup()` to delete users created during the test

This ensures complete test isolation - no state leaks between tests.

### Writing Tests

When writing new tests:

**✅ DO:**

- Use the standard test users from `setupTestServer(t)`
- Use `createRegularUserOnce(t, setup.DB)` for additional test users
- Let the test framework handle cleanup
- Use the `@tests.bookhoard.internal` domain if creating custom test users

**❌ DON'T:**

- Use real email domains like `@example.com` or `@gmail.com`
- Manually manage test user deletion (unless absolutely necessary)
- Assume test users persist between test runs
- Hardcode user IDs (always look up by email/username)

## Running Tests

### Run All Tests

```bash
make test
```

### Run Integration Tests Only

```bash
make test-integration
```

### Run Specific Test

```bash
go test -v -run TestUpdateProfile ./cmd/server/tests/
```

### Run with Race Detection

```bash
go test -race ./cmd/server/tests/
```

## Test Organization

Tests are located in `cmd/server/tests/`:

- `test_helpers.go` - Test utilities and setup functions
- `*_test.go` - Test files organized by feature
  - `user_test.go` - User management tests
  - `auth_test.go` - Authentication tests
  - `media_test.go` - Media item tests
  - etc.

### Key Test Helpers

- `setupTestServer(t *testing.T)` - Creates test server with clean DB state
- `createTestUserOnce(t, db)` - Gets/creates standard admin user
- `createRegularUserOnce(t, db)` - Gets/creates additional test users
- `loginWithCredentials(t, server, email, password)` - Returns auth token

## Bruno API Tests

API integration tests in `bruno/` also use the test email domain:

- Login test: `testuser@tests.bookhoard.internal`
- Register test: `testuser@tests.bookhoard.internal`
- Profile update test: `updated@tests.bookhoard.internal`

See: [Bruno Documentation](https://docs.usebruno.com/)