@redrockswebdevelopment/formstack-form-testing 0.1.32 → 0.1.33

package/dist/index.js

@@ -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",
@@ -5269,6 +5269,12 @@ function fileInputLocator(page, target) {
     }
     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().");
@@ -5356,6 +5362,101 @@ export async function uploadLiveFormFile(page, options) {
             ((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.");
@@ -5393,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,
@@ -5793,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 = {}) => ({