bookhoard/docs/developer/testing.md

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

make test

Run Integration Tests Only

make test-integration

Run Specific Test

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

Run with Race Detection

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