@redrockswebdevelopment/formstack-form-testing 0.1.7 → 0.1.9

package/dist/index.js

@@ -290,6 +290,368 @@ function matchesPattern(value, pattern) {
 function isIgnored(value, patterns) {
     return patterns?.some((pattern) => matchesPattern(value, pattern)) ?? false;
 }
+function liveFormTargetMatches(source, event) {
+    if (source.internalLabel && event.internalLabel)
+        return source.internalLabel === event.internalLabel;
+    if (source.internalLabel && event.target.internalLabel)
+        return source.internalLabel === event.target.internalLabel;
+    if (source.fieldId != null && event.fieldId != null)
+        return String(source.fieldId) === String(event.fieldId);
+    if (source.fieldId != null && event.target.fieldId != null)
+        return String(source.fieldId) === String(event.target.fieldId);
+    return false;
+}
+function createLiveFormEffectTransactionId(prefix = "fspt-effect") {
+    return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function createLiveFormEffectController(adapter, options = {}) {
+    const startedAt = adapter.now?.() ?? Date.now();
+    const now = () => adapter.now?.() ?? Date.now();
+    const effects = new Map();
+    const traces = [];
+    const runCounts = new Map();
+    const latestSequenceByEffect = new Map();
+    const maxRunsPerTransaction = options.maxRunsPerTransaction ?? 25;
+    const emitTrace = (kind, detail, effectId, transactionId) => {
+        const event = {
+            kind,
+            at: new Date().toISOString(),
+            elapsedMs: Math.round(now() - startedAt),
+            ...(effectId ? { effectId } : {}),
+            ...(transactionId ? { transactionId } : {}),
+            detail,
+        };
+        if (options.trace !== false)
+            traces.push(event);
+        options.onTrace?.(event);
+    };
+    const runEffect = async (effect, event) => {
+        const transactionId = event.transactionId ?? createLiveFormEffectTransactionId();
+        if (effect.ignoreTransactions?.includes(transactionId)) {
+            emitTrace("effect-skip", { reason: "ignored-transaction" }, effect.id, transactionId);
+            return;
+        }
+        const runKey = `${transactionId}:${effect.id}`;
+        const runIndex = (runCounts.get(runKey) ?? 0) + 1;
+        runCounts.set(runKey, runIndex);
+        if (runIndex > maxRunsPerTransaction) {
+            emitTrace("effect-skip", { reason: "max-runs-exceeded", runIndex, maxRunsPerTransaction }, effect.id, transactionId);
+            return;
+        }
+        const sequence = (latestSequenceByEffect.get(effect.id) ?? 0) + 1;
+        latestSequenceByEffect.set(effect.id, sequence);
+        const waitForPhase = async () => {
+            if (effect.phase === "afterQuiet" || effect.phase === "afterValidation")
+                await adapter.waitForQuiet?.();
+            if (effect.phase === "afterValidation")
+                await adapter.validate?.({ validate: true });
+        };
+        emitTrace("effect-start", { phase: effect.phase ?? "afterValue", runIndex }, effect.id, transactionId);
+        try {
+            await waitForPhase();
+            if (effect.latestOnly !== false && latestSequenceByEffect.get(effect.id) !== sequence) {
+                emitTrace("effect-skip", { reason: "stale-run", sequence }, effect.id, transactionId);
+                return;
+            }
+            const context = {
+                event,
+                effectId: effect.id,
+                transactionId,
+                runIndex,
+                readField: (target) => adapter.readField(target),
+                writeField: async (target, value, writeOptions = {}) => {
+                    const writeTransactionId = writeOptions.transactionId ?? transactionId;
+                    emitTrace("write", {
+                        target,
+                        value,
+                        source: writeOptions.source ?? effect.id,
+                        suppressEffects: writeOptions.suppressEffects ?? false,
+                    }, effect.id, writeTransactionId);
+                    await adapter.writeField(target, value, {
+                        ...writeOptions,
+                        source: writeOptions.source ?? effect.id,
+                        transactionId: writeTransactionId,
+                    });
+                },
+                waitForQuiet: async (quietOptions) => {
+                    await adapter.waitForQuiet?.(quietOptions);
+                },
+                validate: async (validationOptions) => adapter.validate?.(validationOptions),
+                trace: (kind, detail = {}) => emitTrace(kind, detail, effect.id, transactionId),
+            };
+            await effect.handler(context);
+            emitTrace("effect-complete", { runIndex }, effect.id, transactionId);
+        }
+        catch (error) {
+            emitTrace("effect-error", { message: error instanceof Error ? error.message : String(error) }, effect.id, transactionId);
+            throw error;
+        }
+    };
+    const emit = async (event) => {
+        emitTrace("change", {
+            target: event.target,
+            fieldId: event.fieldId ?? null,
+            internalLabel: event.internalLabel ?? null,
+            source: event.source ?? null,
+        }, undefined, event.transactionId);
+        const matching = [...effects.values()].filter((effect) => effect.sources.some((source) => liveFormTargetMatches(source, event)));
+        for (const effect of matching)
+            await runEffect(effect, event);
+    };
+    const unsubscribe = adapter.onFieldChange((event) => {
+        void emit(event);
+    });
+    return {
+        register: (effect) => {
+            if (effects.has(effect.id))
+                throw new Error(`Live form effect "${effect.id}" is already registered.`);
+            effects.set(effect.id, effect);
+            emitTrace("registered", { sources: effect.sources, phase: effect.phase ?? "afterValue" }, effect.id);
+            return () => {
+                effects.delete(effect.id);
+            };
+        },
+        emit,
+        writeField: async (target, value, writeOptions = {}) => {
+            const transactionId = writeOptions.transactionId ?? createLiveFormEffectTransactionId();
+            emitTrace("write", { target, value, source: writeOptions.source ?? "controller", suppressEffects: writeOptions.suppressEffects ?? false }, undefined, transactionId);
+            await adapter.writeField(target, value, { ...writeOptions, transactionId });
+        },
+        readField: (target) => adapter.readField(target),
+        waitForQuiet: async (quietOptions) => {
+            await adapter.waitForQuiet?.(quietOptions);
+        },
+        validate: async (validationOptions) => adapter.validate?.(validationOptions),
+        traces: () => [...traces],
+        dispose: () => {
+            effects.clear();
+            unsubscribe();
+        },
+    };
+}
+export function createFormstackLiveFormEffectAdapter(options = {}) {
+    const readApi = () => {
+        const globalObject = globalThis;
+        const factory = globalObject.window && typeof globalObject.window === "object"
+            ? Reflect.get(globalObject.window, "fsApi")
+            : Reflect.get(globalObject, "fsApi");
+        const api = typeof factory === "function" ? Reflect.apply(factory, globalObject.window ?? globalObject, []) : null;
+        const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+        const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+        return Array.isArray(forms) ? forms[0] ?? null : null;
+    };
+    const waitForForm = async () => {
+        const timeoutMs = options.waitForApiTimeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        let form = readApi();
+        while ((!form || typeof form !== "object") && Date.now() < deadline) {
+            await delay(50);
+            form = readApi();
+        }
+        if (!form || typeof form !== "object")
+            throw new Error("Formstack Live Form API did not become available.");
+        return form;
+    };
+    const resolveField = async (target) => {
+        const form = await waitForForm();
+        const getField = Reflect.get(form, "getField");
+        const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+        if (target.internalLabel && typeof getFieldByInternalLabel === "function") {
+            const field = Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel]);
+            if (field)
+                return field;
+        }
+        if (target.fieldId != null && typeof getField === "function")
+            return Reflect.apply(getField, form, [String(target.fieldId)]);
+        return null;
+    };
+    const readFieldValue = (field) => {
+        if (!field || typeof field !== "object")
+            return null;
+        const getValue = Reflect.get(field, "getValue");
+        return typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+    };
+    const readFieldId = (field) => {
+        if (!field || typeof field !== "object")
+            return null;
+        const getId = Reflect.get(field, "getId");
+        if (typeof getId === "function")
+            return Reflect.apply(getId, field, []);
+        return Reflect.get(field, "id") ?? null;
+    };
+    const listeners = new Set();
+    let formListenerDispose = null;
+    const ensureFormListener = async () => {
+        if (formListenerDispose)
+            return;
+        const form = await waitForForm();
+        const registerFormEventListener = Reflect.get(form, "registerFormEventListener");
+        const unregisterFormEventListener = Reflect.get(form, "unregisterFormEventListener");
+        if (typeof registerFormEventListener !== "function")
+            return;
+        const formEventListener = {
+            type: "change",
+            onFormEvent: async (event) => {
+                const eventObject = event && typeof event === "object" ? event : {};
+                const data = Reflect.get(eventObject, "data");
+                const dataObject = data && typeof data === "object" ? data : {};
+                const fieldId = Reflect.get(dataObject, "fieldId") ?? null;
+                const field = fieldId == null ? null : typeof Reflect.get(form, "getField") === "function"
+                    ? Reflect.apply(Reflect.get(form, "getField"), form, [String(fieldId)])
+                    : null;
+                const currentValue = readFieldValue(field);
+                const internalLabel = field && typeof field === "object"
+                    ? Reflect.get(field, "internalLabel") ?? null
+                    : null;
+                const changeEvent = {
+                    target: fieldId == null ? {} : { fieldId },
+                    fieldId,
+                    internalLabel,
+                    currentValue,
+                    source: Reflect.get(dataObject, "type") ?? "formstack-change",
+                };
+                for (const listener of listeners)
+                    listener(changeEvent);
+            },
+        };
+        Reflect.apply(registerFormEventListener, form, [formEventListener]);
+        formListenerDispose = () => {
+            if (typeof unregisterFormEventListener === "function")
+                Reflect.apply(unregisterFormEventListener, form, [formEventListener]);
+            formListenerDispose = null;
+        };
+    };
+    return {
+        readField: async (target) => readFieldValue(await resolveField(target)),
+        writeField: async (target, value, writeOptions = {}) => {
+            const form = await waitForForm();
+            const field = await resolveField(target);
+            if (!field || typeof field !== "object")
+                throw new Error(`Unable to resolve Formstack field ${target.internalLabel ?? target.fieldId ?? "unknown"}.`);
+            const setValue = Reflect.get(field, "setValue");
+            if (typeof setValue !== "function")
+                throw new Error("Resolved Formstack field does not support setValue().");
+            const previousValue = readFieldValue(field);
+            await Promise.resolve(Reflect.apply(setValue, field, [value]));
+            if (options.notifyWrites ?? true) {
+                const notifyFormEventListeners = Reflect.get(form, "notifyFormEventListeners");
+                if (typeof notifyFormEventListeners === "function") {
+                    await Promise.resolve(Reflect.apply(notifyFormEventListeners, form, [
+                        "change",
+                        {
+                            fieldId: readFieldId(field),
+                            type: writeOptions.source ?? "effect-write",
+                            transactionId: writeOptions.transactionId,
+                            suppressEffects: writeOptions.suppressEffects ?? false,
+                            value,
+                        },
+                    ]));
+                }
+            }
+            if (!writeOptions.suppressEffects) {
+                const currentValue = readFieldValue(field);
+                const event = {
+                    target,
+                    fieldId: readFieldId(field),
+                    internalLabel: target.internalLabel ?? null,
+                    previousValue,
+                    currentValue,
+                    source: writeOptions.source ?? "effect-write",
+                    ...(writeOptions.transactionId ? { transactionId: writeOptions.transactionId } : {}),
+                };
+                for (const listener of listeners)
+                    listener(event);
+            }
+        },
+        onFieldChange: (listener) => {
+            listeners.add(listener);
+            void ensureFormListener();
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0)
+                    formListenerDispose?.();
+            };
+        },
+        waitForQuiet: async (quietOptions = {}) => {
+            await delay(quietOptions.quietMs ?? options.quietMs ?? 250);
+        },
+        validate: async (validationOptions = {}) => {
+            const form = await waitForForm();
+            if (!validationOptions.validate)
+                return null;
+            const validateForm = Reflect.get(form, "validateForm");
+            return typeof validateForm === "function" ? Reflect.apply(validateForm, form, []) : null;
+        },
+        now: () => Date.now(),
+    };
+}
+function liveFormEffectValuesEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    try {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+export function deriveLiveFormField(options) {
+    return {
+        id: options.id,
+        sources: options.sources,
+        phase: options.phase ?? "afterQuiet",
+        latestOnly: options.latestOnly ?? true,
+        handler: async (context) => {
+            const values = await Promise.all(options.sources.map((source) => context.readField(source)));
+            const nextValue = await options.compute(values, context);
+            const currentValue = await context.readField(options.target);
+            const shouldWrite = options.shouldWrite?.(nextValue, currentValue) ?? !liveFormEffectValuesEqual(nextValue, currentValue);
+            if (!shouldWrite) {
+                context.trace("effect-skip", { reason: "derived-value-unchanged", target: options.target });
+                return;
+            }
+            await context.writeField(options.target, nextValue, options.suppressEffects === undefined ? {} : { suppressEffects: options.suppressEffects });
+        },
+    };
+}
+export function resetLiveFormDependents(options) {
+    return {
+        id: options.id,
+        sources: options.sources,
+        phase: options.phase ?? "afterQuiet",
+        handler: async (context) => {
+            for (const dependent of options.dependents) {
+                await context.writeField(dependent, options.emptyValue ?? "", {
+                    suppressEffects: options.suppressEffects ?? true,
+                });
+            }
+        },
+    };
+}
+export function gateLiveFormSubmit(options) {
+    return {
+        id: options.id,
+        sources: options.sources,
+        phase: options.phase ?? "afterQuiet",
+        latestOnly: true,
+        handler: async (context) => {
+            const values = await Promise.all(options.sources.map((source) => context.readField(source)));
+            const ready = await options.isReady(values, context);
+            const selector = options.submitSelector ?? ".fsSubmitButton, [type=submit]";
+            const documentObject = globalThis.document;
+            if (!documentObject?.querySelectorAll) {
+                context.trace("effect-skip", { reason: "document-unavailable", ready, selector });
+                return;
+            }
+            for (const element of Array.from(documentObject.querySelectorAll(selector))) {
+                element.toggleAttribute("disabled", !ready);
+                element.setAttribute("aria-disabled", ready ? "false" : "true");
+                element.dataset.fsptSubmitReady = ready ? "true" : "false";
+            }
+            context.trace("effect-complete", { kind: "submit-gate", ready, selector });
+        },
+    };
+}
 function defaultDiagnosticsOptions(options = {}) {
     return {
         failOnConsoleTypes: options.failOnConsoleTypes ?? ["error"],
@@ -1566,6 +1928,157 @@ export async function waitForWindowFlag(page, options) {
         };
     }, options);
 }
