@redrockswebdevelopment/formstack-form-testing 0.1.40 → 0.1.42

package/dist/index.js

@@ -26,6 +26,15 @@ export const liveFormFieldTypeCoverage = {
         reason: "Compound address values can be written through Live Form API, while subfield UX should be asserted for address line, city, state, ZIP, and country controls.",
         recommendedHelpers: ["buildLiveFormAddressValue", "setLiveFormAddressValue", "readLiveFormAddressState", "fillAddress"],
     },
+    calculation: {
+        kind: "calculation",
+        strategy: "assertion-only",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Calculation fields are derived by Formstack. Test their lifecycle after source changes, numeric/date normalization, visibility, and submission inclusion instead of writing them directly.",
+        recommendedHelpers: ["readLiveFormCalculationState", "waitForLiveFormCalculationState", "traceLiveFormCalculationLifecycle", "readLiveFormSubmissionInclusion"],
+    },
     checkbox: {
         kind: "checkbox",
         strategy: "api-safe",
@@ -89,6 +98,15 @@ export const liveFormFieldTypeCoverage = {
         reason: "File fields must be tested through browser file upload controls, not generic Live Form API setValue payloads.",
         recommendedHelpers: ["uploadLiveFormFile", "readLiveFormFileState", "uploadFile", "liveFormFieldRecipes.uploadFileDom"],
     },
+    hidden: {
+        kind: "hidden",
+        strategy: "assertion-only",
+        apiWrite: true,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Hidden fields can be populated through API or scripts, but tests should prove visibility state and whether the populated control is included in FormData/submission surfaces.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "readLiveFormFieldValue", "readLiveFormSubmissionInclusion", "readLiveFormStateDrift"],
+    },
     matrix: {
         kind: "matrix",
         strategy: "api-safe",
@@ -1883,7 +1901,12 @@ export async function readLiveFormStructuralState(page, options) {
                 return "embed";
             if (classes.includes("pagebreak") || classes.includes("page-break") || dataTestId.includes("pagebreak") || id.includes("pagebreak"))
                 return "pagebreak";
-            if (classes.includes("description") || internalLabel.includes("description") || dataTestId.includes("description"))
+            if (classes.includes("description") ||
+                classes.includes("richtext") ||
+                internalLabel.includes("description") ||
+                internalLabel.includes("richtext") ||
+                dataTestId.includes("description") ||
+                dataTestId.includes("richtext"))
                 return "description";
             if (classes.includes("section") || id.includes("section") || element.querySelector(".fsSectionHeader, [class*='SectionHeader']"))
                 return "section";
@@ -1920,7 +1943,9 @@ export async function readLiveFormStructuralState(page, options) {
         const visible = isVisible(root);
         const visibilityMatched = expectedVisible === undefined || visible === expectedVisible;
         const kindMatched = stateOptions.expectedKind === undefined || inferredKind === stateOptions.expectedKind;
-        const controlsMatched = stateOptions.allowControls === true || controls.length === 0;
+        const controlsMatched = stateOptions.allowControls === true ||
+            (stateOptions.allowControls !== false && inferredKind === "section") ||
+            controls.length === 0;
         return {
             matched: Boolean(root) && kindMatched && textMatched && visibilityMatched && controlsMatched,
             elementMatched: Boolean(root),
@@ -1952,6 +1977,327 @@ export async function waitForLiveFormStructuralState(page, options) {
     }
     return latest;
 }
+export async function readLiveFormCalculationState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormCalculationState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const readPath = (value, path) => {
+            if (!path)
+                return value;
+            return path.split(".").reduce((current, segment) => {
+                if (current === null || current === undefined || typeof current !== "object")
+                    return undefined;
+                return Reflect.get(current, segment);
+            }, value);
+        };
+        const valuesEqual = (left, right) => {
+            if (Object.is(left, right))
+                return true;
+            try {
+                return JSON.stringify(left) === JSON.stringify(right);
+            }
+            catch {
+                return false;
+            }
+        };
+        const stringifyValue = (value) => {
+            if (value === null || value === undefined)
+                return "";
+            if (typeof value === "string")
+                return value;
+            if (typeof value === "number" || typeof value === "boolean")
+                return String(value);
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return String(value);
+            }
+        };
+        const normalizeNumber = (value) => {
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+            const text = stringifyValue(value).replace(/[$,%\s,]/g, "");
+            if (!text)
+                return null;
+            const parsed = Number(text);
+            return Number.isFinite(parsed) ? parsed : null;
+        };
+        const normalizeDate = (value) => {
+            const text = stringifyValue(value).trim();
+            if (!text)
+                return null;
+            const timestamp = Date.parse(text);
+            if (Number.isNaN(timestamp))
+                return null;
+            return new Date(timestamp).toISOString().slice(0, 10);
+        };
+        const expectedDateText = stateOptions.expectedDate === undefined ? undefined : normalizeDate(stateOptions.expectedDate) ?? undefined;
+        const isVisible = (element) => {
+            if (!element)
+                return null;
+            if (!(element instanceof HTMLElement))
+                return false;
+            for (let current = element; current; current = current.parentElement) {
+                const style = getComputedStyle(current);
+                const rect = current.getBoundingClientRect();
+                if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0)
+                    return false;
+                if (rect.width <= 0 || rect.height <= 0)
+                    return false;
+            }
+            return element.getClientRects().length > 0;
+        };
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return Array.isArray(forms) ? forms[0] ?? null : null;
+        };
+        const form = readApi();
+        const apiAvailable = Boolean(form && typeof form === "object");
+        const getField = form && typeof form === "object" ? Reflect.get(form, "getField") : null;
+        const getFieldByInternalLabel = form && typeof form === "object" ? Reflect.get(form, "getFieldByInternalLabel") : null;
+        const field = stateOptions.fieldId != null && typeof getField === "function"
+            ? Reflect.apply(getField, form, [String(stateOptions.fieldId)])
+            : stateOptions.internalLabel && typeof getFieldByInternalLabel === "function"
+                ? Reflect.apply(getFieldByInternalLabel, form, [stateOptions.internalLabel])
+                : null;
+        const fieldAvailable = Boolean(field && typeof field === "object");
+        const getId = field && typeof field === "object" ? Reflect.get(field, "getId") : null;
+        const getValue = field && typeof field === "object" ? Reflect.get(field, "getValue") : null;
+        const getGeneralAttribute = field && typeof field === "object" ? Reflect.get(field, "getGeneralAttribute") : null;
+        const id = fieldAvailable
+            ? typeof getId === "function"
+                ? Reflect.apply(getId, field, [])
+                : Reflect.get(field, "id") ?? null
+            : stateOptions.fieldId ?? null;
+        const value = typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+        const selectedValue = readPath(value, stateOptions.valuePath);
+        const root = stateOptions.selector != null
+            ? document.querySelector(stateOptions.selector)
+            : stateOptions.internalLabel != null
+                ? document.querySelector(`[data-internal-label="${CSS.escape(stateOptions.internalLabel)}"]`)
+                : id == null
+                    ? null
+                    : document.querySelector(`#fsCell${CSS.escape(String(id))}, #fsFieldCell${CSS.escape(String(id))}, [data-testid="field-${CSS.escape(String(id))}"]`);
+        const visible = isVisible(root);
+        const hidden = typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, ["hidden"]) === true : visible === null ? null : !visible;
+        const textValue = stringifyValue(selectedValue);
+        const numberValue = normalizeNumber(selectedValue);
+        const dateValue = normalizeDate(selectedValue);
+        const valueMatched = stateOptions.expectedValue === undefined || valuesEqual(selectedValue, stateOptions.expectedValue);
+        const numberMatched = stateOptions.expectedNumber === undefined ||
+            (numberValue !== null && Math.abs(numberValue - stateOptions.expectedNumber) <= (stateOptions.numberTolerance ?? 0));
+        const dateMatched = expectedDateText === undefined || dateValue === expectedDateText;
+        const visibilityMatched = stateOptions.expectedVisible === undefined || visible === stateOptions.expectedVisible;
+        return {
+            matched: apiAvailable && fieldAvailable && valueMatched && numberMatched && dateMatched && visibilityMatched,
+            apiAvailable,
+            fieldAvailable,
+            id,
+            internalLabel: root?.getAttribute("data-internal-label") ?? stateOptions.internalLabel ?? null,
+            value,
+            selectedValue,
+            textValue,
+            numberValue,
+            dateValue,
+            visible,
+            hidden,
+            ...(stateOptions.expectedValue === undefined ? {} : { expectedValue: stateOptions.expectedValue }),
+            ...(stateOptions.expectedNumber === undefined ? {} : { expectedNumber: stateOptions.expectedNumber }),
+            ...(expectedDateText === undefined ? {} : { expectedDate: expectedDateText }),
+            valueMatched,
+            numberMatched,
+            dateMatched,
+            visibilityMatched,
+        };
+    }, options);
+}
+export async function waitForLiveFormCalculationState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormCalculationState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormCalculationState(page, options);
+    }
+    return latest;
+}
+export async function readLiveFormSubmissionInclusion(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormSubmissionInclusion requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((inclusionOptions) => {
+        const isEmpty = (value) => {
+            if (value === null || value === undefined)
+                return true;
+            if (typeof value === "string")
+                return value.trim().length === 0;
+            if (typeof value === "number" || typeof value === "boolean")
+                return false;
+            if (Array.isArray(value))
+                return value.length === 0 || value.every((item) => isEmpty(item));
+            if (typeof value === "object")
+                return Object.values(value).every((item) => isEmpty(item));
+            return false;
+        };
+        const isVisible = (element) => {
+            if (!element)
+                return null;
+            if (!(element instanceof HTMLElement))
+                return false;
+            for (let current = element; current; current = current.parentElement) {
+                const style = getComputedStyle(current);
+                const rect = current.getBoundingClientRect();
+                if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0)
+                    return false;
+                if (rect.width <= 0 || rect.height <= 0)
+                    return false;
+            }
+            return element.getClientRects().length > 0;
+        };
+        const controlSnapshot = (control, formData) => {
+            const input = control;
+            const name = control.getAttribute("name");
+            const type = control.getAttribute("type");
+            const disabled = "disabled" in input ? input.disabled : null;
+            const visible = isVisible(control) === true;
+            const checked = control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type) ? control.checked : null;
+            const successful = Boolean(name) &&
+                disabled !== true &&
+                (!(control instanceof HTMLInputElement) || !["checkbox", "radio"].includes(control.type) || control.checked);
+            const formDataIncluded = Boolean(name && formData?.has(name));
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type,
+                id: control.getAttribute("id"),
+                name,
+                value: control.getAttribute("value"),
+                currentValue: "value" in input ? input.value : null,
+                checked,
+                disabled,
+                visible,
+                successful,
+                formDataIncluded,
+            };
+        };
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return Array.isArray(forms) ? forms[0] ?? null : null;
+        };
+        const formApi = readApi();
+        const apiAvailable = Boolean(formApi && typeof formApi === "object");
+        const getField = formApi && typeof formApi === "object" ? Reflect.get(formApi, "getField") : null;
+        const getFieldByInternalLabel = formApi && typeof formApi === "object" ? Reflect.get(formApi, "getFieldByInternalLabel") : null;
+        const field = inclusionOptions.fieldId != null && typeof getField === "function"
+            ? Reflect.apply(getField, formApi, [String(inclusionOptions.fieldId)])
+            : inclusionOptions.internalLabel && typeof getFieldByInternalLabel === "function"
+                ? Reflect.apply(getFieldByInternalLabel, formApi, [inclusionOptions.internalLabel])
+                : null;
+        const fieldAvailable = Boolean(field && typeof field === "object");
+        const getId = field && typeof field === "object" ? Reflect.get(field, "getId") : null;
+        const getValue = field && typeof field === "object" ? Reflect.get(field, "getValue") : null;
+        const getGeneralAttribute = field && typeof field === "object" ? Reflect.get(field, "getGeneralAttribute") : null;
+        const id = fieldAvailable
+            ? typeof getId === "function"
+                ? Reflect.apply(getId, field, [])
+                : Reflect.get(field, "id") ?? null
+            : inclusionOptions.fieldId ?? null;
+        const value = typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+        const root = inclusionOptions.selector != null
+            ? document.querySelector(inclusionOptions.selector)
+            : inclusionOptions.internalLabel != null
+                ? document.querySelector(`[data-internal-label="${CSS.escape(inclusionOptions.internalLabel)}"]`)
+                : id == null
+                    ? null
+                    : document.querySelector(`#fsCell${CSS.escape(String(id))}, #fsFieldCell${CSS.escape(String(id))}, [data-testid="field-${CSS.escape(String(id))}"]`);
+        const htmlForm = root?.closest("form") ?? document.querySelector("form");
+        const formData = htmlForm instanceof HTMLFormElement ? new FormData(htmlForm) : null;
+        const controls = root
+            ? Array.from(root.querySelectorAll("input, textarea, select"))
+                .filter((control) => inclusionOptions.includeHiddenControls !== false || control.getAttribute("type") !== "hidden")
+                .map((control) => controlSnapshot(control, formData))
+            : [];
+        const includedNames = [...new Set(controls.filter((control) => control.formDataIncluded).map((control) => control.name).filter((name) => Boolean(name)))];
+        const included = includedNames.length > 0;
+        const domVisible = isVisible(root);
+        const apiHidden = typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, ["hidden"]) === true : null;
+        const matched = Boolean(root) && (inclusionOptions.expectedIncluded === undefined || included === inclusionOptions.expectedIncluded);
+        const reason = !root
+            ? "field-root-missing"
+            : included
+                ? domVisible === false ? "included-while-dom-hidden" : "included"
+                : isEmpty(value) ? "not-included-empty-value" : domVisible === false || apiHidden === true ? "not-included-hidden-by-logic-or-disabled" : "not-included-no-successful-controls";
+        return {
+            matched,
+            fieldMatched: Boolean(root),
+            apiAvailable,
+            fieldAvailable,
+            id,
+            internalLabel: root?.getAttribute("data-internal-label") ?? inclusionOptions.internalLabel ?? null,
+            value,
+            isEmpty: isEmpty(value),
+            apiHidden,
+            domVisible,
+            controls,
+            included,
+            includedNames,
+            ...(inclusionOptions.expectedIncluded === undefined ? {} : { expectedIncluded: inclusionOptions.expectedIncluded }),
+            reason,
+        };
+    }, options);
+}
+export async function traceLiveFormCalculationLifecycle(page, options) {
+    const totalStartedAt = Date.now();
+    const phases = [];
+    const beforeStartedAt = Date.now();
+    const before = await readLiveFormCalculationState(page, options.calculation);
+    phases.push(endCascadePhase("before-calculation", beforeStartedAt, before.fieldAvailable));
+    const writeStartedAt = Date.now();
+    const transaction = await performLiveFormFieldTransaction(page, {
+        ...(options.trigger.transaction ?? {}),
+        write: {
+            ...(options.trigger.write ?? {}),
+            target: options.trigger.target,
+            value: options.trigger.value,
+            notify: options.trigger.write?.notify ?? true,
+        },
+        ...(options.trigger.fieldKind === undefined ? {} : { fieldKind: options.trigger.fieldKind }),
+    });
+    phases.push(endCascadePhase("write", writeStartedAt, transaction.write.valueMatched !== false));
+    const quietOptions = options.quiet === true ? {} : options.quiet === false ? undefined : options.quiet;
+    const quietStartedAt = Date.now();
+    const quiet = quietOptions ? await waitForLiveFormQuiet(page, quietOptions) : undefined;
+    if (quiet)
+        phases.push(endCascadePhase("quiet", quietStartedAt, quiet.quiet));
+    const afterStartedAt = Date.now();
+    const after = await waitForLiveFormCalculationState(page, options.calculation);
+    phases.push(endCascadePhase("after-calculation", afterStartedAt, after.matched));
+    const visibilityStartedAt = Date.now();
+    const visibility = options.visibility ? await waitForLiveFormVisibility(page, options.visibility) : undefined;
+    if (visibility)
+        phases.push(endCascadePhase("visibility", visibilityStartedAt, visibility.matched));
+    const endedAt = Date.now();
+    const ok = transaction.write.valueMatched !== false && (quiet?.quiet ?? true) && after.matched && (visibility?.matched ?? true);
+    return {
+        label: options.label ?? "live-form-calculation-lifecycle",
+        before,
+        transaction,
+        after,
+        ...(quiet ? { quiet } : {}),
+        ...(visibility ? { visibility } : {}),
+        phases,
+        totalMs: endedAt - totalStartedAt,
+        ok,
+    };
+}
 export async function readLiveFormProductState(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("readLiveFormProductState requires a Playwright page with evaluate().");
@@ -3432,16 +3778,39 @@ export async function discoverLiveFormFieldShapes(page, options = {}) {
                 controls.some((control) => control.name?.toLowerCase().includes("payment") || control.name?.toLowerCase().includes("credit"))) {
                 return "payment";
             }
+            if (internalLabel.includes("calculation") ||
+                internalLabel.includes("calculated") ||
+                internalLabel.includes("calc_") ||
+                internalLabel.endsWith("_calc") ||
+                classes.includes("calculation") ||
+                classes.includes("calculated") ||
+                dataTestId.includes("calculation") ||
+                text.includes("calculation")) {
+                return "calculation";
+            }
             if (internalLabel.includes("code_embed") || text.startsWith(":root{") || text.includes("<script"))
                 return "embed";
             if (controls.length === 0) {
                 if (classes.includes("pagebreak") || classes.includes("page-break") || dataTestId.includes("pagebreak") || id.includes("pagebreak")) {
                     return "pagebreak";
                 }
-                if (classes.includes("description") || internalLabel.includes("description") || dataTestId.includes("description")) {
+                if (classes.includes("description") ||
+                    classes.includes("richtext") ||
+                    internalLabel.includes("description") ||
+                    internalLabel.includes("richtext") ||
+                    dataTestId.includes("description") ||
+                    dataTestId.includes("richtext")) {
                     return "description";
                 }
-                return "section";
+                if (classes.includes("section") || id.includes("section") || element.querySelector(".fsSectionHeader, [class*='SectionHeader']")) {
+                    return "section";
+                }
+                return "description";
+            }
+            if (internalLabel.includes("hidden") ||
+                classes.includes("hidden-field") ||
+                controls.every((control) => control.type === "hidden")) {
+                return "hidden";
             }
             if (classes.includes("matrix") || internalLabel.includes("matrix") || element.querySelector("[id^='matrix-row-'], table"))
                 return "matrix";