@redrockswebdevelopment/formstack-form-testing 0.1.20 → 0.1.22

package/dist/index.js

@@ -3385,7 +3385,7 @@ export function createLiveFormSampleFillPlan(definition, sampleValues, options =
         const entry = {
             key,
             target,
-            value: samples[key],
+            value: normalizeLiveFormSampleValue(config.kind, samples[key]),
             ...(config.kind === undefined ? {} : { fieldKind: config.kind }),
             ...(config.required === undefined ? {} : { required: config.required }),
         };
@@ -3431,6 +3431,44 @@ function createSampleSmokeReadinessOptions(definition, options, defaultEnabled)
     }
     return createLiveFormReadinessOptions(definition, { ...options, requiredOnly: true });
 }
+function stableSerializeLiveFormValue(value) {
+    if (value === undefined)
+        return "undefined";
+    const normalize = (entry) => {
+        if (Array.isArray(entry))
+            return entry.map(normalize);
+        if (entry && typeof entry === "object") {
+            return Object.fromEntries(Object.entries(entry).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, normalize(child)]));
+        }
+        return entry;
+    };
+    return JSON.stringify(normalize(value));
+}
+export function normalizeLiveFormSampleValue(kind = "unknown", value) {
+    if (value instanceof Date)
+        return value.toISOString().slice(0, 10);
+    if (["radio", "rating", "select"].includes(kind) && typeof value === "string") {
+        return { value };
+    }
+    if (kind === "checkbox" && Array.isArray(value)) {
+        return buildLiveFormCheckboxValue(value.filter((entry) => typeof entry === "string"));
+    }
+    if (kind === "checkbox" && value && typeof value === "object" && Array.isArray(value.values)) {
+        return buildLiveFormCheckboxValue(value.values.filter((entry) => typeof entry === "string"));
+    }
+    if (kind === "checkbox" && typeof value === "boolean") {
+        return { checked: value };
+    }
+    return value;
+}
+export function createLiveFormFieldValueAdapter(kind = "unknown") {
+    return {
+        kind,
+        normalize: (value) => normalizeLiveFormSampleValue(kind, value),
+        isEmpty: (value) => isLiveFormFieldValueEmpty(normalizeLiveFormSampleValue(kind, value)),
+        equals: (actual, expected) => stableSerializeLiveFormValue(normalizeLiveFormSampleValue(kind, actual)) === stableSerializeLiveFormValue(normalizeLiveFormSampleValue(kind, expected)),
+    };
+}
 export async function runLiveFormSampleSmoke(page, definition, sampleValues, options = {}) {
     const beforeReadinessOptions = createSampleSmokeReadinessOptions(definition, options.beforeReadiness, false);
     const afterReadinessOptions = createSampleSmokeReadinessOptions(definition, options.afterReadiness, true);
@@ -3456,8 +3494,10 @@ export async function runLiveFormSampleSmoke(page, definition, sampleValues, opt
     };
 }
 function sampleValueShapeIssue(key, kind, value) {
+    const normalizedValue = normalizeLiveFormSampleValue(kind, value);
     const objectValue = value && typeof value === "object" ? value : null;
-    if (["radio", "select", "rating"].includes(kind ?? "") && (objectValue === null || typeof objectValue.value !== "string")) {
+    const normalizedObjectValue = normalizedValue && typeof normalizedValue === "object" ? normalizedValue : null;
+    if (["radio", "select", "rating"].includes(kind ?? "") && (normalizedObjectValue === null || typeof normalizedObjectValue.value !== "string")) {
         return {
             kind: "invalid-value-shape",
             key,
@@ -3465,7 +3505,7 @@ function sampleValueShapeIssue(key, kind, value) {
             detail: { kind },
         };
     }
-    if (["checkbox", "matrix"].includes(kind ?? "") && objectValue === null) {
+    if (["checkbox", "matrix"].includes(kind ?? "") && normalizedObjectValue === null) {
         return {
             kind: "invalid-value-shape",
             key,
@@ -3523,7 +3563,7 @@ export function validateLiveFormSampleProfile(definition, sampleValues, options
             continue;
         if (options.requiredOnly === true && config.required !== true)
             continue;
-        const value = samples[key];
+        const value = normalizeLiveFormSampleValue(config.kind, samples[key]);
         const shapeIssue = sampleValueShapeIssue(key, config.kind, value);
         if (shapeIssue)
             issues.push({ ...shapeIssue, target });
@@ -3578,6 +3618,8 @@ export function createLiveFormProgressiveSamplePlan(definition, sampleValues, op
             ...(step?.expectHiddenAfter === undefined ? {} : { expectHiddenAfter: step.expectHiddenAfter }),
             ...(step?.expectResetAfter === undefined ? {} : { expectResetAfter: step.expectResetAfter }),
             ...(step?.continueSelector === undefined ? {} : { continueSelector: step.continueSelector }),
+            ...(step?.expectVisibleAfterContinue === undefined ? {} : { expectVisibleAfterContinue: step.expectVisibleAfterContinue }),
+            ...(step?.expectHiddenAfterContinue === undefined ? {} : { expectHiddenAfterContinue: step.expectHiddenAfterContinue }),
             ...(step?.transaction === undefined ? {} : { transaction: step.transaction }),
         });
     }
@@ -3598,7 +3640,22 @@ export async function runLiveFormProgressiveSampleFlow(page, definition, sampleV
             ...(step.expectResetAfter === undefined ? {} : { expectReset: step.expectResetAfter }),
         }));
         if (step.continueSelector) {
-            await page.locator(step.continueSelector).first().click();
+            try {
+                await page.locator(step.continueSelector).first().click({ timeout: 5_000 });
+            }
+            catch (error) {
+                throw new Error(`Progressive step "${step.key}" could not click continue selector "${step.continueSelector}". The control may still be disabled because the preceding field value did not trigger Formstack side effects. Cause: ${error.message}`);
+            }
+            const continueVisibilityTargets = [
+                ...(step.expectVisibleAfterContinue ?? []).map((target) => ({ ...target, visible: true })),
+                ...(step.expectHiddenAfterContinue ?? []).map((target) => ({ ...target, visible: false })),
+            ];
+            if (continueVisibilityTargets.length > 0) {
+                const visibility = await waitForLiveFormVisibility(page, { targets: continueVisibilityTargets });
+                if (!visibility.matched) {
+                    throw new Error(`Progressive step "${step.key}" continue action did not settle into the requested visibility state.`);
+                }
+            }
         }
     }
     const quietOptions = options.afterQuiet === false ? undefined : options.afterQuiet === true ? {} : options.afterQuiet;
@@ -3661,10 +3718,14 @@ export async function diagnoseLiveFormSubmitGate(page, options = {}) {
         blockingReasons.push(`readiness-blocking-fields:${readiness.blockingFieldCount}`);
     if (validation && validation.inlineErrors.length > 0)
         blockingReasons.push(`validation-errors:${validation.inlineErrors.length}`);
+    const blockingFields = readiness?.fields.filter((field) => field.isBlocking) ?? [];
+    const validationErrors = validation?.inlineErrors ?? [];
     return {
         selector,
         ...dom,
         blockingReasons,
+        blockingFields,
+        validationErrors,
         ...(readiness ? { readiness } : {}),
         ...(validation ? { validation } : {}),
         ready: blockingReasons.length === 0,
@@ -3737,6 +3798,70 @@ export async function diagnoseLiveFormLayout(page, options = {}) {
         };
     }, options);
 }
+export async function diagnoseLiveFormIframeLayout(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("diagnoseLiveFormIframeLayout requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((layoutOptions) => {
+        const iframe = document.querySelector(layoutOptions.iframeSelector);
+        const viewportWidth = document.documentElement.clientWidth;
+        const viewportHeight = document.documentElement.clientHeight;
+        const issues = [];
+        if (!(iframe instanceof HTMLElement)) {
+            return {
+                iframeSelector: layoutOptions.iframeSelector,
+                exists: false,
+                viewportWidth,
+                viewportHeight,
+                rect: null,
+                issues: [{
+                        kind: "horizontal-overflow",
+                        selector: layoutOptions.iframeSelector,
+                        message: "Iframe element was not found.",
+                    }],
+                ok: false,
+            };
+        }
+        const rect = iframe.getBoundingClientRect();
+        if (rect.left < -1 || rect.right > viewportWidth + 1) {
+            issues.push({
+                kind: "horizontal-overflow",
+                selector: layoutOptions.iframeSelector,
+                message: "Iframe extends outside the viewport horizontally.",
+                detail: { left: Math.round(rect.left), right: Math.round(rect.right), viewportWidth },
+            });
+        }
+        if (layoutOptions.expectedMaxWidth !== undefined && rect.width > layoutOptions.expectedMaxWidth + 1) {
+            issues.push({
+                kind: "horizontal-overflow",
+                selector: layoutOptions.iframeSelector,
+                message: `Iframe width ${Math.round(rect.width)}px exceeds expected maximum ${layoutOptions.expectedMaxWidth}px.`,
+                detail: { width: Math.round(rect.width), expectedMaxWidth: layoutOptions.expectedMaxWidth },
+            });
+        }
+        if (layoutOptions.expectedMaxHeight !== undefined && rect.height > layoutOptions.expectedMaxHeight + 1) {
+            issues.push({
+                kind: "nested-scroll",
+                selector: layoutOptions.iframeSelector,
+                message: `Iframe height ${Math.round(rect.height)}px exceeds expected maximum ${layoutOptions.expectedMaxHeight}px.`,
+                detail: { height: Math.round(rect.height), expectedMaxHeight: layoutOptions.expectedMaxHeight },
+            });
+        }
+        return {
+            iframeSelector: layoutOptions.iframeSelector,
+            exists: true,
+            viewportWidth,
+            viewportHeight,
+            rect: { width: Math.round(rect.width), height: Math.round(rect.height), top: Math.round(rect.top), left: Math.round(rect.left) },
+            issues,
+            ok: issues.length === 0,
+        };
+    }, options);
+}
+function endCascadePhase(name, startedAt, ok) {
+    const endedAt = Date.now();
+    return { name, startedAt, endedAt, durationMs: endedAt - startedAt, ok };
+}
 export async function assertLiveFormChangeCascade(page, options) {
     const transaction = await performLiveFormFieldTransaction(page, {
         ...(options.trigger.transaction ?? {}),
@@ -3766,6 +3891,136 @@ export async function assertLiveFormChangeCascade(page, options) {
     }
     return { transaction, values, settled };
 }
+export async function traceLiveFormChangeCascade(page, options) {
+    const totalStartedAt = Date.now();
+    const phases = [];
+    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 values = [];
+    const valuesStartedAt = Date.now();
+    for (const expected of options.expectValues ?? []) {
+        values.push(await waitForLiveFormFieldValue(page, expected));
+    }
+    phases.push(endCascadePhase("values", valuesStartedAt, values.every((value) => value.valueMatched !== false)));
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []).map((target) => ({ ...target, visible: true })),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const settleStartedAt = Date.now();
+    const settled = await waitForLiveFormLogicSettled(page, {
+        quiet: options.quiet ?? false,
+        ...(visibilityTargets.length === 0 ? {} : { visibility: { targets: visibilityTargets } }),
+        ...(options.validation === undefined ? {} : { validation: options.validation }),
+    });
+    phases.push(endCascadePhase("settled", settleStartedAt, settled.settled));
+    if (!settled.settled || values.some((value) => value.valueMatched === false)) {
+        throw new Error("Expected live form change cascade did not settle into the requested state.");
+    }
+    const endedAt = Date.now();
+    return {
+        label: options.label ?? "live-form-change-cascade",
+        transaction,
+        values,
+        settled,
+        phases,
+        totalMs: endedAt - totalStartedAt,
+    };
+}
+export async function runLiveFormRapidFieldChangeSequence(page, options) {
+    const transactions = [];
+    for (const write of options.writes) {
+        transactions.push(await performLiveFormFieldTransaction(page, {
+            ...(write.transaction ?? {}),
+            write: {
+                ...(write.write ?? {}),
+                target: write.target,
+                value: write.value,
+                notify: write.write?.notify ?? true,
+            },
+            ...(write.fieldKind === undefined ? {} : { fieldKind: write.fieldKind }),
+        }));
+    }
+    const quietOptions = options.afterQuiet === false ? undefined : options.afterQuiet === true ? {} : options.afterQuiet;
+    const validationOptions = options.afterValidation === false ? undefined : options.afterValidation === true ? { expectNoErrors: true } : options.afterValidation;
+    const quiet = quietOptions ? await waitForLiveFormQuiet(page, quietOptions) : undefined;
+    const validation = validationOptions ? await waitForLiveFormValidationSettled(page, validationOptions) : undefined;
+    const finalByTarget = new Map();
+    for (const write of options.writes) {
+        finalByTarget.set(liveFormFieldTargetKey(write.target) ?? JSON.stringify(write.target), { target: write.target, value: write.value });
+    }
+    const finalValues = [];
+    for (const expected of finalByTarget.values()) {
+        finalValues.push(await waitForLiveFormFieldValue(page, { target: expected.target, expectedValue: expected.value }));
+    }
+    return {
+        transactions,
+        ...(quiet ? { quiet } : {}),
+        ...(validation ? { validation } : {}),
+        finalValues,
+        ok: transactions.every((transaction) => transaction.write.valueMatched !== false) &&
+            (quiet?.quiet ?? true) &&
+            ((validation?.inlineErrors.length ?? 0) === 0) &&
+            finalValues.every((value) => value.valueMatched !== false),
+    };
+}
+export async function waitForLiveFormRerenderSettled(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("waitForLiveFormRerenderSettled requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((rerenderOptions) => new Promise((resolve) => {
+        const rootSelector = rerenderOptions.rootSelector ?? "body";
+        const root = document.querySelector(rootSelector);
+        const startedAt = Date.now();
+        const quietMs = rerenderOptions.quietMs ?? 150;
+        const timeoutMs = rerenderOptions.timeoutMs ?? 2000;
+        let mutationCount = 0;
+        let quietTimer;
+        let timeoutTimer;
+        let observer;
+        const finish = (quiet) => {
+            if (observer)
+                observer.disconnect();
+            if (quietTimer !== undefined)
+                window.clearTimeout(quietTimer);
+            if (timeoutTimer !== undefined)
+                window.clearTimeout(timeoutTimer);
+            const elapsedMs = Date.now() - startedAt;
+            resolve({
+                rootSelector,
+                mutationCount,
+                elapsedMs,
+                quiet,
+                ok: quiet && mutationCount >= (rerenderOptions.expectedMinMutations ?? 0),
+            });
+        };
+        if (!root) {
+            finish(false);
+            return;
+        }
+        const armQuietTimer = () => {
+            if (quietTimer !== undefined)
+                window.clearTimeout(quietTimer);
+            quietTimer = window.setTimeout(() => finish(true), quietMs);
+        };
+        observer = new MutationObserver((records) => {
+            mutationCount += records.length;
+            armQuietTimer();
+        });
+        observer.observe(root, { attributes: true, childList: true, subtree: true });
+        timeoutTimer = window.setTimeout(() => finish(false), timeoutMs);
+        armQuietTimer();
+    }), options);
+}
 export async function runFormstackIframePrefillSmoke(page, options) {
     const bridge = await sendFormstackIframePrefillMessage(page, options);
     const responseData = bridge.response.record?.data;
@@ -3773,6 +4028,16 @@ export async function runFormstackIframePrefillSmoke(page, options) {
     const ok = bridge.posted && bridge.response.matched && (options.expectResponseOk === false || responseOk);
     return { bridge, ok };
 }
+export async function runFormstackIframePrefillScenario(page, options) {
+    const prefill = await runFormstackIframePrefillSmoke(page, options);
+    const layoutOptions = options.layout === true ? { iframeSelector: options.iframeSelector } : options.layout || undefined;
+    const layout = layoutOptions ? await diagnoseLiveFormIframeLayout(page, layoutOptions) : undefined;
+    return {
+        prefill,
+        ...(layout ? { layout } : {}),
+        ok: prefill.ok && (layout?.ok ?? true),
+    };
+}
 export async function assertLiveFormConditionalLogic(page, options) {
     const transaction = await performLiveFormFieldTransaction(page, {
         ...(options.trigger.transaction ?? {}),