@redrockswebdevelopment/formstack-form-testing 0.1.42 → 0.1.44

package/dist/index.js

@@ -16,6 +16,17 @@ export class FormScenarioRunError extends Error {
         this.result = result;
     }
 }
+export class LiveFormTestingError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.name = "LiveFormTestingError";
+        this.code = code;
+        if (detail)
+            this.detail = detail;
+    }
+}
 export const liveFormFieldTypeCoverage = {
     address: {
         kind: "address",
@@ -247,6 +258,70 @@ export const liveFormFieldTypeCoverage = {
 export function getLiveFormFieldTypeCoverage(kind) {
     return liveFormFieldTypeCoverage[kind];
 }
+export function createLiveFormTestingError(code, message, detail) {
+    return new LiveFormTestingError(code, message, detail);
+}
+export const liveFormCiProfiles = {
+    "fast-smoke": {
+        name: "fast-smoke",
+        projects: ["chromium"],
+        recommendedRetries: 1,
+        includeVisualBaselines: false,
+        includeHostedSubmissions: false,
+        includePaymentFields: false,
+        defaultTimeoutMs: 30_000,
+        description: "Fast deterministic checks for package and client CI on every commit.",
+    },
+    "hosted-regression": {
+        name: "hosted-regression",
+        projects: ["chromium", "mobile-chrome"],
+        recommendedRetries: 2,
+        includeVisualBaselines: false,
+        includeHostedSubmissions: true,
+        includePaymentFields: false,
+        defaultTimeoutMs: 60_000,
+        description: "Hosted Formstack checks for helper compatibility, custom code behavior, and submission payload probes.",
+    },
+    "full-browser": {
+        name: "full-browser",
+        projects: ["chromium", "mobile-chrome", "webkit"],
+        recommendedRetries: 2,
+        includeVisualBaselines: true,
+        includeHostedSubmissions: true,
+        includePaymentFields: false,
+        defaultTimeoutMs: 90_000,
+        description: "Full browser regression profile for release candidates and project acceptance.",
+    },
+};
+export function getLiveFormCiProfile(name) {
+    return liveFormCiProfiles[name];
+}
+export function createLiveFormFixtureRegistry(fixtures) {
+    const seen = new Set();
+    for (const fixture of fixtures) {
+        if (seen.has(fixture.key)) {
+            throw createLiveFormTestingError("fixture-not-found", `Duplicate live form fixture key "${fixture.key}".`, { key: fixture.key });
+        }
+        seen.add(fixture.key);
+    }
+    return { fixtures: [...fixtures] };
+}
+export function selectLiveFormFixture(registry, options) {
+    const tags = new Set(options.tags ?? []);
+    const fixture = registry.fixtures.find((entry) => {
+        if (options.key !== undefined && entry.key !== options.key)
+            return false;
+        if (options.environment !== undefined && entry.environment !== options.environment)
+            return false;
+        if (tags.size > 0 && ![...tags].every((tag) => entry.tags?.includes(tag)))
+            return false;
+        return true;
+    });
+    if (!fixture) {
+        throw createLiveFormTestingError("fixture-not-found", "No live form fixture matched the requested selector.", { options });
+    }
+    return fixture;
+}
 export function summarizeLiveFormFieldCoverage(reportOrFields) {
     const fields = "fields" in reportOrFields ? reportOrFields.fields : reportOrFields;
     const countsByKind = {};
@@ -268,6 +343,62 @@ export function summarizeLiveFormFieldCoverage(reportOrFields) {
 export async function readLiveFormFieldCoverage(page, options = {}) {
     return summarizeLiveFormFieldCoverage(await discoverLiveFormFieldShapes(page, options));
 }
+export async function diagnoseLiveFormUnknownFields(page, options = {}) {
+    const coverage = await readLiveFormFieldCoverage(page, options);
+    const unknownFields = coverage.fields.filter((field) => field.inferredKind === "unknown");
+    const metadata = options.includeMetadata === false || unknownFields.length === 0
+        ? undefined
+        : await readLiveFormApiMetadataSnapshot(page, {
+            fieldTargets: unknownFields.map((field) => ({
+                ...(field.fieldId == null ? {} : { fieldId: field.fieldId }),
+                ...(field.internalLabel == null ? {} : { internalLabel: field.internalLabel }),
+            })),
+            ...(options.includeValues === undefined ? {} : { includeValues: options.includeValues }),
+        });
+    const metadataByLabel = new Map((metadata?.fields ?? []).map((field) => [field.internalLabel, field]));
+    const suggestionsFor = (field) => {
+        const text = field.labelText.toLowerCase();
+        const types = new Set(field.controlTypes);
+        const label = field.internalLabel?.toLowerCase() ?? "";
+        const suggestions = [];
+        if (types.has("hidden") && field.controlTypes.length === 1) {
+            suggestions.push({ kind: "hidden", reason: "Field exposes only hidden controls.", confidence: "medium" });
+        }
+        if (label.includes("calc") || text.includes("calculation") || text.includes("total")) {
+            suggestions.push({ kind: "calculation", reason: "Field label or internal label suggests a derived calculation.", confidence: "medium" });
+        }
+        if (types.has("date"))
+            suggestions.push({ kind: "date", reason: "Field contains a native date input.", confidence: "high" });
+        if (types.has("number"))
+            suggestions.push({ kind: "number", reason: "Field contains a native number input.", confidence: "high" });
+        if (types.has("text"))
+            suggestions.push({ kind: "text", reason: "Field contains text controls but no stronger field-specific markers.", confidence: "low" });
+        if (field.controlCount === 0)
+            suggestions.push({ kind: "description", reason: "Field has no controls and may be display-only content.", confidence: "low" });
+        return suggestions;
+    };
+    const diagnostics = unknownFields.map((field) => {
+        const suggestions = suggestionsFor(field);
+        const fieldMetadata = field.internalLabel === null ? undefined : metadataByLabel.get(field.internalLabel);
+        return {
+            field,
+            suggestions,
+            ...(fieldMetadata === undefined ? {} : { metadata: fieldMetadata }),
+            recommendedNextSteps: [
+                "Attach the field diagnostic JSON and screenshot to the failing test artifact.",
+                "Inspect stable data-internal-label, controls, API methods, and Formstack field settings.",
+                suggestions.length > 0
+                    ? `Try an inferred-kind override or helper for ${suggestions[0]?.kind}.`
+                    : "Add a package-level inferred kind or a project-specific helper before automating this field.",
+            ],
+        };
+    });
+    return {
+        unknownFields: diagnostics,
+        hasUnknownFields: diagnostics.length > 0,
+        ...(options.screenshotPath === undefined ? {} : { screenshotPath: options.screenshotPath }),
+    };
+}
 function formatCoverageField(field) {
     return `${field.inferredKind}:${field.internalLabel ?? field.domId ?? "unlabeled"}`;
 }
@@ -299,7 +430,12 @@ export function assertLiveFormFieldCoverage(report, options = {}) {
         }
     }
     if (failures.length > 0) {
-        throw new Error(`Live form field coverage assertion failed: ${failures.join("; ")}`);
+        throw createLiveFormTestingError("field-coverage-failed", `Live form field coverage assertion failed: ${failures.join("; ")}`, {
+            failures,
+            countsByKind: report.countsByKind,
+            unknownFields: report.uncovered.map(formatCoverageField),
+            paymentFields: report.paymentFields.map(formatCoverageField),
+        });
     }
 }
 function matchesPattern(value, pattern) {
@@ -3730,6 +3866,121 @@ export async function readLiveFormStateDrift(page, options = {}) {
         hasDrift: issues.length > 0,
     };
 }
+export async function readLiveFormApiMetadataSnapshot(page, options = {}) {
+    if (!hasEvaluate(page)) {
+        throw new Error("readLiveFormApiMetadataSnapshot requires a Playwright page with evaluate().");
+    }
+    return page.evaluate((metadataOptions) => {
+        const methodNames = metadataOptions.methodNames ?? [
+            "getId",
+            "getValue",
+            "setValue",
+            "getInfo",
+            "getGeneralAttribute",
+            "setGeneralAttribute",
+            "validate",
+            "setSkipValidation",
+        ];
+        const domSelector = metadataOptions.snapshot?.selector ?? "[data-internal-label]";
+        const textMaxLength = metadataOptions.snapshot?.textMaxLength ?? 160;
+        const controlSnapshot = (control) => {
+            const input = control;
+            return {
+                tagName: control.tagName.toLowerCase(),
+                type: control.getAttribute("type"),
+                id: control.getAttribute("id"),
+                name: control.getAttribute("name"),
+                value: control.getAttribute("value"),
+                currentValue: "value" in input ? input.value : null,
+                checked: control instanceof HTMLInputElement && ["checkbox", "radio"].includes(input.type) ? control.checked : null,
+            };
+        };
+        const domFields = Array.from(document.querySelectorAll(domSelector)).map((element) => ({
+            internalLabel: element.getAttribute("data-internal-label"),
+            id: element.id,
+            text: element.textContent?.replace(/\s+/g, " ").trim().slice(0, textMaxLength) ?? "",
+            controls: Array.from(element.querySelectorAll("input, textarea, select")).map(controlSnapshot),
+        }));
+        const domByInternalLabel = new Map(domFields.map((field) => [field.internalLabel, field]));
+        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, []) : [];
+            const form = Array.isArray(forms) ? forms[0] ?? null : null;
+            return { form, apiAvailable: Boolean(api && typeof api === "object") };
+        };
+        const { form, apiAvailable } = readApi();
+        const formAvailable = Boolean(form && typeof form === "object");
+        const formId = formAvailable ? Reflect.get(form, "id") ?? Reflect.get(form, "formId") ?? null : null;
+        const formMethodNames = formAvailable
+            ? [...new Set([
+                    ...Object.keys(form),
+                    ...Object.getOwnPropertyNames(Object.getPrototypeOf(form) ?? {}),
+                ])].filter((name) => typeof Reflect.get(form, name) === "function").sort()
+            : [];
+        const getField = formAvailable ? Reflect.get(form, "getField") : null;
+        const getFieldByInternalLabel = formAvailable ? Reflect.get(form, "getFieldByInternalLabel") : null;
+        const targets = metadataOptions.fieldTargets ?? (metadataOptions.includeAllDomFields === false
+            ? []
+            : domFields
+                .map((field) => field.internalLabel)
+                .filter((internalLabel) => Boolean(internalLabel))
+                .map((internalLabel) => ({ internalLabel })));
+        const resolveField = (target) => target.fieldId != null && typeof getField === "function"
+            ? Reflect.apply(getField, form, [String(target.fieldId)])
+            : target.internalLabel && typeof getFieldByInternalLabel === "function"
+                ? Reflect.apply(getFieldByInternalLabel, form, [target.internalLabel])
+                : null;
+        const readAttribute = (field, name) => {
+            if (!field || typeof field !== "object")
+                return undefined;
+            const getGeneralAttribute = Reflect.get(field, "getGeneralAttribute");
+            return typeof getGeneralAttribute === "function" ? Reflect.apply(getGeneralAttribute, field, [name]) : undefined;
+        };
+        const fields = targets.map((target) => {
+            const field = resolveField(target);
+            const fieldAvailable = Boolean(field && typeof field === "object");
+            const getId = fieldAvailable ? Reflect.get(field, "getId") : null;
+            const getValue = fieldAvailable ? Reflect.get(field, "getValue") : null;
+            const getInfo = fieldAvailable ? Reflect.get(field, "getInfo") : null;
+            const id = fieldAvailable
+                ? typeof getId === "function"
+                    ? Reflect.apply(getId, field, [])
+                    : Reflect.get(field, "id") ?? target.fieldId ?? null
+                : target.fieldId ?? null;
+            const internalLabel = target.internalLabel ?? (fieldAvailable ? Reflect.get(field, "internalLabel") ?? null : null);
+            const fieldMethodNames = fieldAvailable
+                ? [...new Set([
+                        ...Object.keys(field),
+                        ...Object.getOwnPropertyNames(Object.getPrototypeOf(field) ?? {}),
+                    ])].filter((name) => typeof Reflect.get(field, name) === "function").sort()
+                : [];
+            const dom = internalLabel ? domByInternalLabel.get(String(internalLabel)) ?? null : null;
+            return {
+                target,
+                fieldAvailable,
+                id,
+                internalLabel: internalLabel == null ? null : String(internalLabel),
+                ...(metadataOptions.includeValues === false || typeof getValue !== "function" ? {} : { value: Reflect.apply(getValue, field, []) }),
+                ...(typeof getInfo !== "function" ? {} : { info: Reflect.apply(getInfo, field, []) }),
+                hidden: readAttribute(field, "hidden"),
+                required: readAttribute(field, "required"),
+                skipValidation: readAttribute(field, "skipValidation"),
+                methodNames: fieldMethodNames,
+                methods: methodNames.map((name) => ({ name, available: fieldAvailable && typeof Reflect.get(field, name) === "function" })),
+                dom,
+            };
+        });
+        return {
+            apiAvailable,
+            formAvailable,
+            formId,
+            formMethodNames,
+            fields,
+        };
+    }, options);
+}
 export async function discoverLiveFormFieldShapes(page, options = {}) {
     if (!hasEvaluate(page)) {
         throw new Error("discoverLiveFormFieldShapes requires a Playwright page with evaluate().");
@@ -3807,11 +4058,6 @@ export async function discoverLiveFormFieldShapes(page, options = {}) {
                 }
                 return "description";
             }
-            if (internalLabel.includes("hidden") ||
-                classes.includes("hidden-field") ||
-                controls.every((control) => control.type === "hidden")) {
-                return "hidden";
-            }
             if (classes.includes("matrix") || internalLabel.includes("matrix") || element.querySelector("[id^='matrix-row-'], table"))
                 return "matrix";
             if (classes.includes("rating") || internalLabel.includes("rating"))
@@ -3844,6 +4090,11 @@ export async function discoverLiveFormFieldShapes(page, options = {}) {
                 return "datetime";
             if (types.has("date") || internalLabel.includes("date"))
                 return "date";
+            if (internalLabel.includes("hidden") ||
+                classes.includes("hidden-field") ||
+                controls.every((control) => control.type === "hidden")) {
+                return "hidden";
+            }
             if (types.has("text"))
                 return "text";
             return "unknown";