@redrockswebdevelopment/formstack-form-testing 0.1.39 → 0.1.40

package/dist/index.js

@@ -60,7 +60,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: false,
         domAssertion: true,
         reason: "Description fields do not collect user values; test rendered content, visibility, and styling.",
-        recommendedHelpers: ["snapshotLiveFormDomFields", "waitForLiveFormVisibility"],
+        recommendedHelpers: ["readLiveFormStructuralState", "waitForLiveFormStructuralState", "liveFormScenarioSteps.expectStructuralField"],
     },
     embed: {
         kind: "embed",
@@ -69,7 +69,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: false,
         domAssertion: true,
         reason: "Embed fields generally provide scripts/styles/markup; test side effects and diagnostics, not value writes.",
-        recommendedHelpers: ["createFormBrowserMonitor", "waitForConsoleMessage", "waitForWindowFlag", "snapshotLiveFormDomFields"],
+        recommendedHelpers: ["readLiveFormStructuralState", "createFormBrowserMonitor", "waitForConsoleMessage", "waitForWindowFlag"],
     },
     email: {
         kind: "email",
@@ -123,7 +123,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: true,
         domAssertion: true,
         reason: "Page breaks do not collect values; test navigation, visible page state, and progress UI.",
-        recommendedHelpers: ["clickNext", "clickPrevious", "waitForLiveFormVisibility"],
+        recommendedHelpers: ["readLiveFormStructuralState", "clickNext", "clickPrevious", "waitForLiveFormVisibility"],
     },
     payment: {
         kind: "payment",
@@ -178,7 +178,7 @@ export const liveFormFieldTypeCoverage = {
         domInteraction: false,
         domAssertion: true,
         reason: "Sections group content and logic visibility; test rendered content and conditional visibility.",
-        recommendedHelpers: ["snapshotLiveFormDomFields", "waitForLiveFormVisibility"],
+        recommendedHelpers: ["readLiveFormStructuralState", "waitForLiveFormStructuralState", "liveFormScenarioSteps.expectStructuralField"],
     },
     select: {
         kind: "select",
@@ -1853,6 +1853,105 @@ export async function waitForLiveFormDomFieldState(page, options) {
     }
     return latest;
 }
+export async function readLiveFormStructuralState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormStructuralState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const normalizeText = (value) => (value ?? "").replace(/\s+/g, " ").trim();
+        const controlSnapshot = (control) => {
+            const input = control;
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type: control.getAttribute("type"),
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: control.getAttribute("value"),
+                currentValue: "value" in input ? input.value : null,
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? control.checked : null,
+            };
+        };
+        const inferKind = (element) => {
+            if (!element)
+                return "unknown";
+            const internalLabel = element.getAttribute("data-internal-label")?.toLowerCase() ?? "";
+            const id = element.getAttribute("id")?.toLowerCase() ?? "";
+            const classes = Array.from(element.classList).join(" ").toLowerCase();
+            const dataTestId = element.getAttribute("data-testid")?.toLowerCase() ?? "";
+            const text = normalizeText(element.textContent).toLowerCase();
+            if (internalLabel.includes("code_embed") || text.startsWith(":root{") || text.includes("<script"))
+                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"))
+                return "description";
+            if (classes.includes("section") || id.includes("section") || element.querySelector(".fsSectionHeader, [class*='SectionHeader']"))
+                return "section";
+            return "unknown";
+        };
+        const isVisible = (element) => {
+            if (!element || !(element instanceof HTMLElement))
+                return false;
+            const style = window.getComputedStyle(element);
+            return style.display !== "none" &&
+                style.visibility !== "hidden" &&
+                style.opacity !== "0" &&
+                element.getClientRects().length > 0;
+        };
+        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, textarea, select")).map(controlSnapshot)
+            : [];
+        const text = normalizeText(root?.textContent);
+        const inferredKind = inferKind(root);
+        const expectedText = stateOptions.expectedText;
+        const textMatched = expectedText === undefined
+            ? true
+            : typeof expectedText === "string"
+                ? text.includes(expectedText)
+                : expectedText.test(text);
+        const expectedVisible = stateOptions.expectedVisible;
+        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;
+        return {
+            matched: Boolean(root) && kindMatched && textMatched && visibilityMatched && controlsMatched,
+            elementMatched: Boolean(root),
+            id: root?.getAttribute("id") ?? null,
+            internalLabel: root?.getAttribute("data-internal-label") ?? null,
+            inferredKind,
+            visible,
+            text,
+            controlCount: controls.length,
+            controls,
+            ...(stateOptions.expectedKind === undefined ? {} : { expectedKind: stateOptions.expectedKind }),
+            ...(expectedText === undefined ? {} : { expectedText: String(expectedText) }),
+            ...(expectedVisible === undefined ? {} : { expectedVisible }),
+            kindMatched,
+            textMatched,
+            visibilityMatched,
+            controlsMatched,
+        };
+    }, options);
+}
+export async function waitForLiveFormStructuralState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormStructuralState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormStructuralState(page, options);
+    }
+    return latest;
+}
 export async function readLiveFormProductState(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("readLiveFormProductState requires a Playwright page with evaluate().");
@@ -6365,6 +6464,15 @@ export const liveFormScenarioSteps = {
             }
         },
     }),
+    expectStructuralField: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const state = await waitForLiveFormStructuralState(harness.page, options);
+            if (!state.matched) {
+                throw new Error(`Expected structural form element ${options.internalLabel ?? options.fieldId ?? options.selector ?? "unknown"} to match.`);
+            }
+        },
+    }),
     expectValidationErrors: (name, options = {}) => ({
         name,
         run: async (harness) => {