Docstrings

Author: reduan-azouaghe

exercise.tests/Helpers/UserTestCases.cs

@@ -1,14 +1,23 @@
 namespace exercise.tests.Helpers
 {
+    /// <summary>
+    /// Provides reusable user-centric <see cref="TestCaseData"/> scenarios for integration tests.
+    /// </summary>
     public static class UserTestCases
     {
+        /// <summary>
+        /// Supplies registration payloads that should produce successful responses.
+        /// </summary>
         public static IEnumerable<TestCaseData> ValidRegisterCases()
         {
             yield return new TestCaseData("validuser", "[email protected]", "ValidPass1!");
             yield return new TestCaseData("user-name", "[email protected]", "SecurePass9#");
             yield return new TestCaseData("user1name", "[email protected]", "StrongPass$1");
         }
 
+        /// <summary>
+        /// Supplies registration payloads that should fail validation.
+        /// </summary>
         public static IEnumerable<TestCaseData> InvalidRegisterCases()
         {
             yield return new TestCaseData("validuser", "plainaddress", "ValidPass1!").SetName("Invalid: Invalid email format (register)");
@@ -19,6 +28,9 @@ public static IEnumerable<TestCaseData> InvalidRegisterCases()
             yield return new TestCaseData("validuser", "[email protected]", "NoSpecialChar1").SetName("Invalid: Missing special character (register)");
         }
 
+        /// <summary>
+        /// Supplies credential pairs that represent successful login attempts.
+        /// </summary>
         public static IEnumerable<TestCaseData> ValidLoginCases()
         {
             yield return new TestCaseData("[email protected]", "SuperHash!4");
@@ -27,6 +39,9 @@ public static IEnumerable<TestCaseData> ValidLoginCases()
             //yield return new TestCaseData("[email protected]", "ValidPass1!");
         }
 
+        /// <summary>
+        /// Supplies credential pairs that should fail authentication.
+        /// </summary>
         public static IEnumerable<TestCaseData> InvalidLoginCases()
         {
             yield return new TestCaseData("[email protected]", "short1!").SetName("Invalid: Password too short (login)");
@@ -37,4 +52,4 @@ public static IEnumerable<TestCaseData> InvalidLoginCases()
             yield return new TestCaseData("[email protected]", "ValidPass1!").SetName("Invalid: Invalid email domain (login)");
         }
     }
-}
+}

exercise.tests/Helpers/UsernameValidationCases.cs

