@redrockswebdevelopment/formstack-form-testing 0.1.32 → 0.1.34

package/dist/index.js

@@ -150,8 +150,8 @@ export const liveFormFieldTypeCoverage = {
         apiWrite: true,
         domInteraction: true,
         domAssertion: true,
-        reason: "Product API state can be set, but visible quantity and amount UI can diverge by product configuration.",
-        recommendedHelpers: ["buildLiveFormProductValue", "setLiveFormFieldValueTransaction", "fillProduct", "readLiveFormDomFieldState"],
+        reason: "Product API state can be set, but visible quantity, fixed amount, and selected product UI can diverge by product configuration.",
+        recommendedHelpers: ["buildLiveFormProductValue", "setLiveFormProductValue", "readLiveFormProductState", "fillProduct"],
     },
     radio: {
         kind: "radio",
@@ -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",
@@ -1030,6 +1030,13 @@ export function buildLiveFormProductValue(value, current = {}) {
         ...value,
     };
 }
+export function normalizeLiveFormProductValue(value, current = {}) {
+    return buildLiveFormProductValue({
+        ...(value.fixedAmount === undefined ? {} : { fixedAmount: String(value.fixedAmount) }),
+        ...(value.quantity === undefined ? {} : { quantity: String(value.quantity) }),
+        ...("value" in value && value.value !== undefined ? { value: String(value.value) } : {}),
+    }, current);
+}
 export function buildLiveFormRatingValue(value) {
     return { value: String(value) };
 }
@@ -1827,6 +1834,119 @@ export async function waitForLiveFormDomFieldState(page, options) {
     }
     return latest;
 }
