From ac880318557fc75a408f2b152e6b7a7a1d01c98c Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Tue, 17 Feb 2026 22:27:51 -0500 Subject: [PATCH] docs(dashboard): document test helpers and cleanup patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive documentation of available test helpers: Available Helpers (from test_helpers.go): - setupTestServer(t) - Creates test server with auto cleanup via t.Cleanup() - loginTestUser(t, ts, db) - Logs in admin user, returns JWT token - loginRegularUser(t, ts, db) - Logs in regular user, returns JWT token - setupDeviceTest(t) - Creates server + user + device + library - getTestUserID(t, db) - Gets/creates admin test user UUID - getRegularUserID(t, db) - Gets/creates regular test user UUID TestServerSetup Structure: - Server *httptest.Server - DB *database.Queries - DBPool *pgxpool.Pool - Config *config.Config - ConnManager, QueueProcessor - Auto cleanup via t.Cleanup() Cleanup Pattern: - Automatic cleanup registered in setupTestServer() - Runs even if test fails or panics - Order: queue processor → connection manager → HTTP server → database pool - No manual defer setup.Close() needed Updated Integration Tests: - Added proper imports (database, uuid, pgtype) - Documented available helpers - Removed custom helpers that don't exist - Uses existing project patterns This ensures developers know what helpers are available and how to use them correctly. --- CAROUSEL_DASHBOARD_PLAN.md | 83 ++++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 16 deletions(-) diff --git a/CAROUSEL_DASHBOARD_PLAN.md b/CAROUSEL_DASHBOARD_PLAN.md index 7e4bbfb..f8628ec 100644 --- a/CAROUSEL_DASHBOARD_PLAN.md +++ b/CAROUSEL_DASHBOARD_PLAN.md @@ -2142,6 +2142,35 @@ func TestGetSectionViewAllURL(t *testing.T) { **COMPLIANCE**: Integration tests in `cmd/server/tests/`, using `setupTestServer` helper +**Available Test Helpers (from `test_helpers.go`):** + +| Helper | Purpose | Returns | +|--------|---------|---------| +| `setupTestServer(t)` | Creates test server with auto cleanup | `*TestServerSetup` | +| `loginTestUser(t, ts, db)` | Logs in admin user (role: admin) | JWT token string | +| `loginRegularUser(t, ts, db)` | Logs in regular user (role: user) | JWT token string | +| `setupDeviceTest(t)` | Creates server + user + device + library | `*TestDeviceSetup` | +| `getTestUserID(t, db)` | Gets/creates admin test user | `uuid.UUID` | +| `getRegularUserID(t, db)` | Gets/creates regular test user | `uuid.UUID` | + +**Cleanup Pattern:** +- `setupTestServer()` automatically registers `t.Cleanup()` +- Cleanup runs even if test fails or panics +- No manual `defer setup.Close()` needed + +**TestServerSetup Contains:** +```go +type TestServerSetup struct { + Server *httptest.Server // Test HTTP server + DB *database.Queries // Database queries + DBPool *pgxpool.Pool // Database pool + Config *config.Config // Test configuration + ConnManager *wsync.ConnectionManager + QueueProcessor *wsync.SyncQueueProcessor + // ... auto cleanup via t.Cleanup() +} +``` + **File: `cmd/server/tests/dashboard_test.go`** (new file) ```go @@ -2149,10 +2178,14 @@ package main import ( "bytes" + "context" "encoding/json" "net/http" "testing" + "bookhoard/internal/database" + "github.com/google/uuid" + "github.com/jackc/pgx/v5/pgtype" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) @@ -2397,6 +2430,7 @@ func TestDashboardSSR_Page(t *testing.T) { // Helper functions for dashboard tests +// updateDashboardPreferences saves dashboard preferences for testing func updateDashboardPreferences(t *testing.T, db *database.Queries, userID, libraryID uuid.UUID, prefs map[string]interface{}) { hiddenSections := prefs["hidden_sections"].([]string) sectionOrder := prefs["section_order"].([]string) @@ -2410,24 +2444,41 @@ func updateDashboardPreferences(t *testing.T, db *database.Queries, userID, libr }) require.NoError(t, err, "Failed to update dashboard preferences") } - -func getUserUUIDFromToken(t *testing.T, db *database.Queries, token string) uuid.UUID { - // Parse JWT and extract user ID - // This would use the same logic as the JWT middleware - // For now, return test user UUID from database - user, err := db.GetUserByEmail(context.Background(), "testuser@example.com") - require.NoError(t, err) - - return uuid.UUID(user.ID.Bytes[0:16]) -} - -func parseUUID(t *testing.T, uuidStr string) uuid.UUID { - id, err := uuid.Parse(uuidStr) - require.NoError(t, err) - return id -} ``` +**Key Helper Functions Available:** + +From `test_helpers.go`: + +```go +// setupTestServer creates complete test environment with auto cleanup +setup := setupTestServer(t) +// No manual cleanup needed - t.Cleanup() registered automatically + +// loginTestUser - logs in admin user (testuser@example.com) +adminToken := loginTestUser(t, setup.Server, setup.DB) + +// loginRegularUser - logs in regular user (testregularuser@example.com) +userToken := loginRegularUser(t, setup.Server, setup.DB) + +// setupDeviceTest - creates server + user + device + library +deviceSetup := setupDeviceTest(t) +deviceSetup.CreateLibrary(t, "My Library", "ebooks") +deviceSetup.CreateDevice(t, "Kindle", "kindle", "kindle-123") + +// getTestUserID - gets/creates admin test user UUID +adminUUID := getTestUserID(t, setup.DB) + +// getRegularUserID - gets/creates regular test user UUID +userUUID := getRegularUserID(t, setup.DB) +``` + +**Cleanup Pattern:** +- ✅ Automatic via `t.Cleanup()` in `setupTestServer()` +- ✅ Runs even if test fails or panics +- ✅ No manual `defer setup.Close()` needed +- ✅ Cleans up: queue processor → connection manager → HTTP server → database pool + **Key Points**: - ✅ Integration tests in `cmd/server/tests/` - ✅ Uses `setupTestServer(t)` helper (from `test_helpers.go`)