@nestia/e2e 7.0.0 → 7.0.1

package/src/TestValidator.ts

@@ -2,18 +2,57 @@ import { RandomGenerator } from "./RandomGenerator";
 import { json_equal_to } from "./internal/json_equal_to";
 
 /**
- * Test validator.
+ * A comprehensive collection of E2E validation utilities for testing
+ * applications.
  *
- * `TestValidator` is a collection gathering E2E validation functions.
+ * TestValidator provides type-safe validation functions for common testing
+ * scenarios including condition checking, equality validation, error testing,
+ * HTTP error validation, pagination testing, search functionality validation,
+ * and sorting validation.
+ *
+ * All functions follow a currying pattern to enable reusable test
+ * configurations and provide detailed error messages for debugging failed
+ * assertions.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   // Basic condition testing
+ *   TestValidator.predicate("user should be authenticated")(user.isAuthenticated);
+ *
+ *   // Equality validation
+ *   TestValidator.equals("API response should match expected")(expected)(actual);
+ *
+ *   // Error validation
+ *   TestValidator.error("should throw on invalid input")(() => validateInput(""));
+ *   ```;
  */
 export namespace TestValidator {
   /**
-   * Test whether condition is satisfied.
+   * Validates that a given condition evaluates to true.
+   *
+   * Supports synchronous boolean values, synchronous functions returning
+   * boolean, and asynchronous functions returning Promise<boolean>. The return
+   * type is automatically inferred based on the input type.
+   *
+   * @example
+   *   ```typescript
+   *   // Synchronous boolean
+   *   TestValidator.predicate("user should exist")(user !== null);
    *
-   * @param title Title of error message when condition is not satisfied
-   * @return Currying function
+   *   // Synchronous function
+   *   TestValidator.predicate("array should be empty")(() => arr.length === 0);
+   *
+   *   // Asynchronous function
+   *   await TestValidator.predicate("database should be connected")(
+   *     async () => await db.ping()
+   *   );
+   *   ```;
+   *
+   * @param title - Descriptive title used in error messages when validation
+   *   fails
+   * @returns A currying function that accepts the condition to validate
+   * @throws Error with descriptive message when condition is not satisfied
    */
   export const predicate =
     (title: string) =>
@@ -48,16 +87,33 @@ export namespace TestValidator {
     };
 
   /**
-   * Test whether two values are equal.
+   * Validates deep equality between two values using JSON comparison.
+   *
+   * Performs recursive comparison of objects and arrays. Supports an optional
+   * exception filter to ignore specific keys during comparison. Useful for
+   * validating API responses, data transformations, and object state changes.
+   *
+   * @example
+   *   ```typescript
+   *   // Basic equality
+   *   TestValidator.equals("response should match expected")(expectedUser)(actualUser);
    *
-   * If you want to validate `covers` relationship,
-   * call smaller first and then larger.
+   *   // Ignore timestamps in comparison
+   *   TestValidator.equals("user data should match", (key) => key === "updatedAt")(
+   *     expectedUser
+   *   )(actualUser);
    *
-   * Otherwise you wanna non equals validator, combine with {@link error}.
+   *   // Validate API response structure
+   *   const validateResponse = TestValidator.equals("API response structure");
+   *   validateResponse({ id: 1, name: "John" })({ id: 1, name: "John" });
+   *   ```;
    *
-   * @param title Title of error message when different
-   * @param exception Exception filter for ignoring some keys
-   * @returns Currying function
+   * @param title - Descriptive title used in error messages when values differ
+   * @param exception - Optional filter function to exclude specific keys from
+   *   comparison
+   * @returns A currying function chain: first accepts expected value, then
+   *   actual value
+   * @throws Error with detailed diff information when values are not equal
    */
   export const equals =
     (title: string, exception: (key: string) => boolean = () => false) =>
@@ -75,13 +131,34 @@ export namespace TestValidator {
     };
 
   /**
-   * Test whether error occurs.
+   * Validates that a function throws an error or rejects when executed.
    *
-   * If error occurs, nothing would be happened.
+   * Expects the provided function to fail. If the function executes
+   * successfully without throwing an error or rejecting, this validator will
+   * throw an exception. Supports both synchronous and asynchronous functions.
    *
-   * However, no error exists, then exception would be thrown.
+   * @example
+   *   ```typescript
+   *   // Synchronous error validation
+   *   TestValidator.error("should reject invalid email")(
+   *     () => validateEmail("invalid-email")
+   *   );
    *
-   * @param title Title of exception because of no error exists
+   *   // Asynchronous error validation
+   *   await TestValidator.error("should reject unauthorized access")(
+   *     async () => await api.functional.getSecretData()
+   *   );
+   *
+   *   // Validate input validation
+   *   TestValidator.error("should throw on empty string")(
+   *     () => processRequiredInput("")
+   *   );
+   *   ```;
+   *
+   * @param title - Descriptive title used in error messages when no error
+   *   occurs
+   * @returns A currying function that accepts the task function to validate
+   * @throws Error when the task function does not throw an error or reject
    */
   export const error =
     (title: string) =>
@@ -99,6 +176,37 @@ export namespace TestValidator {
       }
     };
 
