From 8a40349fa17af1c00bc6ab7badf0eb5ff0d84746 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Mon, 2 Nov 2026 14:53:20 -0500
Subject: [PATCH] =?UTF-8?q?docs(dev):=20delete=20developer/testing.md=20?=
 =?UTF-8?q?=E2=80=94=20contradicted=20current=20test=20doctrine?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Feb-era page described a wipe-all-test-users-per-run lifecycle,
which current doctrine explicitly forbids: the shared testuser is a
LIVE reader whose settings and history must survive every suite run,
cleanups are scoped preserve-lists, and hand-probes must be deleted.
Its recipes were also stale (no container runner, no pool rules, no
gates). The canonical home is docs/contributing/development.md
(architecture, setup, testing, project rules — kept fresh, 542 lines,
touched today), so the page was deleted rather than rewritten, with a
docRedirects entry sending old URLs there. No inbound doc links
existed.
---
 docs/developer/testing.md     | 115 ----------------------------------
 internal/docs/http_handler.go |   6 ++
 2 files changed, 6 insertions(+), 115 deletions(-)
 delete mode 100644 docs/developer/testing.md

diff --git a/docs/developer/testing.md b/docs/developer/testing.md
deleted file mode 100644
index f08d783a..00000000
--- a/docs/developer/testing.md
+++ /dev/null
@@ -1,115 +0,0 @@
-# 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/)
diff --git a/internal/docs/http_handler.go b/internal/docs/http_handler.go
index ec6bf492..91e60fc6 100644
--- a/internal/docs/http_handler.go
+++ b/internal/docs/http_handler.go
@@ -29,6 +29,12 @@ type HTTPHandler struct {
 var docRedirects = map[string]string{
 	"user/admin-guide":              "admin/admin-guide",
 	"user/admin-library-management": "admin/libraries",
+	// developer/testing.md (Feb-era) was deleted 2026-11-02: its
+	// wipe-test-users lifecycle contradicted current doctrine (live
+	// testuser is protected, cleanups are scoped) and its recipes were
+	// superseded by docs/contributing/development.md (architecture,
+	// setup, testing, project rules — kept fresh).
+	"developer/testing": "contributing/development",
 }
 
 // NewHTTPHandler creates a new docs HTTP handler