+export async function readLiveFormProductState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormProductState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const normalizeText = (value) => (value ?? "").replace(/\s+/g, " ").trim();
+        const inferPart = (control) => {
+            const label = control.id ? document.querySelector(`label[for="${CSS.escape(control.id)}"]`) : null;
+            const haystack = [
+                control.name,
+                control.id,
+                control.className,
+                control.getAttribute("placeholder"),
+                control.getAttribute("aria-label"),
+                label?.textContent,
+            ].map(normalizeText).join(" ").toLowerCase();
+            if (/\b(quantity|qty|\[quantity\]|-quantity$|_quantity$)/i.test(haystack))
+                return "quantity";
+            if (/\b(fixed amount|fixedamount|amount|price|\[fixedamount\]|-fixedamount$|_fixedamount$)/i.test(haystack))
+                return "fixedAmount";
+            if (/\b(product|option|value|\[value\]|-value$|_value$)/i.test(haystack))
+                return "value";
+            return null;
+        };
+        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 nativeControls = root
+            ? Array.from(root.querySelectorAll("input, textarea, select"))
+            : [];
+        const controls = nativeControls.map((control) => {
+            const selected = control instanceof HTMLSelectElement
+                ? control.selectedIndex >= 0
+                : control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type)
+                    ? control.checked
+                    : null;
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type: control.getAttribute("type"),
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: control.getAttribute("value"),
+                currentValue: "value" in control ? control.value : "",
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type) ? control.checked : null,
+                part: inferPart(control),
+                text: control instanceof HTMLSelectElement
+                    ? normalizeText(control.selectedOptions.item(0)?.textContent)
+                    : normalizeText(control.textContent),
+                selected,
+                disabled: "disabled" in control ? Boolean(control.disabled) : null,
+            };
+        });
+        const activeControls = controls.filter((control) => control.disabled !== true &&
+            ((control.tagName === "select" && (control.currentValue ?? "").length > 0) ||
+                (["checkbox", "radio"].includes(control.type ?? "") ? control.checked === true : (control.currentValue ?? "").length > 0)));
+        const findPart = (part) => activeControls.find((control) => control.part === part)?.currentValue ?? null;
+        const selectedValue = findPart("value") ?? activeControls.find((control) => ["checkbox", "radio"].includes(control.type ?? "") && control.checked === true)?.currentValue ?? null;
+        const quantity = findPart("quantity");
+        const fixedAmount = findPart("fixedAmount");
+        const amountText = root
+            ? Array.from(root.querySelectorAll("[class*=\"amount\"], [class*=\"price\"], [data-testid*=\"amount\"], [data-testid*=\"price\"]"))
+                .map((element) => normalizeText(element.textContent))
+                .find((text) => text.length > 0 && /[$€£]|\d/.test(text)) ?? null
+            : null;
+        const expected = stateOptions.expectedValue ?? {};
+        const expectedEntries = Object.entries(expected).filter((entry) => typeof entry[1] === "string" && entry[1].length > 0);
+        const selectedParts = {
+            value: selectedValue,
+            quantity,
+            fixedAmount,
+        };
+        const renderedExpectedEntries = expectedEntries.filter(([part]) => selectedParts[part] !== null);
+        const unavailableParts = expectedEntries
+            .filter(([part]) => selectedParts[part] === null)
+            .map(([part]) => part);
+        const missingParts = renderedExpectedEntries
+            .filter(([part]) => selectedParts[part] === "")
+            .map(([part]) => part);
+        const mismatchedParts = renderedExpectedEntries
+            .filter(([part, value]) => selectedParts[part] !== "" && selectedParts[part] !== value)
+            .map(([part]) => part);
+        const renderedValueAvailable = renderedExpectedEntries.length > 0 || activeControls.length > 0 || amountText !== null;
+        return {
+            fieldMatched: Boolean(root),
+            selectedValue,
+            quantity,
+            fixedAmount,
+            amountText,
+            ...(stateOptions.expectedValue === undefined ? {} : { expectedValue: stateOptions.expectedValue }),
+            renderedValueAvailable,
+            unavailableParts,
+            missingParts,
+            mismatchedParts,
+            matched: Boolean(root) && missingParts.length === 0 && mismatchedParts.length === 0,
+            controls,
+        };
+    }, options);
+}
+export async function waitForLiveFormProductState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormProductState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormProductState(page, options);
+    }
+    return latest;
+}
 export async function readLiveFormCheckboxState(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("readLiveFormCheckboxState requires a Playwright page with evaluate().");
@@ -4081,6 +4201,47 @@ export async function setLiveFormMatrixValues(page, options) {
             (visibility?.matched ?? true),
     };
 }
+export async function setLiveFormProductValue(page, options) {
+    const payload = normalizeLiveFormProductValue(options.value, options.current);
+    const transaction = await performLiveFormFieldTransaction(page, {
+        write: {
+            ...(options.write ?? {}),
+            target: options.target,
+            value: payload,
+            notify: options.write?.notify ?? true,
+        },
+        fieldKind: "product",
+        waitForEvent: options.waitForEvent ?? true,
+        dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+        afterQuiet: options.afterQuiet ?? { quietMs: 200, timeoutMs: 5_000 },
+        ...(options.afterValidation === undefined ? {} : { afterValidation: options.afterValidation }),
+    });
+    const dom = await waitForLiveFormProductState(page, {
+        ...options.target,
+        expectedValue: payload,
+        ...(options.write?.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
+    });
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []).map((target) => ({ ...target, visible: true })),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const visibility = visibilityTargets.length > 0
+        ? await waitForLiveFormVisibility(page, { targets: visibilityTargets })
+        : undefined;
+    return {
+        payload,
+        transaction,
+        dom,
+        ...(visibility ? { visibility } : {}),
+        ok: transaction.write.valueMatched &&
+            (transaction.event?.matched ?? true) &&
+            (transaction.domDispatch ? transaction.domDispatch.matchedControlCount >= 1 : true) &&
+            (transaction.quiet?.quiet ?? true) &&
+            ((transaction.validation?.inlineErrors.length ?? 0) === 0) &&
+            dom.matched &&
+            (visibility?.matched ?? true),
+    };
+}
 export async function setLiveFormRatingValue(page, options) {
     const payload = normalizeLiveFormRatingValue(options.value);
     const value = payload.value;
@@ -4211,7 +4372,18 @@ export async function answerProgressiveLiveFormField(page, options) {
             ...(validationOptions ? { afterValidation: validationOptions } : {}),
         })
         : undefined;
