@redrockswebdevelopment/formstack-form-testing 0.1.19 → 0.1.20

package/dist/index.js

@@ -3242,6 +3242,7 @@ export async function answerProgressiveLiveFormField(page, options) {
         },
         ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
         waitForEvent: options.waitForEvent ?? true,
+        dispatchDomEvents: options.dispatchDomEvents ?? "auto",
         afterQuiet: options.afterQuiet ?? true,
         ...(validationOptions ? { afterValidation: validationOptions } : {}),
     });
@@ -3454,6 +3455,324 @@ export async function runLiveFormSampleSmoke(page, definition, sampleValues, opt
         ok: (quiet?.quiet ?? true) && (afterReadiness?.isReady ?? true) && ((validation?.inlineErrors.length ?? 0) === 0) && !(coverage?.hasUnknownFields ?? false),
     };
 }
+function sampleValueShapeIssue(key, kind, value) {
+    const objectValue = value && typeof value === "object" ? value : null;
+    if (["radio", "select", "rating"].includes(kind ?? "") && (objectValue === null || typeof objectValue.value !== "string")) {
+        return {
+            kind: "invalid-value-shape",
+            key,
+            message: `Sample value for ${key} should be an object with a string value property.`,
+            detail: { kind },
+        };
+    }
+    if (["checkbox", "matrix"].includes(kind ?? "") && objectValue === null) {
+        return {
+            kind: "invalid-value-shape",
+            key,
+            message: `Sample value for ${key} should be an object payload for ${kind} fields.`,
+            detail: { kind },
+        };
+    }
+    if (kind === "name" && objectValue === null) {
+        return {
+            kind: "invalid-value-shape",
+            key,
+            message: `Sample value for ${key} should be an object with name subfields.`,
+            detail: { kind },
+        };
+    }
+    return null;
+}
+export function validateLiveFormSampleProfile(definition, sampleValues, options = {}) {
+    const samples = sampleValues;
+    const issues = [];
+    const unknownKeys = [];
+    const missingRequiredKeys = [];
+    const duplicateTargetKeys = [];
+    const targetOwners = new Map();
+    for (const key of Object.keys(samples)) {
+        if (!(key in definition)) {
+            unknownKeys.push(key);
+            issues.push({ kind: "unknown-sample-key", key, message: `Sample value key "${key}" does not exist in the field definition.` });
+        }
+    }
+    for (const [key, config] of Object.entries(definition)) {
+        const target = targetFromHandleConfig(config);
+        const targetKey = liveFormFieldTargetKey(target);
+        if (targetKey) {
+            const owner = targetOwners.get(targetKey);
+            if (owner && Object.hasOwn(samples, key) && Object.hasOwn(samples, owner) && options.allowDuplicateTargets !== true) {
+                duplicateTargetKeys.push(key);
+                issues.push({
+                    kind: "duplicate-target",
+                    key,
+                    target,
+                    message: `Sample value key "${key}" points to the same generated target as "${owner}".`,
+                    detail: { originalKey: owner },
+                });
+            }
+            else if (!owner) {
+                targetOwners.set(targetKey, key);
+            }
+        }
+        if (config.required === true && !Object.hasOwn(samples, key)) {
+            missingRequiredKeys.push(key);
+            issues.push({ kind: "missing-required-sample", key, target, message: `Required field "${key}" does not have a sample value.` });
+        }
+        if (!Object.hasOwn(samples, key))
+            continue;
+        if (options.requiredOnly === true && config.required !== true)
+            continue;
+        const value = samples[key];
+        const shapeIssue = sampleValueShapeIssue(key, config.kind, value);
+        if (shapeIssue)
+            issues.push({ ...shapeIssue, target });
+        const allowedValues = options.optionValues?.[key];
+        if (!allowedValues || !value || typeof value !== "object")
+            continue;
+        const valueObject = value;
+        if (typeof valueObject.value === "string" && !allowedValues.includes(valueObject.value)) {
+            issues.push({
+                kind: "invalid-option-value",
+                key,
+                target,
+                message: `Sample value "${valueObject.value}" is not in the allowed option values for "${key}".`,
+                detail: { allowedValues },
+            });
+        }
+        if (Array.isArray(valueObject.values)) {
+            const invalid = valueObject.values.filter((entry) => typeof entry === "string" && !allowedValues.includes(entry));
+            if (invalid.length > 0) {
+                issues.push({
+                    kind: "invalid-option-values",
+                    key,
+                    target,
+                    message: `Sample values for "${key}" include values outside the allowed options: ${invalid.join(", ")}.`,
+                    detail: { allowedValues, invalid },
+                });
+            }
+        }
+    }
+    return {
+        issues,
+        unknownKeys,
+        missingRequiredKeys,
+        duplicateTargetKeys,
+        ok: issues.length === 0,
+    };
+}
+export function createLiveFormProgressiveSamplePlan(definition, sampleValues, options = {}) {
+    const basePlan = createLiveFormSampleFillPlan(definition, sampleValues, options);
+    const configuredSteps = new Map((options.steps ?? []).map((step) => [step.key, step]));
+    const orderedKeys = options.steps?.map((step) => step.key) ?? basePlan.map((entry) => entry.key);
+    const baseByKey = new Map(basePlan.map((entry) => [entry.key, entry]));
+    const plan = [];
+    for (const key of orderedKeys) {
+        const base = baseByKey.get(key);
+        if (!base)
+            continue;
+        const step = configuredSteps.get(key);
+        plan.push({
+            ...base,
+            ...(step?.expectVisibleAfter === undefined ? {} : { expectVisibleAfter: step.expectVisibleAfter }),
+            ...(step?.expectHiddenAfter === undefined ? {} : { expectHiddenAfter: step.expectHiddenAfter }),
+            ...(step?.expectResetAfter === undefined ? {} : { expectResetAfter: step.expectResetAfter }),
+            ...(step?.continueSelector === undefined ? {} : { continueSelector: step.continueSelector }),
+            ...(step?.transaction === undefined ? {} : { transaction: step.transaction }),
+        });
+    }
+    return plan;
+}
+export async function runLiveFormProgressiveSampleFlow(page, definition, sampleValues, options = {}) {
+    const plan = createLiveFormProgressiveSamplePlan(definition, sampleValues, options);
+    const answers = [];
+    for (const step of plan) {
+        answers.push(await answerProgressiveLiveFormField(page, {
+            ...(options.defaultTransaction ?? {}),
+            ...(step.transaction ?? {}),
+            target: step.target,
+            value: step.value,
+            ...(step.fieldKind === undefined ? {} : { fieldKind: step.fieldKind }),
+            ...(step.expectVisibleAfter === undefined ? {} : { expectVisible: step.expectVisibleAfter.map((target) => ({ ...target, visible: true })) }),
+            ...(step.expectHiddenAfter === undefined ? {} : { expectHidden: step.expectHiddenAfter }),
+            ...(step.expectResetAfter === undefined ? {} : { expectReset: step.expectResetAfter }),
+        }));
+        if (step.continueSelector) {
+            await page.locator(step.continueSelector).first().click();
+        }
+    }
+    const quietOptions = options.afterQuiet === false ? undefined : options.afterQuiet === true ? {} : options.afterQuiet;
+    const readinessOptions = createSampleSmokeReadinessOptions(definition, options.afterReadiness, false);
+    const validationOptions = options.afterValidation === false ? undefined : options.afterValidation === true ? { expectNoErrors: true } : options.afterValidation;
+    const quiet = quietOptions ? await waitForLiveFormQuiet(page, quietOptions) : undefined;
+    const readiness = readinessOptions ? await waitForLiveFormReady(page, readinessOptions) : undefined;
+    const validation = validationOptions ? await waitForLiveFormValidationSettled(page, validationOptions) : undefined;
+    return {
+        plan,
+        answers,
+        ...(quiet ? { quiet } : {}),
+        ...(readiness ? { readiness } : {}),
+        ...(validation ? { validation } : {}),
+        ok: answers.every((answer) => (answer.visibility?.matched ?? true) &&
+            answer.resetValues.every((value) => value.valueMatched !== false) &&
+            ((answer.validation?.inlineErrors.length ?? 0) === 0)) && (quiet?.quiet ?? true) && (readiness?.isReady ?? true) && ((validation?.inlineErrors.length ?? 0) === 0),
+    };
+}
+export async function diagnoseLiveFormSubmitGate(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("diagnoseLiveFormSubmitGate requires a Playwright page with evaluate().");
+    }
+    const selector = options.selector ?? ".fsSubmitButton, [type=submit], .fsSubmit";
+    const dom = await page.evaluate((submitSelector) => {
+        const element = document.querySelector(submitSelector);
+        if (!(element instanceof HTMLElement)) {
+            return {
+                exists: false,
+                visible: null,
+                disabled: null,
+                ariaDisabled: null,
+                dataReady: null,
+                hiddenReason: "missing",
+            };
+        }
+        const style = getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        const disabled = "disabled" in element ? Boolean(element.disabled) : element.getAttribute("disabled") !== null;
+        const ariaDisabled = element.getAttribute("aria-disabled") === "true";
+        const dataReady = element.getAttribute("data-chat-submit-ready") ?? element.getAttribute("data-submit-ready");
+        const visible = style.display !== "none" && style.visibility !== "hidden" && Number(style.opacity) !== 0 && rect.width > 0 && rect.height > 0;
+        const hiddenReason = visible ? null : style.display === "none" ? "display-none" : style.visibility === "hidden" ? "visibility-hidden" : rect.width <= 0 || rect.height <= 0 ? "zero-size" : "transparent";
+        return { exists: true, visible, disabled, ariaDisabled, dataReady, hiddenReason };
+    }, selector);
+    const readiness = options.readiness ? await readLiveFormReadiness(page, options.readiness) : undefined;
+    const validation = options.validation ? await readLiveFormValidationState(page, typeof options.validation === "object" ? options.validation : {}) : undefined;
+    const blockingReasons = [];
+    if (!dom.exists)
+        blockingReasons.push("submit-control-missing");
+    if (dom.visible === false)
+        blockingReasons.push(`submit-control-hidden:${dom.hiddenReason ?? "unknown"}`);
+    if (dom.disabled === true)
+        blockingReasons.push("submit-control-disabled");
+    if (dom.ariaDisabled === true)
+        blockingReasons.push("submit-control-aria-disabled");
+    if (dom.dataReady === "false")
+        blockingReasons.push("submit-control-data-ready-false");
+    if (readiness && !readiness.isReady)
+        blockingReasons.push(`readiness-blocking-fields:${readiness.blockingFieldCount}`);
+    if (validation && validation.inlineErrors.length > 0)
+        blockingReasons.push(`validation-errors:${validation.inlineErrors.length}`);
+    return {
+        selector,
+        ...dom,
+        blockingReasons,
+        ...(readiness ? { readiness } : {}),
+        ...(validation ? { validation } : {}),
+        ready: blockingReasons.length === 0,
+    };
+}
+export async function diagnoseLiveFormLayout(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("diagnoseLiveFormLayout requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((layoutOptions) => {
+        const rootSelector = layoutOptions.rootSelector ?? "body";
+        const minTapTargetPx = layoutOptions.minTapTargetPx ?? 44;
+        const root = document.querySelector(rootSelector);
+        const viewportWidth = document.documentElement.clientWidth;
+        const bodyScrollWidth = document.documentElement.scrollWidth;
+        const rootScrollWidth = root instanceof HTMLElement ? root.scrollWidth : null;
+        const rootClientWidth = root instanceof HTMLElement ? root.clientWidth : null;
+        const issues = [];
+        if (bodyScrollWidth > viewportWidth + 1) {
+            issues.push({
+                kind: "horizontal-overflow",
+                selector: "html",
+                message: `Document scroll width ${bodyScrollWidth}px exceeds viewport width ${viewportWidth}px.`,
+                detail: { bodyScrollWidth, viewportWidth },
+            });
+        }
+        if (rootScrollWidth !== null && rootClientWidth !== null && rootScrollWidth > rootClientWidth + 1) {
+            issues.push({
+                kind: "horizontal-overflow",
+                selector: rootSelector,
+                message: `Root scroll width ${rootScrollWidth}px exceeds client width ${rootClientWidth}px.`,
+                detail: { rootScrollWidth, rootClientWidth },
+            });
+        }
+        const scrollCandidates = Array.from(document.querySelectorAll(layoutOptions.includeSelectors?.join(",") ?? `${rootSelector} *`));
+        for (const element of scrollCandidates) {
+            if (!(element instanceof HTMLElement))
+                continue;
+            const style = getComputedStyle(element);
+            const rect = element.getBoundingClientRect();
+            const selector = element.id ? `#${CSS.escape(element.id)}` : element.getAttribute("data-internal-label") ? `[data-internal-label="${CSS.escape(element.getAttribute("data-internal-label") ?? "")}"]` : element.tagName.toLowerCase();
+            if ((style.overflowY === "auto" || style.overflowY === "scroll") && element.scrollHeight > element.clientHeight + 1) {
+                issues.push({
+                    kind: "nested-scroll",
+                    selector,
+                    message: "Element has internal vertical scrolling.",
+                    detail: { scrollHeight: element.scrollHeight, clientHeight: element.clientHeight },
+                });
+            }
+            if (["BUTTON", "A", "INPUT", "SELECT", "TEXTAREA"].includes(element.tagName) && rect.width > 0 && rect.height > 0 && (rect.width < minTapTargetPx || rect.height < minTapTargetPx)) {
+                issues.push({
+                    kind: "small-tap-target",
+                    selector,
+                    message: `Tap target is smaller than ${minTapTargetPx}px.`,
+                    detail: { width: Math.round(rect.width), height: Math.round(rect.height), minTapTargetPx },
+                });
+            }
+        }
+        return {
+            rootSelector,
+            viewportWidth,
+            bodyScrollWidth,
+            rootScrollWidth,
+            rootClientWidth,
+            issues,
+            hasHorizontalOverflow: issues.some((issue) => issue.kind === "horizontal-overflow"),
+            hasNestedScroll: issues.some((issue) => issue.kind === "nested-scroll"),
+            hasSmallTapTargets: issues.some((issue) => issue.kind === "small-tap-target"),
+            ok: issues.length === 0,
+        };
+    }, options);
+}
+export async function assertLiveFormChangeCascade(page, options) {
+    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 }),
+    });
+    const values = [];
+    for (const expected of options.expectValues ?? []) {
+        values.push(await waitForLiveFormFieldValue(page, expected));
+    }
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []).map((target) => ({ ...target, visible: true })),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const settled = await waitForLiveFormLogicSettled(page, {
+        quiet: options.quiet ?? false,
+        ...(visibilityTargets.length === 0 ? {} : { visibility: { targets: visibilityTargets } }),
+        ...(options.validation === undefined ? {} : { validation: options.validation }),
+    });
+    if (!settled.settled || values.some((value) => value.valueMatched === false)) {
+        throw new Error("Expected live form change cascade did not settle into the requested state.");
+    }
+    return { transaction, values, settled };
+}
+export async function runFormstackIframePrefillSmoke(page, options) {
+    const bridge = await sendFormstackIframePrefillMessage(page, options);
+    const responseData = bridge.response.record?.data;
+    const responseOk = Boolean(responseData && typeof responseData === "object" && Reflect.get(responseData, "ok") === true);
+    const ok = bridge.posted && bridge.response.matched && (options.expectResponseOk === false || responseOk);
+    return { bridge, ok };
+}
 export async function assertLiveFormConditionalLogic(page, options) {
     const transaction = await performLiveFormFieldTransaction(page, {
         ...(options.trigger.transaction ?? {}),