@@ -2,8 +2,14 @@
 
 namespace exercise.tests.Helpers
 {
+    /// <summary>
+    /// Centralises username validation scenarios for reuse across integration tests.
+    /// </summary>
     public static class UsernameValidationTestData
     {
+        /// <summary>
+        /// Yields username samples alongside the expected message outcome for each endpoint.
+        /// </summary>
         public static IEnumerable<TestCaseData> UsernameValidationMessageCases()
         {
             string[] endpoints = new string[]
@@ -53,6 +59,9 @@ public static IEnumerable<TestCaseData> UsernameValidationMessageCases()
             }
 
         }
+        /// <summary>
+        /// Yields username samples alongside the expected status code for each endpoint.
+        /// </summary>
         public static IEnumerable<TestCaseData> UsernameValidationStatusCases()
         {
             string[] endpoints = new string[]

exercise.tests/IntegrationTests/EndpointStatusTest.cs

@@ -6,6 +6,9 @@
 
 namespace exercise.tests.IntegrationTests
 {
+    /// <summary>
+    /// Integration smoke tests that ensure unexpected endpoints return consistent error responses.
+    /// </summary>
     [TestFixture]
     public class EndpointStatusTest
     {
@@ -27,6 +30,9 @@ public void TearDown()
             _factory.Dispose();
         }
 
+        /// <summary>
+        /// Verifies POST requests to unknown routes return a 404 with the canonical payload.
+        /// </summary>
         [Test]
         public async Task PostCheckInvalidEndpoint()
         {
@@ -57,6 +63,9 @@ public async Task PostCheckInvalidEndpoint()
             Assert.That(message?["message"]?.GetValue<string>(), Is.EqualTo("Endpoint not found"));
         }
 
+        /// <summary>
+        /// Verifies GET requests to unknown routes return a 404 with the canonical payload.
+        /// </summary>
         [Test]
         public async Task GetCheckInvalidEndpoint()
         {

exercise.tests/IntegrationTests/PostTests.cs

@@ -7,6 +7,9 @@
 
 namespace exercise.tests.IntegrationTests
 {
+    /// <summary>
+    /// Integration tests covering the lifecycle of posts via the public API endpoints.
+    /// </summary>
     [TestFixture]
     public class PostTests
     {
@@ -28,6 +31,9 @@ public void TearDown()
             _factory.Dispose();
         }
 
+        /// <summary>
+        /// Ensures GET /posts returns a successful response and the expected payload structure.
+        /// </summary>
         [Test]
         public async Task GetAllPosts()
         {
@@ -77,6 +83,9 @@ public async Task GetAllPosts()
             }
         }
 
+        /// <summary>
+        /// Confirms creating a post with valid data yields an HTTP 201 Created status.
+        /// </summary>
         [Test]
         public async Task SuccessfulCreatePostStatus()
         {
@@ -106,6 +115,9 @@ public async Task SuccessfulCreatePostStatus()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.Created));
         }
 
+        /// <summary>
+        /// Validates the create post response body mirrors the request payload and contracts.
+        /// </summary>
         [Test]
         public async Task SuccessfulCreatePostMessage()
         {
@@ -156,6 +168,12 @@ public async Task SuccessfulCreatePostMessage()
             Assert.That(data["createdAt"], Is.Not.Null);
         }
 
+        /// <summary>
+        /// Checks that invalid create post requests surface the correct HTTP status codes.
+        /// </summary>
+        /// <param name="userid">The author identifier to include in the payload.</param>
+        /// <param name="content">The post body content being validated.</param>
+        /// <param name="expected">The status code the API should return.</param>
         [TestCase(9999999, "somecontent", HttpStatusCode.NotFound)]
         [TestCase(5, "", HttpStatusCode.BadRequest)]
         [TestCase(5, "      ", HttpStatusCode.BadRequest)]
@@ -186,6 +204,12 @@ public async Task FailedlCreatePostStatus(int userid, string content, HttpStatus
             Assert.That(response.StatusCode, Is.EqualTo(expected));
         }
 
+        /// <summary>
+        /// Ensures the validation error message matches expectations for rejected create post attempts.
+        /// </summary>
+        /// <param name="userid">The author identifier placed in the request.</param>
+        /// <param name="content">The invalid content variation under test.</param>
+        /// <param name="expectedmessage">The message the API should return.</param>
         [TestCase(9999999, "somecontent", "Invalid userID")]
         [TestCase(5, "", "Content cannot be empty")]
         [TestCase(5, "      ", "Content cannot be empty")]
@@ -219,6 +243,9 @@ public async Task FailedCreatePostMessage(int userid, string content, string exp
             Assert.That(message["data"], Is.Null);
             Assert.That(message["timestamp"], Is.Not.Null);
         }
+        /// <summary>
+        /// Validates that deleting an existing post succeeds and a second deletion reports not found.
+        /// </summary>
         [Test]
         public async Task DeletePostById_SuccessAndNotFound()
         {
@@ -257,6 +284,12 @@ public async Task DeletePostById_SuccessAndNotFound()
 
 
 
+        /// <summary>
+        /// Exercises the PATCH /posts/{id} endpoint across happy path and error scenarios.
+        /// </summary>
+        /// <param name="postId">The identifier of the post to update.</param>
+        /// <param name="newContent">The updated content supplied.</param>
+        /// <param name="expected">The anticipated HTTP status code.</param>
         [TestCase(5, "Updated content", HttpStatusCode.OK)]
         [TestCase(9999999, "Updated content", HttpStatusCode.NotFound)]
         [TestCase(5, "", HttpStatusCode.BadRequest)]

exercise.tests/IntegrationTests/UserTests.cs

@@ -9,6 +9,9 @@
 
 namespace exercise.tests.IntegrationTests
 {
+    /// <summary>
+    /// Integration tests exercising the user management endpoints end-to-end via the API surface.
+    /// </summary>
     [TestFixture]
     public class UserTests
     {
@@ -30,7 +33,13 @@ public void TearDown()
             _factory.Dispose();
         }
 
-        // ad test cases for approved usernames, emails
+        /// <summary>
+        /// Confirms that valid registration payloads yield an HTTP 201 Created response.
+        /// </summary>
+        /// <remarks>Test cases come from <see cref="UserTestCases.ValidRegisterCases"/> and are uniquified at runtime to avoid clashes.</remarks>
+        /// <param name="username">The base username supplied by the data source.</param>
+        /// <param name="email">The base email supplied by the data source.</param>
+        /// <param name="password">The password candidate to register with.</param>
         [Test, TestCaseSource(typeof(UserTestCases), nameof(UserTestCases.ValidRegisterCases))]
         public async Task Register_success(string username, string email, string password)
         {
@@ -62,6 +71,13 @@ public async Task Register_success(string username, string email, string passwor
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.Created));
         }
 
+        /// <summary>
+        /// Verifies the registration endpoint rejects malformed payloads with non-Created responses.
+        /// </summary>
+        /// <remarks>Inputs are provided by <see cref="UserTestCases.InvalidRegisterCases"/>.</remarks>
+        /// <param name="username">The attempted username for registration.</param>
+        /// <param name="email">The attempted email for registration.</param>
+        /// <param name="password">The password candidate under test.</param>
         [Test, TestCaseSource(typeof(UserTestCases), nameof(UserTestCases.InvalidRegisterCases))]
         public async Task Register_Failure(string username, string email, string password)
         {
@@ -96,6 +112,12 @@ public async Task Register_Failure(string username, string email, string passwor
         }
 
 
+        /// <summary>
+        /// Ensures valid credentials receive an HTTP 200 response and a token payload.
+        /// </summary>
+        /// <remarks>Credentials are sourced from <see cref="UserTestCases.ValidLoginCases"/>.</remarks>
+        /// <param name="email">The email address to authenticate with.</param>
+        /// <param name="password">The password paired with the supplied email.</param>
         [Test, TestCaseSource(typeof(UserTestCases), nameof(UserTestCases.ValidLoginCases))]
         public async Task Login_success(string email, string password)
         {
@@ -127,6 +149,12 @@ public async Task Login_success(string email, string password)
             Assert.That(message["data"]["token"], Is.Not.Null);
         }
 
+        /// <summary>
+        /// Asserts that invalid login attempts fail with the expected HTTP status and message.
+        /// </summary>
+        /// <remarks>Negative credential combinations come from <see cref="UserTestCases.InvalidLoginCases"/>.</remarks>
+        /// <param name="email">The incorrect email supplied to the login endpoint.</param>
+        /// <param name="password">The incorrect password paired with the email.</param>
         [Test, TestCaseSource(typeof(UserTestCases), nameof(UserTestCases.InvalidLoginCases))]
         public async Task Login_failure(string email, string password)
         {
@@ -161,6 +189,9 @@ public async Task Login_failure(string email, string password)
 
         }
 
+        /// <summary>
+        /// Validates that a PATCH with complete, valid fields updates an existing user successfully.
+        /// </summary>
         [Test]
         public async Task UpdateUserSuccess()
         {
@@ -181,6 +212,9 @@ public async Task UpdateUserSuccess()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
         }
 
+        /// <summary>
+        /// Ensures PATCH requests with no mutable fields return a bad request response.
+        /// </summary>
         [Test]
         public async Task UpdateUserNullFieldsOnly()
         {
@@ -195,6 +229,9 @@ public async Task UpdateUserNullFieldsOnly()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Confirms the API rejects usernames that violate allowed formatting rules.
+        /// </summary>
         [Test]
         public async Task UpdateUserInvalidUsername()
         {
@@ -212,6 +249,9 @@ public async Task UpdateUserInvalidUsername()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Confirms GitHub username updates honor the same validation rules as the standalone validator.
+        /// </summary>
         [Test]
         public async Task UpdateUserInvalidGitHubUsername()
         {
@@ -229,6 +269,9 @@ public async Task UpdateUserInvalidGitHubUsername()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Verifies email updates are blocked when the address fails format validation.
+        /// </summary>
         [Test]
         public async Task UpdateUserInvalidEmail()
         {
@@ -246,6 +289,9 @@ public async Task UpdateUserInvalidEmail()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Confirms passwords that do not meet the complexity requirements are rejected on update.
+        /// </summary>
         [Test]
         public async Task UpdateUserInvalidPassword()
         {
@@ -263,6 +309,9 @@ public async Task UpdateUserInvalidPassword()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Ensures role updates outside the defined enum range produce a bad request.
+        /// </summary>
         [Test]
         public async Task UpdateUserInvalidRole()
         {
@@ -280,6 +329,9 @@ public async Task UpdateUserInvalidRole()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Verifies the API prevents changing a username to one that is already in use.
+        /// </summary>
         [Test]
         public async Task UpdateUserUsernameExists()
         {
@@ -297,6 +349,9 @@ public async Task UpdateUserUsernameExists()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Verifies the API prevents reusing an existing GitHub username value.
+        /// </summary>
         [Test]
         public async Task UpdateUserGitHubUsernameExists()
         {
@@ -314,6 +369,9 @@ public async Task UpdateUserGitHubUsernameExists()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Verifies the API prevents reusing an existing email address value.
+        /// </summary>
         [Test]
         public async Task UpdateUserEmailExists()
         {
@@ -331,6 +389,11 @@ public async Task UpdateUserEmailExists()
             Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.BadRequest));
         }
 
+        /// <summary>
+        /// Ensures retrieving users by id returns 200 for known users and 404 for missing ones.
+        /// </summary>
+        /// <param name="id">The user id sent to the endpoint.</param>
+        /// <param name="responseStatus">The expected HTTP status code.</param>
         [TestCase("1", HttpStatusCode.OK)]
         [TestCase("10000000", HttpStatusCode.NotFound)]
         public async Task GetUserByIdTest(string id, HttpStatusCode responseStatus)