Test docstrings

backend/handlers/auth/auth_test.go

@@ -92,7 +92,10 @@ func parseResponseBody(w *httptest.ResponseRecorder, dest interface{}) error {
 // Register Handler Tests
 // =============================================================================
 
-func TestRegister_Success(t *testing.T) {
+// TestRegister_Success verifies that a new user can successfully register with
+// valid credentials. It tests the happy path: valid name, email, password,
+// UK phone number, date of birth, and policy agreement. The test confirms
+// the user is created in the database with status 201.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -126,7 +129,9 @@ func TestRegister_Success(t *testing.T) {
 	db.DB.Exec(context.Background(), "DELETE FROM users WHERE id = $1", userID)
 }
 
-func TestRegister_InvalidInput_MissingFields(t *testing.T) {
+// TestRegister_InvalidInput_MissingFields tests that registration fails with
+// HTTP 400 when required fields are missing. It covers missing firstName,
+// lastName, email, phone, dateOfBirth, and when policy agreement is not given.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -172,7 +177,8 @@ func TestRegister_InvalidInput_MissingFields(t *testing.T) {
 	}
 }
 
-func TestRegister_InvalidInput_InvalidEmail(t *testing.T) {
+// TestRegister_InvalidInput_InvalidEmail verifies that registration fails
+// with HTTP 400 when an invalid email format is provided (e.g., "not-an-email").
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -195,7 +201,8 @@ func TestRegister_InvalidInput_InvalidEmail(t *testing.T) {
 	}
 }
 
-func TestRegister_InvalidInput_InvalidPhone(t *testing.T) {
+// TestRegister_InvalidInput_InvalidPhone tests that registration fails
+// with HTTP 400 when an invalid UK phone number is provided (e.g., too short).
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -219,7 +226,8 @@ func TestRegister_InvalidInput_InvalidPhone(t *testing.T) {
 }
 
 // TestRegister_ValidUKPhoneNumbers tests all valid UK mobile phone formats
-func TestRegister_ValidUKPhoneNumbers(t *testing.T) {
+// TestRegister_ValidUKPhoneNumbers verifies that registration accepts all
+// valid UK mobile phone formats including 07x numbers and E.164 format (+447...).
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -263,7 +271,9 @@ func TestRegister_ValidUKPhoneNumbers(t *testing.T) {
 }
 
 // TestRegister_InvalidPhoneNumbers tests various invalid phone formats
-func TestRegister_InvalidPhoneNumbers(t *testing.T) {
+// TestRegister_InvalidPhoneNumbers verifies that registration rejects
+// invalid phone numbers including too short, invalid formats, US numbers, and
+// numbers with special characters.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -303,7 +313,8 @@ func TestRegister_InvalidPhoneNumbers(t *testing.T) {
 	}
 }
 
-func TestRegister_InvalidInput_Under16(t *testing.T) {
+// TestRegister_InvalidInput_Under16 tests that users under 16 years old cannot
+// register. The system enforces a minimum age of 16 for account creation.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -329,7 +340,8 @@ func TestRegister_InvalidInput_Under16(t *testing.T) {
 	}
 }
 
-func TestRegister_DuplicateEmail(t *testing.T) {
+// TestRegister_DuplicateEmail verifies that attempting to register with
+// an email that already exists returns HTTP 409 Conflict.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -366,7 +378,8 @@ func TestRegister_DuplicateEmail(t *testing.T) {
 // Login Handler Tests
 // =============================================================================
 
-func TestLogin_Success(t *testing.T) {
+// TestLogin_Success tests that an existing user can successfully log in
+// with correct email and password, receiving a JWT token in the response.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -402,7 +415,8 @@ func TestLogin_Success(t *testing.T) {
 	}
 }
 
-func TestLogin_InvalidCredentials_WrongPassword(t *testing.T) {
+// TestLogin_InvalidCredentials_WrongPassword verifies that login fails with
+// HTTP 401 when the correct email exists but the password is incorrect.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -427,7 +441,8 @@ func TestLogin_InvalidCredentials_WrongPassword(t *testing.T) {
 	}
 }
 
