@redrockswebdevelopment/formstack-form-testing 0.1.1 → 0.1.2

package/dist/index.js

@@ -16,6 +16,274 @@ export class FormScenarioRunError extends Error {
         this.result = result;
     }
 }
+export const liveFormFieldTypeCoverage = {
+    address: {
+        kind: "address",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Compound address values can be written through Live Form API, while layout and subfield UX should be asserted through DOM controls.",
+        recommendedHelpers: ["buildLiveFormAddressValue", "setLiveFormFieldValueTransaction", "fillAddress", "readLiveFormDomFieldState"],
+    },
+    checkbox: {
+        kind: "checkbox",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Checkbox values are stable when using option values. Multi-select UX should still dispatch DOM events or use DOM interaction.",
+        recommendedHelpers: ["buildLiveFormCheckboxValue", "setLiveFormFieldValueTransaction", "setCheckboxes", "waitForLiveFormQuiet"],
+    },
+    date: {
+        kind: "date",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Date API state can be set reliably, but split/calendar renderer variants should be verified through DOM assertions.",
+        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormFieldValueTransaction", "fillDateTime", "readLiveFormDomFieldState"],
+    },
+    datetime: {
+        kind: "datetime",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Date/time API state can be set, but visible split controls may lag or vary by renderer.",
+        recommendedHelpers: ["buildLiveFormDateTimeValue", "setLiveFormFieldValueTransaction", "fillDateTime", "readLiveFormDomFieldState"],
+    },
+    description: {
+        kind: "description",
+        strategy: "assertion-only",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Description fields do not collect user values; test rendered content, visibility, and styling.",
+        recommendedHelpers: ["snapshotLiveFormDomFields", "waitForLiveFormVisibility"],
+    },
+    embed: {
+        kind: "embed",
+        strategy: "assertion-only",
+        apiWrite: false,
+        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"],
+    },
+    email: {
+        kind: "email",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Email fields behave like text fields with validation-specific assertions.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillEmail", "waitForLiveFormValidationState"],
+    },
+    file: {
+        kind: "file",
+        strategy: "dom-only",
+        apiWrite: false,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "File fields must be tested through browser file upload controls, not generic Live Form API setValue payloads.",
+        recommendedHelpers: ["uploadFile", "liveFormFieldRecipes.uploadFileDom", "readLiveFormDomFieldState"],
+    },
+    matrix: {
+        kind: "matrix",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Matrix selections can be written by row/column labels or selected through DOM cells.",
+        recommendedHelpers: ["buildLiveFormMatrixValue", "setLiveFormFieldValueTransaction", "selectMatrixCell", "readLiveFormDomFieldState"],
+    },
+    name: {
+        kind: "name",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Name compound fields support direct API values and stable subfield DOM automation.",
+        recommendedHelpers: ["buildLiveFormNameValue", "setLiveFormFieldValueTransaction", "fillName", "readLiveFormReadiness"],
+    },
+    number: {
+        kind: "number",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Number fields use simple value payloads; use validation assertions for numeric constraints.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillNumber", "waitForLiveFormValidationState"],
+    },
+    pagebreak: {
+        kind: "pagebreak",
+        strategy: "layout-only",
+        apiWrite: false,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Page breaks do not collect values; test navigation, visible page state, and progress UI.",
+        recommendedHelpers: ["clickNext", "clickPrevious", "waitForLiveFormVisibility"],
+    },
+    payment: {
+        kind: "payment",
+        strategy: "excluded",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: false,
+        paymentRisk: true,
+        reason: "Payment fields are intentionally excluded from generic helpers because custom embedded code can trigger Formstack attestation and compliance review.",
+        recommendedHelpers: ["createFormBrowserMonitor"],
+    },
+    phone: {
+        kind: "phone",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Phone fields use simple value payloads; use DOM and validation assertions for formatting behavior.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillPhone", "waitForLiveFormValidationState"],
+    },
+    product: {
+        kind: "product",
+        strategy: "api-with-dom-caveats",
+        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"],
+    },
+    radio: {
+        kind: "radio",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Radio fields are stable when using option values. Dispatch DOM change for custom scripts.",
+        recommendedHelpers: ["buildLiveFormChoiceValue", "setLiveFormFieldValueTransaction", "chooseRadio", "waitForLiveFormQuiet"],
+    },
+    rating: {
+        kind: "rating",
+        strategy: "api-with-dom-caveats",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Rating values can be written through API, but visual stars/buttons should be asserted separately.",
+        recommendedHelpers: ["buildLiveFormRatingValue", "setLiveFormFieldValueTransaction", "setRating", "readLiveFormDomFieldState"],
+    },
+    section: {
+        kind: "section",
+        strategy: "layout-only",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: true,
+        reason: "Sections group content and logic visibility; test rendered content and conditional visibility.",
+        recommendedHelpers: ["snapshotLiveFormDomFields", "waitForLiveFormVisibility"],
+    },
+    select: {
+        kind: "select",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Select fields support stable option values through API or DOM select operations.",
+        recommendedHelpers: ["buildLiveFormSelectValue", "setLiveFormFieldValueTransaction", "selectOption", "readLiveFormDomFieldState"],
+    },
+    signature: {
+        kind: "signature",
+        strategy: "dom-only",
+        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"],
+    },
+    textarea: {
+        kind: "textarea",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Textarea fields use simple value payloads and stable DOM fill operations.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillTextarea", "readLiveFormDomFieldState"],
+    },
+    text: {
+        kind: "text",
+        strategy: "api-safe",
+        apiWrite: true,
+        domInteraction: true,
+        domAssertion: true,
+        reason: "Text fields use simple value payloads and stable DOM fill operations.",
+        recommendedHelpers: ["setLiveFormFieldValueTransaction", "fillText", "readLiveFormDomFieldState"],
+    },
+    unknown: {
+        kind: "unknown",
+        strategy: "excluded",
+        apiWrite: false,
+        domInteraction: false,
+        domAssertion: false,
+        reason: "Unknown fields need discovery before using generic automation.",
+        recommendedHelpers: ["discoverLiveFormFieldShapes", "snapshotLiveFormDomFields"],
+    },
+};
+export function getLiveFormFieldTypeCoverage(kind) {
+    return liveFormFieldTypeCoverage[kind];
+}
+export function summarizeLiveFormFieldCoverage(reportOrFields) {
+    const fields = "fields" in reportOrFields ? reportOrFields.fields : reportOrFields;
+    const countsByKind = {};
+    const fieldsWithCoverage = fields.map((field) => {
+        countsByKind[field.inferredKind] = (countsByKind[field.inferredKind] ?? 0) + 1;
+        return { ...field, coverage: getLiveFormFieldTypeCoverage(field.inferredKind) };
+    });
+    const uncovered = fields.filter((field) => field.inferredKind === "unknown");
+    const paymentFields = fields.filter((field) => field.inferredKind === "payment");
+    return {
+        fields: fieldsWithCoverage,
+        countsByKind,
+        uncovered,
+        paymentFields,
+        hasUnknownFields: uncovered.length > 0,
+        hasPaymentFields: paymentFields.length > 0,
+    };
+}
+export async function readLiveFormFieldCoverage(page, options = {}) {
+    return summarizeLiveFormFieldCoverage(await discoverLiveFormFieldShapes(page, options));
+}
+function formatCoverageField(field) {
+    return `${field.inferredKind}:${field.internalLabel ?? field.domId ?? "unlabeled"}`;
+}
+export function assertLiveFormFieldCoverage(report, options = {}) {
+    const failures = [];
+    if (!options.allowUnknown && report.hasUnknownFields) {
+        failures.push(`unknown fields: ${report.uncovered.map(formatCoverageField).join(", ")}`);
+    }
+    if (!options.allowPayment && report.hasPaymentFields) {
+        failures.push(`payment fields: ${report.paymentFields.map(formatCoverageField).join(", ")}`);
+    }
+    const allowedStrategies = new Set(options.allowedStrategies ?? []);
+    if (allowedStrategies.size > 0) {
+        const invalid = report.fields.filter((field) => !allowedStrategies.has(field.coverage.strategy));
+        if (invalid.length > 0) {
+            failures.push(`fields outside allowed strategies: ${invalid.map((field) => `${formatCoverageField(field)}=${field.coverage.strategy}`).join(", ")}`);
+        }
+    }
+    const disallowedStrategies = new Set(options.disallowedStrategies ?? []);
+    if (disallowedStrategies.size > 0) {
+        const invalid = report.fields.filter((field) => disallowedStrategies.has(field.coverage.strategy));
+        if (invalid.length > 0) {
+            failures.push(`fields using disallowed strategies: ${invalid.map((field) => `${formatCoverageField(field)}=${field.coverage.strategy}`).join(", ")}`);
+        }
+    }
+    for (const requiredKind of options.requiredKinds ?? []) {
+        if ((report.countsByKind[requiredKind] ?? 0) === 0) {
+            failures.push(`missing required field kind: ${requiredKind}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(`Live form field coverage assertion failed: ${failures.join("; ")}`);
+    }
+}
 function matchesPattern(value, pattern) {
     return typeof pattern === "string" ? value.includes(pattern) : pattern.test(value);
 }
@@ -503,6 +771,8 @@ export async function waitForLiveFormQuiet(page, options = {}) {
         const waitForApiTimeoutMs = quietOptions.waitForApiTimeoutMs ?? 2_000;
         const eventTypes = quietOptions.eventTypes ?? ["input", "change", "blur", "click", "submit"];
         const formEventTypes = quietOptions.formEventTypes ?? ["change", "calculations-complete", "validation-complete", "submit", "error"];
+        const observeMutations = quietOptions.observeMutations ?? true;
+        const mutationSelector = quietOptions.mutationSelector ?? "form, [id^='fsForm-'], body";
         const includeEvents = quietOptions.includeEvents ?? true;
         const events = [];
         let lastEventAt = now();
@@ -544,6 +814,31 @@ export async function waitForLiveFormQuiet(page, options = {}) {
         };
         for (const eventType of eventTypes)
             document.addEventListener(eventType, domListener, true);
+        const mutationTarget = document.querySelector(mutationSelector) ?? document.body;
+        const mutationObserver = observeMutations && typeof MutationObserver !== "undefined" && mutationTarget
+            ? new MutationObserver((mutations) => {
+                const mutationTypes = [...new Set(mutations.map((mutation) => mutation.type))];
+                const changedFieldLabels = [
+                    ...new Set(mutations
+                        .flatMap((mutation) => [mutation.target, ...Array.from(mutation.addedNodes), ...Array.from(mutation.removedNodes)])
+                        .filter((node) => node instanceof Element)
+                        .map((element) => element.closest("[data-internal-label]")?.getAttribute("data-internal-label"))
+                        .filter((label) => Boolean(label))),
+                ].slice(0, 20);
+                record("mutation", "mutation", {
+                    count: mutations.length,
+                    types: mutationTypes,
+                    changedFieldLabels,
+                });
+            })
+            : null;
+        mutationObserver?.observe(mutationTarget, {
+            attributes: true,
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributeFilter: ["class", "style", "aria-invalid", "hidden", "data-internal-label"],
+        });
         const formEventListeners = apiAvailable && form && typeof form === "object"
             ? formEventTypes.map((type) => ({
                 type,
@@ -592,6 +887,7 @@ export async function waitForLiveFormQuiet(page, options = {}) {
         finally {
             for (const eventType of eventTypes)
                 document.removeEventListener(eventType, domListener, true);
+            mutationObserver?.disconnect();
             if (typeof unregisterFormEventListener === "function") {
                 for (const listener of formEventListeners)
                     Reflect.apply(unregisterFormEventListener, form, [listener]);
@@ -1375,10 +1671,27 @@ export async function discoverLiveFormFieldShapes(page, options = {}) {
             const classes = element.className.toString().toLowerCase();
             const types = new Set(controls.map((control) => control.type ?? control.tagName));
             const internalLabel = element.getAttribute("data-internal-label")?.toLowerCase() ?? "";
+            const id = element.getAttribute("id")?.toLowerCase() ?? "";
+            const dataTestId = element.getAttribute("data-testid")?.toLowerCase() ?? "";
+            if (internalLabel.includes("payment") ||
+                internalLabel.includes("credit_card") ||
+                internalLabel.includes("credit-card") ||
+                classes.includes("payment") ||
+                text.includes("credit card") ||
+                controls.some((control) => control.name?.toLowerCase().includes("payment") || control.name?.toLowerCase().includes("credit"))) {
+                return "payment";
+            }
             if (internalLabel.includes("code_embed") || text.startsWith(":root{") || text.includes("<script"))
                 return "embed";
-            if (controls.length === 0)
+            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")) {
+                    return "description";
+                }
                 return "section";
+            }
             if (classes.includes("matrix") || internalLabel.includes("matrix") || element.querySelector("[id^='matrix-row-'], table"))
                 return "matrix";
             if (classes.includes("rating") || internalLabel.includes("rating"))
@@ -1407,6 +1720,8 @@ export async function discoverLiveFormFieldShapes(page, options = {}) {
                 return "phone";
             if (types.has("number") || internalLabel.includes("number"))
                 return "number";
+            if (internalLabel.includes("date_time") || internalLabel.includes("datetime") || text.includes("am/pm") || text.includes("minutes"))
+                return "datetime";
             if (types.has("date") || internalLabel.includes("date"))
                 return "date";
             if (types.has("text"))
@@ -2074,6 +2389,85 @@ export async function setLiveFormFieldValueTransaction(page, options) {
         ...(domFields ? { domFields } : {}),
     };
 }
+export async function setLiveFormFieldValueTimedTransaction(page, options) {
+    const timeline = [];
+    const startedAt = Date.now();
+    const runPhase = async (name, run) => {
+        const phaseStartedAt = Date.now();
+        try {
+            const result = await run();
+            const endedAt = Date.now();
+            timeline.push({
+                name,
+                startedAtMs: phaseStartedAt - startedAt,
+                endedAtMs: endedAt - startedAt,
+                durationMs: endedAt - phaseStartedAt,
+                ok: true,
+            });
+            return result;
+        }
+        catch (error) {
+            const endedAt = Date.now();
+            timeline.push({
+                name,
+                startedAtMs: phaseStartedAt - startedAt,
+                endedAtMs: endedAt - startedAt,
+                durationMs: endedAt - phaseStartedAt,
+                ok: false,
+                detail: { message: error instanceof Error ? error.message : String(error) },
+            });
+            throw error;
+        }
+    };
+    const beforeReadiness = options.beforeReadiness
+        ? await runPhase("before-readiness", () => readLiveFormReadiness(page, options.beforeReadiness))
+        : undefined;
+    const beforeDomFields = options.beforeSnapshot
+        ? await runPhase("before-snapshot", () => snapshotLiveFormDomFields(page, typeof options.beforeSnapshot === "object" ? options.beforeSnapshot : {}))
+        : undefined;
+    const shouldWaitForEvent = options.waitForEvent === true || (options.waitForEvent === undefined && options.write.notify === true);
+    const defaultEventOptions = {
+        eventTypes: ["change"],
+        target: options.write.target,
+        ...(options.write.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
+    };
+    const eventOptions = typeof options.waitForEvent === "object"
+        ? options.waitForEvent
+        : shouldWaitForEvent
+            ? defaultEventOptions
+            : undefined;
+    const eventPromise = eventOptions ? waitForLiveFormEvent(page, eventOptions) : null;
+    const write = await runPhase("write", () => setLiveFormFieldValue(page, options.write));
+    const event = eventPromise ? await runPhase("wait-for-event", () => eventPromise) : undefined;
+    const domDispatch = options.dispatchDomEvents
+        ? await runPhase("dispatch-dom-events", () => dispatchLiveFormFieldDomEvents(page, {
+            ...(typeof options.dispatchDomEvents === "object" ? options.dispatchDomEvents : {}),
+            target: options.write.target,
+        }))
+        : undefined;
+    const quiet = options.afterQuiet
+        ? await runPhase("after-quiet", () => waitForLiveFormQuiet(page, typeof options.afterQuiet === "object" ? options.afterQuiet : {}))
+        : undefined;
+    const readiness = options.readiness ? await runPhase("readiness", () => readLiveFormReadiness(page, options.readiness)) : undefined;
+    const validation = options.afterValidation
+        ? await runPhase("after-validation", () => waitForLiveFormValidationState(page, typeof options.afterValidation === "object" ? options.afterValidation : {}))
+        : undefined;
+    const domFields = options.snapshot
+        ? await runPhase("snapshot", () => snapshotLiveFormDomFields(page, typeof options.snapshot === "object" ? options.snapshot : {}))
+        : undefined;
+    return {
+        timeline,
+        write,
+        ...(event ? { event } : {}),
+        ...(domDispatch ? { domDispatch } : {}),
+        ...(readiness ? { readiness } : {}),
+        ...(domFields ? { domFields } : {}),
+        ...(beforeReadiness ? { beforeReadiness } : {}),
+        ...(beforeDomFields ? { beforeDomFields } : {}),
+        ...(quiet ? { quiet } : {}),
+        ...(validation ? { validation } : {}),
+    };
+}
 export async function setLiveFormFieldValuesTransaction(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("setLiveFormFieldValuesTransaction requires a Playwright page with evaluate().");
@@ -2310,6 +2704,13 @@ export const liveFormScenarioSteps = {
             }
         },
     }),
+    expectFieldCoverage: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const coverage = await readLiveFormFieldCoverage(harness.page, options);
+            assertLiveFormFieldCoverage(coverage, options);
+        },
+    }),
     expectFieldValue: (name, options) => ({
         name,
         run: async (harness) => {
@@ -2450,6 +2851,10 @@ export const liveFormFieldRecipes = {
         name,
         run: (harness) => harness.uploadFile(internalLabel, files),
     }),
+    clearSignatureDom: (name, internalLabel) => ({
+        name,
+        run: (harness) => harness.clearSignature(internalLabel),
+    }),
     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) => apiRecipeStep(name, { internalLabel }, buildLiveFormChoiceValue(value), options),