@chidchanun/bcp 0.2.12 → 0.2.14

package/packages/server/src/testing-page.ts

@@ -0,0 +1,274 @@
+import {
+    executePageActionFunction,
+    normalizePageActionMethod,
+    type PageAction,
+    type PageActionExecution,
+    type PageActionMethod,
+} from "./form-action.js";
+import {
+    executePageGuardFunctions,
+    type PageGuard,
+    type PageGuardData,
+    type PageGuardDefinition,
+    type PageGuardExecution,
+} from "./page-guard.js";
+import {
+    executePageLoaderFunction,
+    type PageLoader,
+    type PageLoaderExecution,
+} from "./page-loader.js";
+
+export interface TestPageContextOptions {
+    params?: Record<string, any>;
+    url?: string | URL;
+    guardData?: PageGuardData;
+    hasGuard?: boolean;
+}
+
+export interface TestPageGuardOptions
+extends Omit<
+    TestPageContextOptions,
+    "guardData" | "hasGuard"
+> {
+    label?: string;
+}
+
+export interface TestPageActionOptions
+extends TestPageContextOptions {
+    actionName?: string;
+    method?: PageActionMethod | string;
+    formData?: FormData;
+    fields?: Record<
+        string,
+        string | Blob | Array<string | Blob>
+    >;
+    label?: string;
+}
+
+export async function runTestPageLoader(
+    loader: PageLoader,
+    options: TestPageContextOptions = {}
+): Promise<PageLoaderExecution> {
+    assertFunction(
+        loader,
+        "page loader"
+    );
+
+    return executePageLoaderFunction(
+        loader,
+        {
+            ...(options.params ?? {}),
+        },
+        resolveTestPageUrl(
+            options.url
+        ),
+        "bcp/testing loader",
+        {
+            ...(options.guardData ?? {}),
+        },
+        options.hasGuard ??
+            Object.keys(
+                options.guardData ?? {}
+            ).length > 0
+    );
+}
+
+export async function runTestPageGuards(
+    guards:
+        | PageGuard
+        | PageGuard[]
+        | PageGuardDefinition[],
+    options: TestPageGuardOptions = {}
+): Promise<PageGuardExecution> {
+    const list =
+        Array.isArray(guards)
+            ? guards
+            : [guards];
+    const definitions:
+        PageGuardDefinition[] =
+        list.map(
+            (candidate, index) => {
+                if (
+                    typeof candidate === "object" &&
+                    candidate !== null &&
+                    "guard" in candidate
+                ) {
+                    const definition =
+                        candidate as PageGuardDefinition;
+                    assertFunction(
+                        definition.guard,
+                        `page guard ${index + 1}`
+                    );
+                    return {
+                        filePath:
+                            definition.filePath ||
+                            `${options.label ?? "bcp/testing guard"}#${index + 1}`,
+                        guard:
+                            definition.guard,
+                    };
+                }
+
+                assertFunction(
+                    candidate,
+                    `page guard ${index + 1}`
+                );
+
+                return {
+                    filePath:
+                        `${options.label ?? "bcp/testing guard"}#${index + 1}`,
+                    guard:
+                        candidate as PageGuard,
+                };
+            }
+        );
+
+    return executePageGuardFunctions(
+        definitions,
+        {
+            ...(options.params ?? {}),
+        },
+        resolveTestPageUrl(
+            options.url
+        )
+    );
+}
+
+export async function runTestPageAction(
+    action: PageAction,
+    options: TestPageActionOptions = {}
+): Promise<PageActionExecution> {
+    assertFunction(
+        action,
+        "page action"
+    );
+
+    if (
+        options.formData &&
+        options.fields
+    ) {
+        throw new TypeError(
+            "BCP Testing: page action test cannot specify both formData and fields."
+        );
+    }
+
+    const actionName =
+        normalizeText(
+            options.actionName ?? "action",
+            "page action name"
+        );
+    const method =
+        normalizePageActionMethod(
+            options.method ?? "POST"
+        );
+    const formData =
+        options.formData ??
+        createTestFormData(
+            options.fields ?? {}
+        );
+
+    return executePageActionFunction(
+        action,
+        actionName,
+        method,
+        formData,
+        {
+            ...(options.params ?? {}),
+        },
+        resolveTestPageUrl(
+            options.url
+        ),
+        {
+            ...(options.guardData ?? {}),
+        },
+        options.hasGuard ??
+            Object.keys(
+                options.guardData ?? {}
+            ).length > 0,
+        options.label ??
+            "bcp/testing actions"
+    );
+}
+
+export function createTestFormData(
+    fields: Record<
+        string,
+        string | Blob | Array<string | Blob>
+    > = {}
+): FormData {
+    const formData =
+        new FormData();
+
+    for (
+        const [name, rawValue]
+        of Object.entries(fields)
+    ) {
+        const values =
+            Array.isArray(rawValue)
+                ? rawValue
+                : [rawValue];
+
+        for (const value of values) {
+            formData.append(
+                name,
+                value
+            );
+        }
+    }
+
+    return formData;
+}
+
+function resolveTestPageUrl(
+    value?: string | URL
+): URL {
+    if (value instanceof URL) {
+        return new URL(
+            value.href
+        );
+    }
+
+    const candidate =
+        value ??
+        "http://bcp.test/";
+
+    try {
+        return new URL(
+            candidate
+        );
+    } catch {
+        return new URL(
+            String(candidate).replace(
+                /^\//,
+                ""
+            ),
+            "http://bcp.test/"
+        );
+    }
+}
+
+function assertFunction(
+    value: unknown,
+    label: string
+): asserts value is (...args: any[]) => unknown {
+    if (typeof value !== "function") {
+        throw new TypeError(
+            `BCP Testing: ${label} must be a function.`
+        );
+    }
+}
+
+function normalizeText(
+    value: unknown,
+    label: string
+): string {
+    const text =
+        String(value ?? "").trim();
+
+    if (!text) {
+        throw new TypeError(
+            `BCP Testing: ${label} must be a non-empty string.`
+        );
+    }
+
+    return text;
+}