+export async function installLiveFormEffectTraceProbe(page, options) {
+    if (!hasEvaluate(page)) {
+        throw new Error("installLiveFormEffectTraceProbe requires a Playwright page with evaluate().");
+    }
+    return page.evaluate(async (probeOptions) => {
+        const propertyName = probeOptions.propertyName ?? "__fsptLiveFormEffectProbe";
+        const effectId = probeOptions.effectId ?? "fspt-effect-probe";
+        const startedAt = Date.now();
+        const traces = [];
+        const record = (kind, detail, transactionId) => {
+            traces.push({
+                kind,
+                at: new Date().toISOString(),
+                elapsedMs: Date.now() - startedAt,
+                effectId,
+                ...(transactionId ? { transactionId } : {}),
+                detail,
+            });
+        };
+        const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+        const readApi = () => {
+            const factory = Reflect.get(window, "fsApi");
+            const api = typeof factory === "function" ? Reflect.apply(factory, window, []) : null;
+            const getForms = api && typeof api === "object" ? Reflect.get(api, "getForms") : null;
+            const forms = typeof getForms === "function" ? Reflect.apply(getForms, api, []) : [];
+            return Array.isArray(forms) ? forms[0] ?? null : null;
+        };
+        const waitForForm = async () => {
+            const deadline = Date.now() + 10_000;
+            let form = readApi();
+            while ((!form || typeof form !== "object") && Date.now() < deadline) {
+                await wait(50);
+                form = readApi();
+            }
+            if (!form || typeof form !== "object")
+                throw new Error("Formstack Live Form API did not become available.");
+            return form;
+        };
+        const fieldIdFromTarget = async (target) => {
+            if (target.fieldId != null)
+                return target.fieldId;
+            const form = await waitForForm();
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            const field = target.internalLabel && typeof getFieldByInternalLabel === "function"
+                ? Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel])
+                : null;
+            if (!field || typeof field !== "object")
+                return null;
+            const getId = Reflect.get(field, "getId");
+            return typeof getId === "function" ? Reflect.apply(getId, field, []) : Reflect.get(field, "id");
+        };
+        const resolveField = async (target) => {
+            const form = await waitForForm();
+            const getField = Reflect.get(form, "getField");
+            const getFieldByInternalLabel = Reflect.get(form, "getFieldByInternalLabel");
+            if (target.internalLabel && typeof getFieldByInternalLabel === "function")
+                return Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel]);
+            if (target.fieldId != null && typeof getField === "function")
+                return Reflect.apply(getField, form, [String(target.fieldId)]);
+            return null;
+        };
+        const readValue = (field) => {
+            if (!field || typeof field !== "object")
+                return null;
+            const getValue = Reflect.get(field, "getValue");
+            return typeof getValue === "function" ? Reflect.apply(getValue, field, []) : null;
+        };
+        const writeValue = async (target, value, transactionId) => {
+            const field = await resolveField(target);
+            if (!field || typeof field !== "object")
+                return;
+            const setValue = Reflect.get(field, "setValue");
+            if (typeof setValue !== "function")
+                return;
+            await Promise.resolve(Reflect.apply(setValue, field, [value]));
+            record("write", { target, value }, transactionId);
+        };
+        const form = await waitForForm();
+        const sourceFieldId = await fieldIdFromTarget(probeOptions.source);
+        const registerFormEventListener = Reflect.get(form, "registerFormEventListener");
+        const unregisterFormEventListener = Reflect.get(form, "unregisterFormEventListener");
+        const listener = {
+            type: "change",
+            onFormEvent: async (event) => {
+                const eventObject = event && typeof event === "object" ? event : {};
+                const data = Reflect.get(eventObject, "data");
+                const dataObject = data && typeof data === "object" ? data : {};
+                const changedFieldId = Reflect.get(dataObject, "fieldId");
+                if (sourceFieldId != null && String(changedFieldId ?? "") !== String(sourceFieldId))
+                    return;
+                const transactionId = `probe-${Date.now().toString(36)}`;
+                record("change", { fieldId: changedFieldId ?? null, data }, transactionId);
+                record("effect-start", { phase: probeOptions.phase ?? "afterQuiet" }, transactionId);
+                if ((probeOptions.phase ?? "afterQuiet") === "afterQuiet" || probeOptions.phase === "afterValidation")
+                    await wait(probeOptions.quietMs ?? 250);
+                if (probeOptions.phase === "afterValidation") {
+                    const validateForm = Reflect.get(form, "validateForm");
+                    if (typeof validateForm === "function")
+                        await Promise.resolve(Reflect.apply(validateForm, form, []));
+                }
+                if (probeOptions.target) {
+                    const sourceField = await resolveField(probeOptions.source);
+                    await writeValue(probeOptions.target, probeOptions.writeValue ?? readValue(sourceField), transactionId);
+                }
+                record("effect-complete", { target: probeOptions.target ?? null }, transactionId);
+            },
+        };
+        if (typeof registerFormEventListener !== "function")
+            throw new Error("Formstack form event listener API is not available.");
+        Reflect.apply(registerFormEventListener, form, [listener]);
+        Object.defineProperty(window, propertyName, {
+            configurable: true,
+            value: {
+                traces,
+                dispose: () => {
+                    if (typeof unregisterFormEventListener === "function")
+                        Reflect.apply(unregisterFormEventListener, form, [listener]);
+                },
+            },
+        });
+        record("registered", { source: probeOptions.source, target: probeOptions.target ?? null });
+        return { installed: true, propertyName, effectId };
+    }, options);
+}
+export async function readLiveFormEffectTraces(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormEffectTraces requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((readOptions) => {
+        const propertyName = readOptions.propertyName ?? "__fsptLiveFormEffectProbe";
+        const probe = Reflect.get(window, propertyName);
+        return Array.isArray(probe?.traces) ? [...probe.traces] : [];
+    }, options);
+}
+export async function waitForLiveFormEffectTrace(page, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const intervalMs = options.intervalMs ?? 100;
+    const startedAt = Date.now();
+    const expectedKinds = options.kinds ?? ["effect-complete"];
+    let traces = await readLiveFormEffectTraces(page, options);
+    const matches = () => expectedKinds.every((kind) => traces.some((trace) => trace.kind === kind && (options.effectId === undefined || trace.effectId === options.effectId)));
+    while (!matches() && Date.now() - startedAt < timeoutMs) {
+        await delay(intervalMs);
+        traces = await readLiveFormEffectTraces(page, options);
+    }
+    return {
+        matched: matches(),
+        timedOut: !matches(),
+        traces,
+    };
+}
 export async function readLiveFormValidationState(page, options = {}) {
     if (!hasEvaluate(page)) {
         throw new Error("readLiveFormValidationState requires a Playwright page with evaluate().");