+  /**
+   * Validates that a function throws an HTTP error with specific status codes.
+   *
+   * Specialized error validator for HTTP operations. Validates that the
+   * function throws an HttpError with one of the specified status codes. Useful
+   * for testing API endpoints, authentication, and authorization logic.
+   *
+   * @example
+   *   ```typescript
+   *   // Validate 401 Unauthorized
+   *   await TestValidator.httpError("should return 401 for invalid token")(401)(
+   *     async () => await api.functional.getProtectedResource("invalid-token")
+   *   );
+   *
+   *   // Validate multiple possible error codes
+   *   await TestValidator.httpError("should return client error")(400, 404, 422)(
+   *     async () => await api.functional.updateNonexistentResource(data)
+   *   );
+   *
+   *   // Validate server errors
+   *   TestValidator.httpError("should handle server errors")(500, 502, 503)(
+   *     () => callFaultyEndpoint()
+   *   );
+   *   ```;
+   *
+   * @param title - Descriptive title used in error messages
+   * @returns A currying function that accepts status codes, then the task
+   *   function
+   * @throws Error when function doesn't throw HttpError or status code doesn't
+   *   match
+   */
   export const httpError =
     (title: string) =>
     (...statuses: number[]) =>
@@ -143,6 +251,37 @@ export namespace TestValidator {
       }
     };
 
