@redrockswebdevelopment/formstack-form-testing 0.1.31 → 0.1.33

package/dist/index.js

@@ -42,7 +42,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: true,
         domAssertion: true,
         reason: "Date API state can be set reliably, but split/calendar renderer variants should be verified through DOM assertions.",
-        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormFieldValueTransaction", "fillDateTime", "readLiveFormDomFieldState"],
+        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormDateTimeValue", "readLiveFormDateTimeState", "fillDateTime"],
     },
     datetime: {
         kind: "datetime",
@@ -51,7 +51,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: true,
         domAssertion: true,
         reason: "Date/time API state can be set, but visible split controls may lag or vary by renderer.",
-        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormFieldValueTransaction", "fillDateTime", "readLiveFormDomFieldState"],
+        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormDateTimeValue", "readLiveFormDateTimeState", "fillDateTime"],
     },
     description: {
         kind: "description",
@@ -87,7 +87,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: true,
         domAssertion: true,
         reason: "File fields must be tested through browser file upload controls, not generic Live Form API setValue payloads.",
-        recommendedHelpers: ["uploadFile", "liveFormFieldRecipes.uploadFileDom", "readLiveFormDomFieldState"],
+        recommendedHelpers: ["uploadLiveFormFile", "readLiveFormFileState", "uploadFile", "liveFormFieldRecipes.uploadFileDom"],
     },
     matrix: {
         kind: "matrix",
@@ -195,8 +195,8 @@ export const liveFormFieldTypeCoverage = {
         apiWrite: false,
         domInteraction: true,
         domAssertion: true,
-        reason: "Signature fields require specialized canvas/user-event automation; the portable helper safely supports clearing and DOM assertions.",
-        recommendedHelpers: ["clearSignature", "liveFormFieldRecipes.clearSignatureDom", "readLiveFormDomFieldState"],
+        reason: "Signature fields require specialized canvas/user-event automation; strict helpers verify hidden signature values or canvas ink after draw/clear.",
+        recommendedHelpers: ["drawLiveFormSignature", "clearLiveFormSignature", "readLiveFormSignatureState", "liveFormFieldRecipes.drawSignatureAndAssertDom"],
     },
     textarea: {
         kind: "textarea",
@@ -5253,6 +5253,210 @@ function productPartLocator(page, internalLabel, part) {
 function productQuantityLocator(page, internalLabel) {
     return page.locator(`${formstackSelectors.fieldByInternalLabel(internalLabel)} input[name$="[quantity]"], ${formstackSelectors.fieldByInternalLabel(internalLabel)} select[name$="[quantity]"]`).first();
 }
+export function normalizeLiveFormFileNames(files) {
+    const values = Array.isArray(files) ? files : [files];
+    return values.map((file) => {
+        const parts = String(file).split(/[\\/]/).filter(Boolean);
+        return parts.length > 0 ? parts[parts.length - 1] ?? String(file) : String(file);
+    });
+}
+function fileInputLocator(page, target) {
+    if (target.internalLabel != null) {
+        return page.locator(formstackSelectors.fieldByInternalLabel(target.internalLabel)).locator("input[type=\"file\"]").first();
+    }
+    if (target.fieldId != null) {
+        return page.locator(formstackSelectors.fieldById(target.fieldId)).locator("input[type=\"file\"]").first();
+    }
+    throw new Error("File upload target requires internalLabel or fieldId.");
+}
+function liveFormSignatureInternalLabel(target) {
+    if (target.internalLabel == null) {
+        throw new Error("Signature target requires internalLabel.");
+    }
+    return target.internalLabel;
+}
+export async function readLiveFormFileState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormFileState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const root = stateOptions.selector != null
+            ? document.querySelector(stateOptions.selector)
+            : stateOptions.internalLabel != null
+                ? document.querySelector(`[data-internal-label="${CSS.escape(stateOptions.internalLabel)}"]`)
+                : stateOptions.fieldId == null
+                    ? null
+                    : document.querySelector(`#fsCell${CSS.escape(String(stateOptions.fieldId))}, #fsFieldCell${CSS.escape(String(stateOptions.fieldId))}, [data-testid="field-${CSS.escape(String(stateOptions.fieldId))}"]`);
+        const controls = root
+            ? Array.from(root.querySelectorAll("input[type=\"file\"]")).map((control) => {
+                const files = Array.from(control.files ?? []).map((file) => file.name);
+                return {
+                    tagName: control.tagName.toLowerCase(),
+                    type: control.getAttribute("type"),
+                    id: control.getAttribute("id"),
+                    name: control.getAttribute("name"),
+                    value: control.getAttribute("value"),
+                    currentValue: control.value,
+                    checked: null,
+                    files,
+                    accept: control.getAttribute("accept"),
+                    multiple: control.multiple,
+                    disabled: control.disabled,
+                    required: control.required,
+                };
+            })
+            : [];
+        const selectedFileNames = controls.flatMap((control) => control.files);
+        const expectedFileNames = [...(stateOptions.expectedFileNames ?? [])];
+        const missingFileNames = expectedFileNames.filter((name) => !selectedFileNames.includes(name));
+        const unexpectedFileNames = selectedFileNames.filter((name) => !expectedFileNames.includes(name));
+        const exact = stateOptions.exact !== false;
+        return {
+            fieldMatched: Boolean(root),
+            controlMatched: controls.length > 0,
+            selectedFileNames,
+            expectedFileNames,
+            missingFileNames,
+            unexpectedFileNames,
+            exact,
+            matched: Boolean(root) &&
+                controls.length > 0 &&
+                missingFileNames.length === 0 &&
+                (expectedFileNames.length === 0 || !exact || unexpectedFileNames.length === 0),
+            controls,
+        };
+    }, options);
+}
+export async function waitForLiveFormFileState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormFileState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormFileState(page, options);
+    }
+    return latest;
+}
+export async function uploadLiveFormFile(page, options) {
+    const fileNames = options.expectedFileNames ?? normalizeLiveFormFileNames(options.files);
+    await fileInputLocator(page, options.target).setInputFiles(options.files);
+    const quiet = options.afterQuiet === false
+        ? undefined
+        : await waitForLiveFormQuiet(page, typeof options.afterQuiet === "object" ? options.afterQuiet : {});
+    const dom = await waitForLiveFormFileState(page, {
+        ...options.target,
+        expectedFileNames: fileNames,
+        ...(options.exact === undefined ? {} : { exact: options.exact }),
+    });
+    const validation = options.afterValidation === undefined
+        ? undefined
+        : await waitForLiveFormValidationState(page, typeof options.afterValidation === "object" ? options.afterValidation : {});
+    return {
+        fileNames,
+        dom,
+        ...(quiet ? { quiet } : {}),
+        ...(validation ? { validation } : {}),
+        ok: dom.matched &&
+            (quiet?.quiet ?? true) &&
+            ((validation?.inlineErrors.length ?? 0) === 0),
+    };
+}
+export async function readLiveFormSignatureState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormSignatureState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const root = stateOptions.selector != null
+            ? document.querySelector(stateOptions.selector)
+            : stateOptions.internalLabel != null
+                ? document.querySelector(`[data-internal-label="${CSS.escape(stateOptions.internalLabel)}"]`)
+                : stateOptions.fieldId == null
+                    ? null
+                    : document.querySelector(`#fsCell${CSS.escape(String(stateOptions.fieldId))}, #fsFieldCell${CSS.escape(String(stateOptions.fieldId))}, [data-testid="field-${CSS.escape(String(stateOptions.fieldId))}"]`);
+        const hiddenValues = root
+            ? Array.from(root.querySelectorAll("input[type=\"hidden\"], textarea"))
+                .map((control) => control.value)
+                .filter((value) => value.trim().length > 0)
+            : [];
+        const canvases = root
+            ? Array.from(root.querySelectorAll("canvas")).map((canvas) => {
+                try {
+                    const context = canvas.getContext("2d", { willReadFrequently: true });
+                    if (!context || canvas.width <= 0 || canvas.height <= 0) {
+                        return {
+                            width: canvas.width,
+                            height: canvas.height,
+                            readable: false,
+                            inkPixelCount: null,
+                            dataUrlLength: null,
+                            error: context ? "empty-canvas" : "missing-2d-context",
+                        };
+                    }
+                    const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data;
+                    let inkPixelCount = 0;
+                    for (let index = 0; index < pixels.length; index += 4) {
+                        const alpha = pixels[index + 3] ?? 0;
+                        const red = pixels[index] ?? 255;
+                        const green = pixels[index + 1] ?? 255;
+                        const blue = pixels[index + 2] ?? 255;
+                        if (alpha > 0 && (red < 245 || green < 245 || blue < 245))
+                            inkPixelCount += 1;
+                    }
+                    let dataUrlLength = null;
+                    try {
+                        dataUrlLength = canvas.toDataURL("image/png").length;
+                    }
+                    catch {
+                        dataUrlLength = null;
+                    }
+                    return {
+                        width: canvas.width,
+                        height: canvas.height,
+                        readable: true,
+                        inkPixelCount,
+                        dataUrlLength,
+                        error: null,
+                    };
+                }
+                catch (error) {
+                    return {
+                        width: canvas.width,
+                        height: canvas.height,
+                        readable: false,
+                        inkPixelCount: null,
+                        dataUrlLength: null,
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                }
+            })
+            : [];
+        const surfaceMatched = Boolean(root?.querySelector(".konvajs-content, canvas"));
+        const canvasMatched = canvases.length > 0;
+        const signed = hiddenValues.length > 0 || canvases.some((canvas) => (canvas.inkPixelCount ?? 0) > 0);
+        return {
+            fieldMatched: Boolean(root),
+            surfaceMatched,
+            canvasMatched,
+            signed,
+            ...(stateOptions.expectSigned === undefined ? {} : { expectSigned: stateOptions.expectSigned }),
+            matched: Boolean(root) && surfaceMatched && (stateOptions.expectSigned === undefined || signed === stateOptions.expectSigned),
+            hiddenValues,
+            canvases,
+        };
+    }, options);
+}
+export async function waitForLiveFormSignatureState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormSignatureState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormSignatureState(page, options);
+    }
+    return latest;
+}
 export async function drawSignature(page, internalLabel, options = {}) {
     if (!page.mouse) {
         throw new Error("drawSignature requires a Playwright page with mouse support.");
@@ -5290,6 +5494,49 @@ export async function drawSignature(page, internalLabel, options = {}) {
     }
     await page.mouse.up();
 }
+export async function drawLiveFormSignature(page, options) {
+    await drawSignature(page, liveFormSignatureInternalLabel(options.target), options);
+    const quiet = options.afterQuiet === false
+        ? undefined
+        : await waitForLiveFormQuiet(page, typeof options.afterQuiet === "object" ? options.afterQuiet : {});
+    const dom = await waitForLiveFormSignatureState(page, {
+        ...options.target,
+        expectSigned: true,
+    });
+    const validation = options.afterValidation === undefined
+        ? undefined
+        : await waitForLiveFormValidationState(page, typeof options.afterValidation === "object" ? options.afterValidation : {});
+    return {
+        dom,
+        ...(quiet ? { quiet } : {}),
+        ...(validation ? { validation } : {}),
+        ok: dom.matched &&
+            (quiet?.quiet ?? true) &&
+            ((validation?.inlineErrors.length ?? 0) === 0),
+    };
+}
+export async function clearLiveFormSignature(page, options) {
+    const internalLabel = liveFormSignatureInternalLabel(options.target);
+    await page.locator(formstackSelectors.signatureClearButtonByInternalLabel(internalLabel)).first().click();
+    const quiet = options.afterQuiet === false
+        ? undefined
+        : await waitForLiveFormQuiet(page, typeof options.afterQuiet === "object" ? options.afterQuiet : {});
+    const dom = await waitForLiveFormSignatureState(page, {
+        ...options.target,
+        expectSigned: false,
+    });
+    const validation = options.afterValidation === undefined
+        ? undefined
+        : await waitForLiveFormValidationState(page, typeof options.afterValidation === "object" ? options.afterValidation : {});
+    return {
+        dom,
+        ...(quiet ? { quiet } : {}),
+        ...(validation ? { validation } : {}),
+        ok: dom.matched &&
+            (quiet?.quiet ?? true) &&
+            ((validation?.inlineErrors.length ?? 0) === 0),
+    };
+}
 export function createFormTestHarness(page, options = {}) {
     return {
         page,
@@ -5669,6 +5916,19 @@ export const liveFormFieldRecipes = {
         name,
         run: (harness) => harness.uploadFile(internalLabel, files),
     }),
+    uploadFileAndAssertDom: (name, internalLabel, files, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const result = await uploadLiveFormFile(harness.page, {
+                ...options,
+                target: { internalLabel },
+                files,
+            });
+            if (!result.ok) {
+                throw new Error(`File upload "${internalLabel}" did not match expected selected files.`);
+            }
+        },
+    }),
     clearSignatureDom: (name, internalLabel) => ({
         name,
         run: (harness) => harness.clearSignature(internalLabel),
@@ -5677,6 +5937,30 @@ export const liveFormFieldRecipes = {
         name,
         run: (harness) => harness.drawSignature(internalLabel, options),
     }),
+    drawSignatureAndAssertDom: (name, internalLabel, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const result = await drawLiveFormSignature(harness.page, {
+                ...options,
+                target: { internalLabel },
+            });
+            if (!result.ok) {
+                throw new Error(`Signature "${internalLabel}" did not produce a signed state.`);
+            }
+        },
+    }),
+    clearSignatureAndAssertDom: (name, internalLabel, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const result = await clearLiveFormSignature(harness.page, {
+                ...options,
+                target: { internalLabel },
+            });
+            if (!result.ok) {
+                throw new Error(`Signature "${internalLabel}" did not clear to an unsigned state.`);
+            }
+        },
+    }),
     setNameApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormNameValue(value), options),
     setAddressApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormAddressValue(value), options),
     setChoiceApi: (name, internalLabel, value, options = {}) => ({