@redrockswebdevelopment/formstack-form-testing 0.1.21 → 0.1.23

package/dist/index.js

@@ -910,6 +910,27 @@ export function buildLiveFormSelectValue(value) {
 export function buildLiveFormCheckboxValue(values, otherValue = null) {
     return Object.fromEntries([...values.map((value, index) => [String(index), value]), ["otherValue", otherValue]]);
 }
+export function readLiveFormCheckboxValues(value) {
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === "string");
+    }
+    if (!value || typeof value !== "object")
+        return [];
+    const record = value;
+    if (Array.isArray(record.values)) {
+        return record.values.filter((entry) => typeof entry === "string");
+    }
+    return Object.entries(record)
+        .filter(([key, entry]) => /^\d+$/.test(key) && typeof entry === "string" && entry.length > 0)
+        .sort(([left], [right]) => Number(left) - Number(right))
+        .map(([, entry]) => entry);
+}
+export function normalizeLiveFormCheckboxValue(value, otherValue = null) {
+    const explicitOtherValue = value && typeof value === "object" && !Array.isArray(value) && "otherValue" in value
+        ? value.otherValue
+        : otherValue;
+    return buildLiveFormCheckboxValue(readLiveFormCheckboxValues(value), typeof explicitOtherValue === "string" ? explicitOtherValue : explicitOtherValue === null ? null : otherValue);
+}
 export function buildLiveFormDateTimeValue(value, current = {}) {
     return {
         ...(current && typeof current === "object" ? current : {}),
@@ -1696,6 +1717,104 @@ export async function waitForLiveFormDomFieldState(page, options) {
     }
     return latest;
 }
+export async function readLiveFormCheckboxState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormCheckboxState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const controlSnapshot = (control) => ({
+            tagName: control.tagName.toLowerCase(),
+            type: control.getAttribute("type"),
+            id: control.getAttribute("id"),
+            name: control.getAttribute("name"),
+            value: control.getAttribute("value"),
+            currentValue: control.value,
+            checked: control.checked,
+        });
+        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[type=\"checkbox\"]")).map(controlSnapshot)
+            : [];
+        const selectedValues = controls
+            .filter((control) => control.checked === true)
+            .map((control) => control.currentValue ?? control.value ?? "")
+            .filter((value) => value.length > 0);
+        const allValues = controls
+            .map((control) => control.currentValue ?? control.value ?? "")
+            .filter((value) => value.length > 0);
+        const expectedValues = [...(stateOptions.expectedValues ?? [])];
+        const missingValues = expectedValues.filter((value) => !selectedValues.includes(value));
+        const unexpectedValues = selectedValues.filter((value) => !expectedValues.includes(value));
+        const exact = stateOptions.exact !== false;
+        return {
+            fieldMatched: Boolean(root),
+            selectedValues,
+            allValues,
+            expectedValues,
+            missingValues,
+            unexpectedValues,
+            exact,
+            matched: Boolean(root) && missingValues.length === 0 && (!exact || unexpectedValues.length === 0),
+            controls,
+        };
+    }, options);
+}
+export async function waitForLiveFormCheckboxState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormCheckboxState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormCheckboxState(page, options);
+    }
+    return latest;
+}
+export async function diagnoseLiveFormCommitControl(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("diagnoseLiveFormCommitControl requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((commitOptions) => {
+        const element = document.querySelector(commitOptions.selector);
+        if (!(element instanceof HTMLElement)) {
+            return {
+                selector: commitOptions.selector,
+                exists: false,
+                visible: null,
+                disabled: null,
+                ariaDisabled: null,
+                text: null,
+                reason: "missing",
+                ready: false,
+            };
+        }
+        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 visible = style.display !== "none" && style.visibility !== "hidden" && Number(style.opacity) !== 0 && rect.width > 0 && rect.height > 0;
+        const reason = !visible ? (style.display === "none" ? "display-none" : style.visibility === "hidden" ? "visibility-hidden" : rect.width <= 0 || rect.height <= 0 ? "zero-size" : "transparent")
+            : disabled ? "disabled"
+                : ariaDisabled ? "aria-disabled"
+                    : null;
+        return {
+            selector: commitOptions.selector,
+            exists: true,
+            visible,
+            disabled,
+            ariaDisabled,
+            text: element.textContent?.replace(/\s+/g, " ").trim() ?? "",
+            reason,
+            ready: visible && !disabled && !ariaDisabled,
+        };
+    }, options);
+}
 export async function dispatchLiveFormFieldDomEvents(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("dispatchLiveFormFieldDomEvents requires a Playwright page with evaluate().");
@@ -3231,21 +3350,89 @@ export async function performLiveFormFieldTransaction(page, options) {
         afterQuiet: options.afterQuiet ?? true,
     });
 }
