@redrockswebdevelopment/formstack-form-testing 0.1.34 → 0.1.36

package/dist/index.js

@@ -23,8 +23,8 @@ export const liveFormFieldTypeCoverage = {
         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"],
+        reason: "Compound address values can be written through Live Form API, while subfield UX should be asserted for address line, city, state, ZIP, and country controls.",
+        recommendedHelpers: ["buildLiveFormAddressValue", "setLiveFormAddressValue", "readLiveFormAddressState", "fillAddress"],
     },
     checkbox: {
         kind: "checkbox",
@@ -104,8 +104,8 @@ export const liveFormFieldTypeCoverage = {
         apiWrite: true,
         domInteraction: true,
         domAssertion: true,
-        reason: "Name compound fields support direct API values and stable subfield DOM automation.",
-        recommendedHelpers: ["buildLiveFormNameValue", "setLiveFormFieldValueTransaction", "fillName", "readLiveFormReadiness"],
+        reason: "Name compound fields support direct API values and should be asserted by prefix, first, middle, last, and suffix subfields.",
+        recommendedHelpers: ["buildLiveFormNameValue", "setLiveFormNameValue", "readLiveFormNameState", "fillName"],
     },
     number: {
         kind: "number",
@@ -895,12 +895,31 @@ export function buildLiveFormNameValue(value, current = {}) {
         ...value,
     };
 }
+export function normalizeLiveFormNameValue(value, current = {}) {
+    return buildLiveFormNameValue({
+        ...(value.prefix === undefined ? {} : { prefix: String(value.prefix) }),
+        ...(value.first === undefined ? {} : { first: String(value.first) }),
+        ...(value.middle === undefined ? {} : { middle: String(value.middle) }),
+        ...(value.last === undefined ? {} : { last: String(value.last) }),
+        ...(value.suffix === undefined ? {} : { suffix: String(value.suffix) }),
+    }, current);
+}
 export function buildLiveFormAddressValue(value, current = {}) {
     return {
         ...(current && typeof current === "object" ? current : {}),
         ...value,
     };
 }
+export function normalizeLiveFormAddressValue(value, current = {}) {
+    return buildLiveFormAddressValue({
+        ...(value.address === undefined ? {} : { address: String(value.address) }),
+        ...(value.address2 === undefined ? {} : { address2: String(value.address2) }),
+        ...(value.city === undefined ? {} : { city: String(value.city) }),
+        ...(value.state === undefined ? {} : { state: String(value.state) }),
+        ...(value.zip === undefined ? {} : { zip: String(value.zip) }),
+        ...(value.country === undefined ? {} : { country: String(value.country) }),
+    }, current);
+}
 export function buildLiveFormChoiceValue(value, otherValue = "") {
     return { value, otherValue };
 }
@@ -1947,6 +1966,200 @@ export async function waitForLiveFormProductState(page, options) {
     }
     return latest;
 }
