@redrockswebdevelopment/formstack-form-testing 0.1.5 → 0.1.7

package/dist/index.js

@@ -1407,6 +1407,20 @@ export async function postMessageToIframe(page, options) {
 export function buildFormstackIframeBridgeMessage(message) {
     return message;
 }
+export function createFormstackIframeBridgeRequest(options) {
+    return buildFormstackIframeBridgeMessage({
+        channel: options.channel,
+        requestId: options.requestId ?? `fspt-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+        type: options.type,
+        ...(options.payload === undefined ? {} : { payload: options.payload }),
+    });
+}
+export function createFormstackIframePrefillRequest(options) {
+    return createFormstackIframeBridgeRequest({
+        ...options,
+        type: options.type ?? "prefill",
+    });
+}
 export async function waitForWindowMessage(page, options = {}) {
     if (!hasEvaluate(page)) {
         throw new Error("waitForWindowMessage requires a Playwright page with evaluate().");
@@ -1472,6 +1486,13 @@ export async function sendFormstackIframeBridgeMessage(page, options) {
     });
     return { posted, response };
 }
+export async function sendFormstackIframePrefillMessage(page, options) {
+    return sendFormstackIframeBridgeMessage(page, {
+        ...options,
+        type: options.type ?? "prefill",
+        responseType: options.responseType ?? `${options.type ?? "prefill"}:response`,
+    });
+}
 export async function waitForConsoleMessage(page, options = {}) {
     const timeoutMs = options.timeoutMs ?? 5_000;
     const startedAt = Date.now();
@@ -2440,6 +2461,57 @@ export async function waitForLiveFormEvent(page, options) {
         };
     }, options);
 }
+export function defaultLiveFormFieldEventPlan(kind = "unknown") {
+    if (["radio", "checkbox", "matrix", "rating"].includes(kind)) {
+        return {
+            eventTypes: ["input", "change", "blur"],
+            onlyCheckedChoices: true,
+            reason: "Choice-like fields should notify checked controls and then blur so custom scripts and validation see a user-like selection.",
+        };
+    }
+    if (["name", "address", "date", "datetime", "product"].includes(kind)) {
+        return {
+            eventTypes: ["input", "change", "blur"],
+            onlyCheckedChoices: false,
+            reason: "Compound fields can render several controls, so dispatch across all visible subcontrols after an API value write.",
+        };
+    }
+    if (["select"].includes(kind)) {
+        return {
+            eventTypes: ["change", "blur"],
+            onlyCheckedChoices: false,
+            reason: "Select fields primarily publish change events, with blur included for validation parity.",
+        };
+    }
+    if (["text", "textarea", "email", "phone", "number"].includes(kind)) {
+        return {
+            eventTypes: ["input", "change", "blur"],
+            onlyCheckedChoices: false,
+            reason: "Text-like fields should emit input, change, and blur to match Formstack custom-script and validation timing.",
+        };
+    }
+    return {
+        eventTypes: ["input", "change", "blur"],
+        onlyCheckedChoices: true,
+        reason: "Unknown fields use the conservative user-like event sequence while avoiding unchecked choice controls.",
+    };
+}
+function liveFormFieldTargetKey(target) {
+    if (target.internalLabel)
+        return target.internalLabel;
+    if (target.fieldId != null)
+        return String(target.fieldId);
+    return null;
+}
+function resolveLiveFormDispatchOptions(dispatch, fieldKind) {
+    if (dispatch === undefined || dispatch === false)
+        return null;
+    if (dispatch === true || dispatch === "auto") {
+        const { eventTypes, onlyCheckedChoices } = defaultLiveFormFieldEventPlan(fieldKind);
+        return { eventTypes, onlyCheckedChoices };
+    }
+    return dispatch;
+}
 export async function setLiveFormFieldValueTransaction(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("setLiveFormFieldValueTransaction requires a Playwright page with evaluate().");
@@ -2459,12 +2531,13 @@ export async function setLiveFormFieldValueTransaction(page, options) {
     const eventPromise = eventOptions ? waitForLiveFormEvent(page, eventOptions) : null;
     const write = await setLiveFormFieldValue(page, options.write);
     const event = eventPromise ? await eventPromise : undefined;
-    const domDispatch = options.dispatchDomEvents === undefined || options.dispatchDomEvents === false
-        ? undefined
-        : await dispatchLiveFormFieldDomEvents(page, {
-            ...(typeof options.dispatchDomEvents === "object" ? options.dispatchDomEvents : {}),
+    const dispatchOptions = resolveLiveFormDispatchOptions(options.dispatchDomEvents, options.fieldKind);
+    const domDispatch = dispatchOptions
+        ? await dispatchLiveFormFieldDomEvents(page, {
+            ...dispatchOptions,
             target: options.write.target,
-        });
+        })
+        : undefined;
     const readiness = options.readiness ? await readLiveFormReadiness(page, options.readiness) : undefined;
     const domFields = options.snapshot
         ? await snapshotLiveFormDomFields(page, typeof options.snapshot === "object" ? options.snapshot : {})
@@ -2527,9 +2600,10 @@ export async function setLiveFormFieldValueTimedTransaction(page, options) {
     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
+    const dispatchOptions = resolveLiveFormDispatchOptions(options.dispatchDomEvents, options.fieldKind);
+    const domDispatch = dispatchOptions
         ? await runPhase("dispatch-dom-events", () => dispatchLiveFormFieldDomEvents(page, {
-            ...(typeof options.dispatchDomEvents === "object" ? options.dispatchDomEvents : {}),
+            ...dispatchOptions,
             target: options.write.target,
         }))
         : undefined;
@@ -2556,6 +2630,104 @@ export async function setLiveFormFieldValueTimedTransaction(page, options) {
         ...(validation ? { validation } : {}),
     };
 }
+export async function waitForLiveFormReady(page, options = {}) {
+    const report = await waitForLiveFormReadiness(page, options);
+    if (options.throwOnBlockingFields !== false && !report.isReady) {
+        throw new Error(`Live form did not become ready; ${report.blockingFieldCount} field(s) are blocking.`);
+    }
+    return report;
+}
+export async function waitForLiveFormFieldStable(page, options) {
+    const quiet = options.quiet
+        ? await waitForLiveFormQuiet(page, typeof options.quiet === "object" ? options.quiet : {})
+        : undefined;
+    const value = options.value ? await waitForLiveFormFieldValue(page, { ...options.value, target: options.target }) : undefined;
+    const dom = options.dom ? await waitForLiveFormDomFieldState(page, { ...options.target, ...options.dom }) : undefined;
+    const stable = (quiet?.quiet ?? true) && (value ? (value.expectedValue === undefined ? value.fieldAvailable && !value.isEmpty : value.valueMatched === true) : true) && (dom?.matched ?? true);
+    return {
+        ...(quiet ? { quiet } : {}),
+        ...(value ? { value } : {}),
+        ...(dom ? { dom } : {}),
+        stable,
+    };
+}
+export async function waitForLiveFormValidationSettled(page, options = {}) {
+    const validation = await waitForLiveFormValidationState(page, {
+        ...options,
+        ...(options.requireNoErrors === false ? {} : { expectNoErrors: options.expectNoErrors ?? true }),
+    });
+    if (options.requireNoErrors !== false && validation.inlineErrors.length > 0) {
+        throw new Error(`Live form validation did not settle cleanly; found ${validation.inlineErrors.length} visible error(s).`);
+    }
+    return validation;
+}
+export async function waitForLiveFormLogicSettled(page, options = {}) {
+    const quiet = options.quiet
+        ? await waitForLiveFormQuiet(page, typeof options.quiet === "object" ? options.quiet : {})
+        : undefined;
+    const visibility = options.visibility ? await waitForLiveFormVisibility(page, options.visibility) : undefined;
+    const readiness = options.readiness ? await waitForLiveFormReadiness(page, options.readiness) : undefined;
+    const validation = options.validation
+        ? await waitForLiveFormValidationSettled(page, typeof options.validation === "object" ? options.validation : {})
+        : undefined;
+    return {
+        ...(quiet ? { quiet } : {}),
+        ...(visibility ? { visibility } : {}),
+        ...(readiness ? { readiness } : {}),
+        ...(validation ? { validation } : {}),
+        settled: (quiet?.quiet ?? true) && (visibility?.matched ?? true) && (readiness?.isReady ?? true) && ((validation?.inlineErrors.length ?? 0) === 0),
+    };
+}
+export async function performLiveFormFieldTransaction(page, options) {
+    return setLiveFormFieldValueTimedTransaction(page, {
+        ...options,
+        ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
+        dispatchDomEvents: options.dispatchDomEvents ?? (options.autoDispatchDomEvents === false ? false : "auto"),
+        afterQuiet: options.afterQuiet ?? true,
+    });
+}
+export async function answerProgressiveLiveFormField(page, options) {
+    const validationOptions = options.afterValidation === undefined ? undefined : typeof options.afterValidation === "object" ? options.afterValidation : {};
+    const transaction = await performLiveFormFieldTransaction(page, {
+        write: {
+            ...(options.write ?? {}),
+            target: options.target,
+            value: options.value,
+            notify: options.write?.notify ?? true,
+        },
+        ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
+        waitForEvent: options.waitForEvent ?? true,
+        afterQuiet: options.afterQuiet ?? true,
+        ...(validationOptions ? { afterValidation: validationOptions } : {}),
+    });
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const visibility = visibilityTargets.length > 0
+        ? await waitForLiveFormVisibility(page, { targets: visibilityTargets })
+        : undefined;
+    if (visibility && !visibility.matched) {
+        throw new Error("Progressive live form answer did not produce the expected visibility state.");
+    }
+    const resetValues = [];
+    for (const reset of options.expectReset ?? []) {
+        const value = await readLiveFormFieldValue(page, reset);
+        if (!value.isEmpty) {
+            throw new Error(`Expected progressive answer reset target ${reset.target.internalLabel ?? reset.target.fieldId ?? "unknown"} to be empty.`);
+        }
+        resetValues.push(value);
+    }
+    const validation = validationOptions
+        ? await waitForLiveFormValidationSettled(page, validationOptions)
+        : undefined;
+    return {
+        transaction,
+        ...(visibility ? { visibility } : {}),
+        resetValues,
+        ...(validation ? { validation } : {}),
+    };
+}
 function mergeTraceFieldValueTarget(target, options) {
     if (!target || options === false || options === undefined)
         return null;
@@ -2653,10 +2825,12 @@ export async function setLiveFormFieldValuesTransaction(page, options) {
     const domDispatches = [];
     const waitForEvents = options.waitForEvents ?? true;
     for (const writeOptions of options.writes) {
+        const fieldKey = liveFormFieldTargetKey(writeOptions.target);
         const transaction = await setLiveFormFieldValueTransaction(page, {
             write: writeOptions,
             waitForEvent: waitForEvents && writeOptions.notify === true,
             ...(options.dispatchDomEvents === undefined ? {} : { dispatchDomEvents: options.dispatchDomEvents }),
+            ...(fieldKey && options.fieldKinds?.[fieldKey] ? { fieldKind: options.fieldKinds[fieldKey] } : {}),
         });
         writes.push(transaction.write);
         if (transaction.event)
@@ -2820,6 +2994,9 @@ function errorReport(error) {
 }
 export async function runFormScenario(page, scenario, options = {}) {
     const monitor = createFormBrowserMonitor(page, scenario.diagnostics ?? options.diagnostics);
+    const activityRecorder = options.activity
+        ? createFormBrowserActivityRecorder(page, typeof options.activity === "object" ? options.activity : {})
+        : null;
     const harness = createFormTestHarness(page, options);
     const steps = [];
     const started = Date.now();
@@ -2834,6 +3011,7 @@ export async function runFormScenario(page, scenario, options = {}) {
             durationMs: ended - started,
             steps,
             diagnostics: monitor.report(),
+            ...(activityRecorder ? { activity: activityRecorder.report() } : {}),
             ...(options.artifacts === undefined ? {} : { artifacts: options.artifacts }),
         };
     };
@@ -2886,6 +3064,7 @@ export async function runFormScenario(page, scenario, options = {}) {
     }
     finally {
         monitor.detach();
+        activityRecorder?.detach();
     }
 }
 export function defineFormScenario(scenario) {
@@ -2896,6 +3075,14 @@ export const liveFormScenarioSteps = {
         name,
         run: (harness) => setLiveFormFieldValueTransaction(harness.page, options).then(() => undefined),
     }),
+    performFieldTransaction: (name, options) => ({
+        name,
+        run: (harness) => performLiveFormFieldTransaction(harness.page, options).then(() => undefined),
+    }),
+    answerProgressiveField: (name, options) => ({
+        name,
+        run: (harness) => answerProgressiveLiveFormField(harness.page, options).then(() => undefined),
+    }),
     writeFields: (name, options) => ({
         name,
         run: (harness) => setLiveFormFieldValuesTransaction(harness.page, options).then(() => undefined),
@@ -2903,12 +3090,30 @@ export const liveFormScenarioSteps = {
     expectReady: (name, options) => ({
         name,
         run: async (harness) => {
-            const readiness = await waitForLiveFormReadiness(harness.page, options);
+            const readiness = await waitForLiveFormReady(harness.page, options);
             if (!readiness.isReady) {
                 throw new Error(`Expected live form to be ready, but ${readiness.blockingFieldCount} field(s) are blocking.`);
             }
         },
     }),
+    expectFieldStable: (name, options) => ({
+        name,
+        run: async (harness) => {
+            const stable = await waitForLiveFormFieldStable(harness.page, options);
+            if (!stable.stable) {
+                throw new Error("Expected live form field to become stable before timeout.");
+            }
+        },
+    }),
+    expectLogicSettled: (name, options = {}) => ({
+        name,
+        run: async (harness) => {
+            const settled = await waitForLiveFormLogicSettled(harness.page, options);
+            if (!settled.settled) {
+                throw new Error("Expected live form logic to settle before timeout.");
+            }
+        },
+    }),
     waitForQuiet: (name, options = {}) => ({
         name,
         run: async (harness) => {
@@ -3034,6 +3239,7 @@ function apiRecipeStep(name, target, value, options = {}) {
                 },
                 waitForEvent: options.waitForEvent ?? (options.notify ?? true),
                 ...(options.dispatchDomEvents === undefined ? {} : { dispatchDomEvents: options.dispatchDomEvents }),
+                ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
             });
             await maybeWaitForQuiet(harness.page, options);
         },
@@ -3089,7 +3295,8 @@ export const liveFormFieldRecipes = {
     setMatrixApi: (name, internalLabel, selections, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormMatrixValue(selections), options),
     setRatingApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormRatingValue(value), options),
     setProductApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormProductValue(value), options),
-    setNameApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setNameApi(name, internalLabel, value, { ...options, dispatchDomEvents: { eventTypes: ["input", "change", "blur"], onlyCheckedChoices: false } }),
-    setChoiceApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setChoiceApi(name, internalLabel, value, { ...options, dispatchDomEvents: { eventTypes: ["input", "change", "blur"], onlyCheckedChoices: true } }),
+    setFieldApiAuto: (name, internalLabel, value, fieldKind, options = {}) => apiRecipeStep(name, { internalLabel }, value, { ...options, fieldKind, dispatchDomEvents: "auto" }),
+    setNameApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setNameApi(name, internalLabel, value, { ...options, fieldKind: options.fieldKind ?? "name", dispatchDomEvents: "auto" }),
+    setChoiceApiAndDispatch: (name, internalLabel, value, options = {}) => liveFormFieldRecipes.setChoiceApi(name, internalLabel, value, { ...options, fieldKind: options.fieldKind ?? "radio", dispatchDomEvents: "auto" }),
 };
 //# sourceMappingURL=index.js.map