-export async function answerProgressiveLiveFormField(page, options) {
-    const validationOptions = options.afterValidation === undefined ? undefined : typeof options.afterValidation === "object" ? options.afterValidation : {};
+export async function setLiveFormCheckboxValues(page, options) {
+    const payload = normalizeLiveFormCheckboxValue(options.values);
+    const values = readLiveFormCheckboxValues(payload);
     const transaction = await performLiveFormFieldTransaction(page, {
         write: {
             ...(options.write ?? {}),
             target: options.target,
-            value: options.value,
+            value: payload,
             notify: options.write?.notify ?? true,
         },
-        ...(options.fieldKind ? { fieldKind: options.fieldKind } : {}),
+        fieldKind: "checkbox",
         waitForEvent: options.waitForEvent ?? true,
         dispatchDomEvents: options.dispatchDomEvents ?? "auto",
-        afterQuiet: options.afterQuiet ?? true,
-        ...(validationOptions ? { afterValidation: validationOptions } : {}),
+        afterQuiet: options.afterQuiet ?? { quietMs: 200, timeoutMs: 5_000 },
+        ...(options.afterValidation === undefined ? {} : { afterValidation: options.afterValidation }),
+    });
+    const dom = await waitForLiveFormCheckboxState(page, {
+        ...options.target,
+        expectedValues: values,
+        exact: options.exactDomSelection ?? true,
+        ...(options.write?.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
     });
+    let commitControl;
+    let clickedCommit = false;
+    if (options.commitSelector) {
+        const deadline = Date.now() + (options.commitTimeoutMs ?? 5_000);
+        commitControl = await diagnoseLiveFormCommitControl(page, { selector: options.commitSelector });
+        while (!commitControl.ready && Date.now() < deadline) {
+            await delay(100);
+            commitControl = await diagnoseLiveFormCommitControl(page, { selector: options.commitSelector });
+        }
+        if (options.clickCommit === true) {
+            if (!commitControl.ready) {
+                throw new Error(`Checkbox commit control "${options.commitSelector}" is not ready after selecting ${values.length} value(s): ${commitControl.reason ?? "unknown"}.`);
+            }
+            await page.locator(options.commitSelector).first().click({ timeout: options.commitTimeoutMs ?? 5_000 });
+            clickedCommit = true;
+        }
+    }
+    return {
+        payload,
+        values,
+        transaction,
+        dom,
+        ...(commitControl ? { commitControl } : {}),
+        clickedCommit,
+        ok: transaction.write.valueMatched &&
+            (transaction.event?.matched ?? true) &&
+            (transaction.domDispatch ? transaction.domDispatch.matchedControlCount >= values.length : true) &&
+            (transaction.quiet?.quiet ?? true) &&
+            ((transaction.validation?.inlineErrors.length ?? 0) === 0) &&
+            dom.matched &&
+            (commitControl?.ready ?? true),
+    };
+}
+export async function answerProgressiveLiveFormField(page, options) {
+    const validationOptions = options.afterValidation === undefined ? undefined : typeof options.afterValidation === "object" ? options.afterValidation : {};
+    const checkboxTransaction = options.fieldKind === "checkbox"
+        ? await setLiveFormCheckboxValues(page, {
+            target: options.target,
+            values: options.value,
+            ...(options.write === undefined ? {} : { write: options.write }),
+            waitForEvent: options.waitForEvent ?? true,
+            dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+            afterQuiet: options.afterQuiet ?? true,
+            ...(validationOptions ? { afterValidation: validationOptions } : {}),
+        })
+        : undefined;
+    const transaction = checkboxTransaction
+        ? checkboxTransaction.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,
+            dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+            afterQuiet: options.afterQuiet ?? true,
+            ...(validationOptions ? { afterValidation: validationOptions } : {}),
+        });
     const visibilityTargets = [
         ...(options.expectVisible ?? []),
         ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
@@ -3450,8 +3637,8 @@ export function normalizeLiveFormSampleValue(kind = "unknown", value) {
     if (["radio", "rating", "select"].includes(kind) && typeof value === "string") {
         return { value };
     }
-    if (kind === "checkbox" && Array.isArray(value)) {
-        return { values: value };
+    if (kind === "checkbox" && (Array.isArray(value) || (value && typeof value === "object"))) {
+        return normalizeLiveFormCheckboxValue(value);
     }
     if (kind === "checkbox" && typeof value === "boolean") {
         return { checked: value };
@@ -3637,7 +3824,12 @@ 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 })),
@@ -4664,7 +4856,19 @@ export const liveFormFieldRecipes = {
     setAddressApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormAddressValue(value), options),
     setChoiceApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormChoiceValue(value), options),
     setSelectApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormSelectValue(value), options),
-    setCheckboxesApi: (name, internalLabel, values, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormCheckboxValue(values), options),
+    setCheckboxesApi: (name, internalLabel, values, options = {}) => ({
+        name,
+        run: async (harness) => {
+            await setLiveFormCheckboxValues(harness.page, {
+                target: { internalLabel },
+                values,
+                write: { notify: options.notify ?? true },
+                waitForEvent: options.waitForEvent ?? (options.notify ?? true),
+                dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+                afterQuiet: options.waitForQuiet ?? true,
+            });
+        },
+    }),
     setDateTimeApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormDateTimeValue(value), options),
     setMatrixApi: (name, internalLabel, selections, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormMatrixValue(selections), options),
     setRatingApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormRatingValue(value), options),