+export async function readLiveFormAddressState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormAddressState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const normalizeText = (value) => (value ?? "").replace(/\s+/g, " ").trim();
+        const inferPart = (control) => {
+            const label = control.id ? document.querySelector(`label[for="${CSS.escape(control.id)}"]`) : null;
+            const haystack = [
+                control.name,
+                control.id,
+                control.className,
+                control.getAttribute("placeholder"),
+                control.getAttribute("aria-label"),
+                label?.textContent,
+            ].map(normalizeText).join(" ").toLowerCase();
+            if (/\b(address line 2|address 2|address2|line 2|street 2|\[address2\]|-address2$|_address2$)/i.test(haystack))
+                return "address2";
+            if (/\b(address line 1|address 1|address|street|line 1|\[address\]|-address$|_address$)/i.test(haystack))
+                return "address";
+            if (/\b(city|\[city\]|-city$|_city$)/i.test(haystack))
+                return "city";
+            if (/\b(state|province|region|\[state\]|-state$|_state$)/i.test(haystack))
+                return "state";
+            if (/\b(zip|postal|postcode|post code|\[zip\]|-zip$|_zip$)/i.test(haystack))
+                return "zip";
+            if (/\b(country|\[country\]|-country$|_country$)/i.test(haystack))
+                return "country";
+            return null;
+        };
+        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 nativeControls = root
+            ? Array.from(root.querySelectorAll("input, textarea, select"))
+            : [];
+        const controls = nativeControls.map((control) => ({
+            tagName: control.tagName.toLowerCase(),
+            type: control.getAttribute("type"),
+            id: control.getAttribute("id"),
+            name: control.getAttribute("name"),
+            value: control.getAttribute("value"),
+            currentValue: "value" in control ? control.value : "",
+            checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type) ? control.checked : null,
+            part: inferPart(control),
+            text: control instanceof HTMLSelectElement
+                ? normalizeText(control.selectedOptions.item(0)?.textContent)
+                : normalizeText(control.textContent),
+            disabled: "disabled" in control ? Boolean(control.disabled) : null,
+        }));
+        const selectedParts = {};
+        for (const control of controls) {
+            if (control.part && control.disabled !== true && typeof control.currentValue === "string" && control.currentValue.length > 0) {
+                selectedParts[control.part] = control.currentValue;
+            }
+        }
+        const expected = stateOptions.expectedValue ?? {};
+        const expectedEntries = Object.entries(expected).filter((entry) => typeof entry[1] === "string" && entry[1].length > 0);
+        const availableParts = new Set(controls.filter((control) => control.part && control.disabled !== true).map((control) => control.part));
+        const renderedExpectedEntries = expectedEntries.filter(([part]) => availableParts.has(part));
+        const unavailableParts = expectedEntries
+            .filter(([part]) => !availableParts.has(part))
+            .map(([part]) => part);
+        const missingParts = renderedExpectedEntries
+            .filter(([part]) => selectedParts[part] === undefined || selectedParts[part] === "")
+            .map(([part]) => part);
+        const mismatchedParts = renderedExpectedEntries
+            .filter(([part, value]) => selectedParts[part] !== undefined && selectedParts[part] !== "" && selectedParts[part] !== value)
+            .map(([part]) => part);
+        const renderedValueAvailable = Object.keys(selectedParts).length > 0;
+        return {
+            fieldMatched: Boolean(root),
+            selectedParts,
+            ...(stateOptions.expectedValue === undefined ? {} : { expectedValue: stateOptions.expectedValue }),
+            renderedValueAvailable,
+            unavailableParts,
+            missingParts,
+            mismatchedParts,
+            matched: Boolean(root) && missingParts.length === 0 && mismatchedParts.length === 0,
+            controls,
+        };
+    }, options);
+}
+export async function waitForLiveFormAddressState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormAddressState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormAddressState(page, options);
+    }
+    return latest;
+}
+export async function readLiveFormNameState(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormNameState requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((stateOptions) => {
+        const normalizeText = (value) => (value ?? "").replace(/\s+/g, " ").trim();
+        const inferPart = (control) => {
+            const label = control.id ? document.querySelector(`label[for="${CSS.escape(control.id)}"]`) : null;
+            const haystack = [
+                control.name,
+                control.id,
+                control.className,
+                control.getAttribute("placeholder"),
+                control.getAttribute("aria-label"),
+                label?.textContent,
+            ].map(normalizeText).join(" ").toLowerCase();
+            if (/\b(prefix|title|\[prefix\]|-prefix$|_prefix$)/i.test(haystack))
+                return "prefix";
+            if (/\b(first name|given name|first|\[first\]|-first$|_first$)/i.test(haystack))
+                return "first";
+            if (/\b(middle name|middle initial|middle|\[middle\]|-middle$|_middle$)/i.test(haystack))
+                return "middle";
+            if (/\b(last name|family name|surname|last|\[last\]|-last$|_last$)/i.test(haystack))
+                return "last";
+            if (/\b(suffix|\[suffix\]|-suffix$|_suffix$)/i.test(haystack))
+                return "suffix";
+            return null;
+        };
+        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 nativeControls = root
+            ? Array.from(root.querySelectorAll("input, textarea, select"))
+            : [];
+        const controls = nativeControls.map((control) => ({
+            tagName: control.tagName.toLowerCase(),
+            type: control.getAttribute("type"),
+            id: control.getAttribute("id"),
+            name: control.getAttribute("name"),
+            value: control.getAttribute("value"),
+            currentValue: "value" in control ? control.value : "",
+            checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(control.type) ? control.checked : null,
+            part: inferPart(control),
+            text: control instanceof HTMLSelectElement
+                ? normalizeText(control.selectedOptions.item(0)?.textContent)
+                : normalizeText(control.textContent),
+            disabled: "disabled" in control ? Boolean(control.disabled) : null,
+        }));
+        const selectedParts = {};
+        for (const control of controls) {
+            if (control.part && control.disabled !== true && typeof control.currentValue === "string" && control.currentValue.length > 0) {
+                selectedParts[control.part] = control.currentValue;
+            }
+        }
+        const expected = stateOptions.expectedValue ?? {};
+        const expectedEntries = Object.entries(expected).filter((entry) => typeof entry[1] === "string" && entry[1].length > 0);
+        const availableParts = new Set(controls.filter((control) => control.part && control.disabled !== true).map((control) => control.part));
+        const renderedExpectedEntries = expectedEntries.filter(([part]) => availableParts.has(part));
+        const unavailableParts = expectedEntries
+            .filter(([part]) => !availableParts.has(part))
+            .map(([part]) => part);
+        const missingParts = renderedExpectedEntries
+            .filter(([part]) => selectedParts[part] === undefined || selectedParts[part] === "")
+            .map(([part]) => part);
+        const mismatchedParts = renderedExpectedEntries
+            .filter(([part, value]) => selectedParts[part] !== undefined && selectedParts[part] !== "" && selectedParts[part] !== value)
+            .map(([part]) => part);
+        const renderedValueAvailable = Object.keys(selectedParts).length > 0;
+        return {
+            fieldMatched: Boolean(root),
+            selectedParts,
+            ...(stateOptions.expectedValue === undefined ? {} : { expectedValue: stateOptions.expectedValue }),
+            renderedValueAvailable,
+            unavailableParts,
+            missingParts,
+            mismatchedParts,
+            matched: Boolean(root) && missingParts.length === 0 && mismatchedParts.length === 0,
+            controls,
+        };
+    }, options);
+}
+export async function waitForLiveFormNameState(page, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    let latest = await readLiveFormNameState(page, options);
+    while (!latest.matched && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        latest = await readLiveFormNameState(page, options);
+    }
+    return latest;
+}
 export async function readLiveFormCheckboxState(page, options) {
     if (!hasEvaluate(page)) {
         throw new Error("readLiveFormCheckboxState requires a Playwright page with evaluate().");
@@ -4242,6 +4455,88 @@ export async function setLiveFormProductValue(page, options) {
             (visibility?.matched ?? true),
     };
 }
+export async function setLiveFormAddressValue(page, options) {
+    const payload = normalizeLiveFormAddressValue(options.value, options.current);
+    const transaction = await performLiveFormFieldTransaction(page, {
+        write: {
+            ...(options.write ?? {}),
+            target: options.target,
+            value: payload,
+            notify: options.write?.notify ?? true,
+        },
+        fieldKind: "address",
+        waitForEvent: options.waitForEvent ?? true,
+        dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+        afterQuiet: options.afterQuiet ?? { quietMs: 200, timeoutMs: 5_000 },
+        ...(options.afterValidation === undefined ? {} : { afterValidation: options.afterValidation }),
+    });
+    const dom = await waitForLiveFormAddressState(page, {
+        ...options.target,
+        expectedValue: payload,
+        ...(options.write?.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
+    });
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []).map((target) => ({ ...target, visible: true })),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const visibility = visibilityTargets.length > 0
+        ? await waitForLiveFormVisibility(page, { targets: visibilityTargets })
+        : undefined;
+    return {
+        payload,
+        transaction,
+        dom,
+        ...(visibility ? { visibility } : {}),
+        ok: transaction.write.valueMatched &&
+            (transaction.event?.matched ?? true) &&
+            (transaction.domDispatch ? transaction.domDispatch.matchedControlCount >= 1 : true) &&
+            (transaction.quiet?.quiet ?? true) &&
+            ((transaction.validation?.inlineErrors.length ?? 0) === 0) &&
+            dom.matched &&
+            (visibility?.matched ?? true),
+    };
+}
+export async function setLiveFormNameValue(page, options) {
+    const payload = normalizeLiveFormNameValue(options.value, options.current);
+    const transaction = await performLiveFormFieldTransaction(page, {
+        write: {
+            ...(options.write ?? {}),
+            target: options.target,
+            value: payload,
+            notify: options.write?.notify ?? true,
+        },
+        fieldKind: "name",
+        waitForEvent: options.waitForEvent ?? true,
+        dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+        afterQuiet: options.afterQuiet ?? { quietMs: 200, timeoutMs: 5_000 },
+        ...(options.afterValidation === undefined ? {} : { afterValidation: options.afterValidation }),
+    });
+    const dom = await waitForLiveFormNameState(page, {
+        ...options.target,
+        expectedValue: payload,
+        ...(options.write?.timeoutMs === undefined ? {} : { timeoutMs: options.write.timeoutMs }),
+    });
+    const visibilityTargets = [
+        ...(options.expectVisible ?? []).map((target) => ({ ...target, visible: true })),
+        ...(options.expectHidden ?? []).map((target) => ({ ...target, visible: false })),
+    ];
+    const visibility = visibilityTargets.length > 0
+        ? await waitForLiveFormVisibility(page, { targets: visibilityTargets })
+        : undefined;
+    return {
+        payload,
+        transaction,
+        dom,
+        ...(visibility ? { visibility } : {}),
+        ok: transaction.write.valueMatched &&
+            (transaction.event?.matched ?? true) &&
+            (transaction.domDispatch ? transaction.domDispatch.matchedControlCount >= 1 : true) &&
+            (transaction.quiet?.quiet ?? true) &&
+            ((transaction.validation?.inlineErrors.length ?? 0) === 0) &&
+            dom.matched &&
+            (visibility?.matched ?? true),
+    };
+}
 export async function setLiveFormRatingValue(page, options) {
     const payload = normalizeLiveFormRatingValue(options.value);
     const value = payload.value;
@@ -4372,7 +4667,29 @@ export async function answerProgressiveLiveFormField(page, options) {
             ...(validationOptions ? { afterValidation: validationOptions } : {}),
         })
         : undefined;
-    const productTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && options.fieldKind === "product"
+    const nameTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && options.fieldKind === "name"
+        ? await setLiveFormNameValue(page, {
+            target: options.target,
+            value: 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 addressTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && !nameTransaction && options.fieldKind === "address"
+        ? await setLiveFormAddressValue(page, {
+            target: options.target,
+            value: 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 productTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && !nameTransaction && !addressTransaction && options.fieldKind === "product"
         ? await setLiveFormProductValue(page, {
             target: options.target,
             value: options.value,
@@ -4383,7 +4700,7 @@ export async function answerProgressiveLiveFormField(page, options) {
             ...(validationOptions ? { afterValidation: validationOptions } : {}),
         })
         : undefined;
-    const ratingTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && !productTransaction && options.fieldKind === "rating"
+    const ratingTransaction = !checkboxTransaction && !choiceTransaction && !selectTransaction && !matrixTransaction && !nameTransaction && !addressTransaction && !productTransaction && options.fieldKind === "rating"
         ? await setLiveFormRatingValue(page, {
             target: options.target,
             value: options.value,
@@ -4413,25 +4730,29 @@ export async function answerProgressiveLiveFormField(page, options) {
                 ? selectTransaction.transaction
                 : matrixTransaction
                     ? matrixTransaction.transaction
-                    : productTransaction
-                        ? productTransaction.transaction
-                        : ratingTransaction
-                            ? ratingTransaction.transaction
-                            : dateTimeTransaction
-                                ? dateTimeTransaction.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 } : {}),
-                                });
+                    : nameTransaction
+                        ? nameTransaction.transaction
+                        : addressTransaction
+                            ? addressTransaction.transaction
+                            : productTransaction
+                                ? productTransaction.transaction
+                                : ratingTransaction
+                                    ? ratingTransaction.transaction
+                                    : dateTimeTransaction
+                                        ? dateTimeTransaction.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 })),
@@ -6135,8 +6456,32 @@ export const liveFormFieldRecipes = {
             }
         },
     }),
-    setNameApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormNameValue(value), options),
-    setAddressApi: (name, internalLabel, value, options) => apiRecipeStep(name, { internalLabel }, buildLiveFormAddressValue(value), options),
+    setNameApi: (name, internalLabel, value, options = {}) => ({
+        name,
+        run: async (harness) => {
+            await setLiveFormNameValue(harness.page, {
+                target: { internalLabel },
+                value,
+                write: { notify: options.notify ?? true },
+                waitForEvent: options.waitForEvent ?? (options.notify ?? true),
+                dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+                afterQuiet: options.waitForQuiet ?? true,
+            });
+        },
+    }),
+    setAddressApi: (name, internalLabel, value, options = {}) => ({
+        name,
+        run: async (harness) => {
+            await setLiveFormAddressValue(harness.page, {
+                target: { internalLabel },
+                value,
+                write: { notify: options.notify ?? true },
+                waitForEvent: options.waitForEvent ?? (options.notify ?? true),
+                dispatchDomEvents: options.dispatchDomEvents ?? "auto",
+                afterQuiet: options.waitForQuiet ?? true,
+            });
+        },
+    }),
     setChoiceApi: (name, internalLabel, value, options = {}) => ({
         name,
         run: async (harness) => {