-func TestLogin_InvalidCredentials_NonExistentEmail(t *testing.T) {
+// TestLogin_InvalidCredentials_NonExistentEmail verifies that login fails
+// with HTTP 401 when the email does not exist in the database.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -449,7 +464,8 @@ func TestLogin_InvalidCredentials_NonExistentEmail(t *testing.T) {
 // Refresh Token Handler Tests
 // =============================================================================
 
-func TestRefreshToken_Success(t *testing.T) {
+// TestRefreshToken_Success tests that a valid JWT token can be refreshed
+// to obtain a new token with extended expiry.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -493,7 +509,8 @@ func TestRefreshToken_Success(t *testing.T) {
 	}
 }
 
-func TestRefreshToken_Unauthorized_NoToken(t *testing.T) {
+// TestRefreshToken_Unauthorized_NoToken verifies that attempting to refresh
+// a token without providing one results in HTTP 401 Unauthorized.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -515,7 +532,9 @@ func TestRefreshToken_Unauthorized_NoToken(t *testing.T) {
 // Verify Generate Handler Tests
 // =============================================================================
 
-func TestVerifyGenerate_ValidEmail(t *testing.T) {
+// TestVerifyGenerate_ValidEmail tests that a verification code can be
+// generated for an existing user email. The code is stored in the database
+// for subsequent verification.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -559,7 +578,9 @@ func TestVerifyGenerate_ValidEmail(t *testing.T) {
 	db.DB.Exec(context.Background(), "DELETE FROM verification_codes WHERE user_id = $1", userID)
 }
 
-func TestVerifyGenerate_NonExistentEmail(t *testing.T) {
+// TestVerifyGenerate_NonExistentEmail verifies that the verification code
+// generation endpoint returns HTTP 200 even for non-existent emails. This is
+// a security measure to prevent email enumeration attacks.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -591,7 +612,9 @@ func TestVerifyGenerate_NonExistentEmail(t *testing.T) {
 // Verify Check Handler Tests
 // =============================================================================
 
-func TestVerifyCheck_ValidCode(t *testing.T) {
+// TestVerifyCheck_ValidCode tests that a valid, non-expired, unused
+// verification code successfully verifies a user's email and updates their
+// account role from unverified_email to verified_email.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -643,7 +666,8 @@ func TestVerifyCheck_ValidCode(t *testing.T) {
 	}
 }
 
-func TestVerifyCheck_InvalidCode(t *testing.T) {
+// TestVerifyCheck_InvalidCode verifies that attempting to verify with
+// a non-existent code returns HTTP 400 Bad Request.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -660,7 +684,8 @@ func TestVerifyCheck_InvalidCode(t *testing.T) {
 	}
 }
 
-func TestVerifyCheck_ExpiredCode(t *testing.T) {
+// TestVerifyCheck_ExpiredCode tests that verification fails with HTTP 400
+// when the code has expired (past its expires_at timestamp).
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -699,7 +724,8 @@ func TestVerifyCheck_ExpiredCode(t *testing.T) {
 // Additional Edge Case Tests
 // =============================================================================
 
-func TestLogin_InvalidRequest(t *testing.T) {
+// TestLogin_InvalidRequest verifies that sending malformed JSON to the login
+// endpoint returns HTTP 400 Bad Request.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -716,7 +742,8 @@ func TestLogin_InvalidRequest(t *testing.T) {
 	}
 }
 
-func TestRegister_NameTooLong(t *testing.T) {
+// TestRegister_NameTooLong tests that registration fails when the first name
+// exceeds 50 characters (the maximum allowed length).
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -741,7 +768,8 @@ func TestRegister_NameTooLong(t *testing.T) {
 	}
 }
 
-func TestRegister_InvalidNameCharacters(t *testing.T) {
+// TestRegister_InvalidNameCharacters verifies that registration fails when
+// names contain invalid characters (e.g., numbers).
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -765,7 +793,8 @@ func TestRegister_InvalidNameCharacters(t *testing.T) {
 	}
 }
 
-func TestVerifyCheck_AlreadyUsed(t *testing.T) {
+// TestVerifyCheck_AlreadyUsed tests that attempting to verify with a code
+// that has already been used returns HTTP 403 Forbidden.
 	cleanup := setupTestDB(t)
 	defer cleanup()
 
@@ -805,7 +834,9 @@ func TestVerifyCheck_AlreadyUsed(t *testing.T) {
 	}
 }
 
-func TestVerifyCheck_RoleChangeToVerified(t *testing.T) {
+// TestVerifyCheck_RoleChangeToVerified confirms that after a successful
+// verification, the user's account_role changes from unverified_email to
+// verified_email, granting them full account access.
 	cleanup := setupTestDB(t)
 	defer cleanup()