-    const ratingTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && options.fieldKind === "rating"
+    const productTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && options.fieldKind === "product"
+        ? await setLiveFormProductValue(page, {
+            target: options.target,
+            value: options.value,
+            ...(options.write === undefined ? {} : { write: options.write }),
+            waitForEvent: options.waitForEvent ?? true,
+            dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+            afterQuiet: options.afterQuiet ?? true,
+            ...(validationOptions ? { afterValidation: validationOptions } : {}),
+        })
+        : undefined;
+    const ratingTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && !productTransaction && options.fieldKind === "rating"
         ? await setLiveFormRatingValue(page, {
             target: options.target,
             value: options.value,
@@ -4241,23 +4413,25 @@ export async function answerProgressiveLiveFormField(page, options) {
                 ? selectTransaction.transaction
                 : matrixTransaction
                     ? matrixTransaction.transaction
-                    : ratingTransaction
-                        ? ratingTransaction.transaction
-                        : dateTimeTransaction
-                            ? dateTimeTransaction.transaction
-                            : await performLiveFormFieldTransaction(page, {
-                                write: {
-                                    ...(options.write ?? {}),
-                                    target: options.target,
-                                    value: options.value,
-                                    notify: options.write?.notify ?? true,
-                                },
-                                ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
-                                waitForEvent: options.waitForEvent ?? true,
-                                dispatchDomEvents: options.dispatchDomEvents ?? "auto",
-                                afterQuiet: options.afterQuiet ?? true,
-                                ...(validationOptions ? { afterValidation: validationOptions } : {}),
-                            });
+                    : productTransaction
+                        ? productTransaction.transaction
+                        : ratingTransaction
+                            ? ratingTransaction.transaction
+                            : dateTimeTransaction
+                                ? dateTimeTransaction.transaction
+                                : await performLiveFormFieldTransaction(page, {
+                                    write: {
+                                        ...(options.write ?? {}),
+                                        target: options.target,
+                                        value: options.value,
+                                        notify: options.write?.notify ?? true,
+                                    },
+                                    ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
+                                    waitForEvent: options.waitForEvent ?? true,
+                                    dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+                                    afterQuiet: options.afterQuiet ?? true,
+                                    ...(validationOptions ? { afterValidation: validationOptions } : {}),
+                                });
     const visibilityTargets = [
         ...(options.expectVisible ?? []),
         ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
@@ -5269,6 +5443,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 +5536,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 +5668,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 +6111,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 = {}) => ({
@@ -5873,7 +6215,19 @@ export const liveFormFieldRecipes = {
             });
         },
     }),
-    setProductApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormProductValue(value), options),
+    setProductApi: (name, internalLabel, value, options = {}) => ({
+        name,
+        run: async (harness) => {
+            await setLiveFormProductValue(harness.page, {
+                target: { internalLabel },
+                value,
+                write: { notify: options.notify ?? true },
+                waitForEvent: options.waitForEvent ?? (options.notify ?? true),
+                dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+                afterQuiet: options.waitForQuiet ?? true,
+            });
+        },
+    }),
     setFieldApiAuto: (name, internalLabel, value, fieldKind, options = {}) => apiRecipeStep(name, { internalLabel }, value, { ...options, fieldKind, dispatchDomEvents: "auto" }),
     setNameApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setNameApi(name, internalLabel, value, { ...options, fieldKind: options.fieldKind ?? "name", dispatchDomEvents: "auto" }),
     setChoiceApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setChoiceApi(name, internalLabel, value, { ...options, fieldKind: options.fieldKind ?? "radio", dispatchDomEvents: "auto" }),