+  /**
+   * Safely executes a function and captures any errors without throwing.
+   *
+   * Utility function for error handling in tests. Executes the provided
+   * function and returns any error that occurs, or null if successful. Supports
+   * both synchronous and asynchronous functions. Useful for testing error
+   * conditions without stopping test execution.
+   *
+   * @example
+   *   ```typescript
+   *   // Synchronous error capture
+   *   const error = TestValidator.proceed(() => {
+   *     throw new Error("Something went wrong");
+   *   });
+   *   console.log(error?.message); // "Something went wrong"
+   *
+   *   // Asynchronous error capture
+   *   const asyncError = await TestValidator.proceed(async () => {
+   *     await failingAsyncOperation();
+   *   });
+   *
+   *   // Success case
+   *   const noError = TestValidator.proceed(() => {
+   *     return "success";
+   *   });
+   *   console.log(noError); // null
+   *   ```;
+   *
+   * @param task - Function to execute safely
+   * @returns Error object if function throws/rejects, null if successful
+   */
   export function proceed(task: () => Promise<any>): Promise<Error | null>;
   export function proceed(task: () => any): Error | null;
   export function proceed(
@@ -163,16 +302,36 @@ export namespace TestValidator {
   }
 
   /**
-   * Validate index API.
+   * Validates pagination index API results against expected entity order.
    *
-   * Test whether two indexed values are equal.
+   * Compares the order of entities returned by a pagination API with manually
+   * sorted expected results. Validates that entity IDs appear in the correct
+   * sequence. Commonly used for testing database queries, search results, and
+   * any paginated data APIs.
    *
-   * If two values are different, then exception would be thrown.
+   * @example
+   *   ```typescript
+   *   // Test article pagination
+   *   const expectedArticles = await db.articles.findAll({ order: 'created_at DESC' });
+   *   const actualArticles = await api.functional.getArticles({ page: 1, limit: 10 });
    *
-   * @param title Title of error message when different
-   * @return Currying function
+   *   TestValidator.index("article pagination order")(expectedArticles)(
+   *     actualArticles,
+   *     true // enable trace logging
+   *   );
    *
-   * @example https://github.com/samchon/nestia-template/blob/master/src/test/features/api/bbs/test_api_bbs_article_index_search.ts
+   *   // Test user search results
+   *   const manuallyFilteredUsers = allUsers.filter(u => u.name.includes("John"));
+   *   const apiSearchResults = await api.functional.searchUsers({ query: "John" });
+   *
+   *   TestValidator.index("user search results")(manuallyFilteredUsers)(
+   *     apiSearchResults
+   *   );
+   *   ```;
+   *
+   * @param title - Descriptive title used in error messages when order differs
+   * @returns A currying function chain: expected entities, then actual entities
+   * @throws Error when entity order differs between expected and actual results
    */
   export const index =
     (title: string) =>
@@ -203,31 +362,53 @@ export namespace TestValidator {
     };
 
   /**
-   * Valiate search options.
+   * Validates search functionality by testing API results against manual
+   * filtering.
+   *
+   * Comprehensive search validation that samples entities from a complete
+   * dataset, extracts search values, applies manual filtering, calls the search
+   * API, and compares results. Validates that search APIs return the correct
+   * subset of data matching the search criteria.
+   *
+   * @example
+   *   ```typescript
+   *   // Test article search functionality
+   *   const allArticles = await db.articles.findAll();
+   *   const searchValidator = TestValidator.search("article search API")(
+   *     (req) => api.searchArticles(req)
+   *   )(allArticles, 5); // test with 5 random samples
    *
-   * Test a pagination API supporting search options.
+   *   await searchValidator({
+   *     fields: ["title", "content"],
+   *     values: (article) => [article.title.split(" ")[0]], // first word
+   *     filter: (article, [keyword]) =>
+   *       article.title.includes(keyword) || article.content.includes(keyword),
+   *     request: ([keyword]) => ({ q: keyword })
+   *   });
    *
-   * @param title Title of error message when searching is invalid
-   * @returns Currying function
+   *   // Test user search with multiple criteria
+   *   await TestValidator.search("user search with filters")(
+   *     (req) => api.getUsers(req)
+   *   )(allUsers, 3)({
+   *     fields: ["status", "role"],
+   *     values: (user) => [user.status, user.role],
+   *     filter: (user, [status, role]) =>
+   *       user.status === status && user.role === role,
+   *     request: ([status, role]) => ({ status, role })
+   *   });
+   *   ```;
    *
-   * @example https://github.com/samchon/nestia-template/blob/master/src/test/features/api/bbs/test_api_bbs_article_index_search.ts
+   * @param title - Descriptive title used in error messages when search fails
+   * @returns A currying function chain: API getter function, then dataset and
+   *   sample count
+   * @throws Error when API search results don't match manual filtering results
    */
   export const search =
     (title: string) =>
-    /**
-     * @param getter A pagination API function to be called
-     */
     <Entity extends IEntity<any>, Request>(
       getter: (input: Request) => Promise<Entity[]>,
     ) =>
-    /**
-     * @param total Total entity records for comparison
-     * @param sampleCount Sampling count. Default is 1
-     */
     (total: Entity[], sampleCount: number = 1) =>
-    /**
-     * @param props Search properties
-     */
     async <Values extends any[]>(
       props: ISearchProps<Entity, Values, Request>,
     ): Promise<void> => {
@@ -245,34 +426,94 @@ export namespace TestValidator {
       }
     };
 
+  /**
+   * Configuration interface for search validation functionality.
+   *
+   * Defines the structure needed to validate search operations by specifying
+   * how to extract search values from entities, filter the dataset manually,
+   * and construct API requests.
+   *
+   * @template Entity - Type of entities being searched, must have an ID field
+   * @template Values - Tuple type representing the search values extracted from
+   *   entities
+   * @template Request - Type of the API request object
+   */
   export interface ISearchProps<
     Entity extends IEntity<any>,
     Values extends any[],
     Request,
   > {
+    /** Field names being searched, used in error messages for identification */
     fields: string[];
+
+    /**
+     * Extracts search values from a sample entity
+     *
+     * @param entity - The entity to extract search values from
+     * @returns Tuple of values used for searching
+     */
     values(entity: Entity): Values;
+
+    /**
+     * Manual filter function to determine if an entity matches search criteria
+     *
+     * @param entity - Entity to test against criteria
+     * @param values - Search values to match against
+     * @returns True if entity matches the search criteria
+     */
     filter(entity: Entity, values: Values): boolean;
+
+    /**
+     * Constructs API request object from search values
+     *
+     * @param values - Search values to include in request
+     * @returns Request object for the search API
+     */
     request(values: Values): Request;
   }
 
   /**
-   * Validate sorting options.
+   * Validates sorting functionality of pagination APIs.
+   *
+   * Tests sorting operations by calling the API with sort parameters and
+   * validating that results are correctly ordered. Supports multiple fields,
+   * ascending/descending order, and optional filtering. Provides detailed error
+   * reporting for sorting failures.
    *
-   * Test a pagination API supporting sorting options.
+   * @example
+   *   ```typescript
+   *   // Test single field sorting
+   *   const sortValidator = TestValidator.sort("article sorting")(
+   *     (sortable) => api.getArticles({ sort: sortable })
+   *   )("created_at")(
+   *     (a, b) => new Date(a.created_at).getTime() - new Date(b.created_at).getTime()
+   *   );
    *
-   * You can validate detailed sorting options both ascending and descending orders
-   * with multiple fields. However, as it forms a complicate currying function,
-   * I recommend you to see below example code before using.
+   *   await sortValidator("+"); // ascending
+   *   await sortValidator("-"); // descending
    *
-   * @param title Title of error message when sorting is invalid
-   * @example https://github.com/samchon/nestia-template/blob/master/src/test/features/api/bbs/test_api_bbs_article_index_sort.ts
+   *   // Test multi-field sorting with filtering
+   *   const userSortValidator = TestValidator.sort("user sorting")(
+   *     (sortable) => api.getUsers({ sort: sortable })
+   *   )("status", "created_at")(
+   *     (a, b) => {
+   *       if (a.status !== b.status) return a.status.localeCompare(b.status);
+   *       return new Date(a.created_at).getTime() - new Date(b.created_at).getTime();
+   *     },
+   *     (user) => user.isActive // only test active users
+   *   );
+   *
+   *   await userSortValidator("+", true); // ascending with trace logging
+   *   ```;
+   *
+   * @param title - Descriptive title used in error messages when sorting fails
+   * @returns A currying function chain: API getter, field names, comparator,
+   *   then direction
+   * @throws Error when API results are not properly sorted according to
+   *   specification
    */
   export const sort =
     (title: string) =>
-    /**
-     * @param getter A pagination API function to be called
-     */
     <
       T extends object,
       Fields extends string,
@@ -282,18 +523,8 @@ export namespace TestValidator {
     >(
       getter: (sortable: Sortable) => Promise<T[]>,
     ) =>
-    /**
-     * @param fields List of fields to be sorted
-     */
     (...fields: Fields[]) =>
-    /**
-     * @param comp Comparator function for validation
-     * @param filter Filter function for data if required
-     */
     (comp: (x: T, y: T) => number, filter?: (elem: T) => boolean) =>
-    /**
-     * @param direction "+" means ascending order, and "-" means descending order
-     */
     async (direction: "+" | "-", trace: boolean = false) => {
       let data: T[] = await getter(
         fields.map((field) => `${direction}${field}` as const) as Sortable,
@@ -318,6 +549,22 @@ export namespace TestValidator {
       }
     };
 
+  /**
+   * Type alias for sortable field specifications.
+   *
+   * Represents an array of sort field specifications where each field can be
+   * prefixed with '+' for ascending order or '-' for descending order.
+   *
+   * @example
+   *   ```typescript
+   *   type UserSortable = TestValidator.Sortable<"name" | "email" | "created_at">;
+   *   // Results in: Array<"-name" | "+name" | "-email" | "+email" | "-created_at" | "+created_at">
+   *
+   *   const userSort: UserSortable = ["+name", "-created_at"];
+   *   ```;
+   *
+   * @template Literal - String literal type representing available field names
+   */
   export type Sortable<Literal extends string> = Array<
     `-${Literal}` | `+${Literal}`
   >;