@sdods/core 0.3.2 → 0.5.2

package/dist/heal/healer.js

@@ -3,7 +3,7 @@ import { expect } from '@playwright/test';
 import { attachmentNames, scenarioFiles } from '@sdods/contracts';
 import { Logger } from '../logger.js';
 import { SdodsError } from '../errors.js';
-import { buildCandidates } from './strategies.js';
+import { buildCandidates, disambiguationCandidates, rolesFor } from './strategies.js';
 /** Locator wrapper: every action goes through the healer. */
 export class HealedLocator {
     healer;
@@ -83,54 +83,100 @@ export class Healer {
     async expectText(primary, ctx, text) {
         await expect(await this.resolve(primary, ctx, 'assert')).toContainText(text);
     }
+    /**
+     * The first of `locators`, in preference order, that matches anything. Waits up to
+     * primaryTimeoutMs for the LAST one to attach — callers list the loosest locator last, a
+     * superset of the others — so an element that renders a moment late is still judged by the
+     * most precise locator. When nothing matches, the most precise one is returned for resolve()
+     * to wait on and heal from.
+     */
+    async prefer(...locators) {
+        const loosest = locators[locators.length - 1];
+        await loosest
+            .first()
+            .waitFor({ state: 'attached', timeout: this.deps.config.primaryTimeoutMs })
+            .catch(() => undefined);
+        for (const locator of locators)
+            if ((await locator.count()) > 0)
+                return locator;
+        return locators[0];
+    }
     /**
      * Wait briefly for the primary locator; on failure probe all candidates in parallel,
-     * score them and pick the best above minScore. Records a HealEvent either way.
+     * score them and pick the best above minScore. A primary that is visible but matches several
+     * elements is healed too, for actions that have a role to prefer. Records a HealEvent whenever
+     * it heals.
      */
     async resolve(primary, ctx, action) {
         const cfg = this.deps.config;
+        const healable = cfg.enabled && cfg.actions.includes(action);
         try {
             await primary.first().waitFor({ state: 'visible', timeout: cfg.primaryTimeoutMs });
-            return primary;
         }
         catch (primaryError) {
-            if (!cfg.enabled || !cfg.actions.includes(action))
+            if (!healable)
                 throw primaryError;
             const page = primary.page();
-            const t0 = Date.now();
             const candidates = buildCandidates(page, ctx);
             if (candidates.length === 0)
                 throw primaryError;
-            const probes = await Promise.all(candidates.map((c) => this.probe(c, cfg.probeTimeoutMs, action)));
-            const ranked = probes.sort((a, b) => b.score - a.score);
-            const best = ranked[0];
-            const event = {
-                fingerprint: this.deps.scenario?.fingerprint ?? '',
-                runId: this.deps.runId ?? '',
-                stepIndex: this.deps.stepIndex?.() ?? 0,
-                action,
-                description: ctx.description,
-                pageUrl: page.url(),
-                originalSelector: String(primary),
-                context: { ...ctx, name: ctx.name instanceof RegExp ? ctx.name.toString() : ctx.name },
-                strategyUsed: best && best.score >= cfg.minScore ? best.strategy : null,
-                healedSelector: best && best.score >= cfg.minScore ? best.selector : null,
-                candidates: ranked.map(({ locator: _l, baseScore: _b, ...rest }) => rest),
-                succeeded: Boolean(best && best.score >= cfg.minScore),
-                durationMs: Date.now() - t0,
-                at: new Date().toISOString(),
-            };
-            this.record(event);
-            if (!event.succeeded || !best) {
-                throw new SdodsError('HEAL_FAILED', `Could not locate "${ctx.description}" (${String(primary)}) and no healing candidate scored ≥ ${cfg.minScore}.`, {
-                    hint: `Probed: ${ranked.map((p) => `${p.strategy}=${p.score.toFixed(2)}`).join(', ') || 'none'}. Add role/name/testId/label to the heal context or fix the locator.`,
-                    details: { candidates: event.candidates },
-                    cause: primaryError,
-                });
-            }
-            this.log.warn(`healed "${ctx.description}": ${String(primary)} → ${best.selector} via ${best.strategy} (score ${best.score.toFixed(2)}, ${event.durationMs} ms). Update the page object.`);
-            return best.locator.first();
+            // The role filter goes first: a primary whose FIRST match is hidden (a collapsed toggle
+            // ahead of the field) never becomes visible, yet narrows to the visible element that fits.
+            return this.heal(primary, ctx, action, [...disambiguationCandidates(page, primary, ctx, action), ...candidates], { cause: primaryError });
+        }
+        // Visible is not enough. A primary matching several elements makes the action throw a
+        // strict-mode violation after resolve() has returned, where healing never sees it. Assertions
+        // and hovers have no role to prefer, and their callers take .first() when they mean "any of
+        // them", so only role-bound actions are disambiguated.
+        if (!healable || rolesFor(action).length === 0)
+            return primary;
+        const matched = await primary.count();
+        if (matched <= 1)
+            return primary;
+        const page = primary.page();
+        return this.heal(primary, ctx, action, [...disambiguationCandidates(page, primary, ctx, action), ...buildCandidates(page, ctx)], { matched });
+    }
+    async heal(primary, ctx, action, candidates, why) {
+        const cfg = this.deps.config;
+        const page = primary.page();
+        const t0 = Date.now();
+        const probes = await Promise.all(candidates.map((c) => this.probe(c, cfg.probeTimeoutMs, action)));
+        const ranked = probes.sort((a, b) => b.score - a.score);
+        // Healing an ambiguity onto another ambiguous locator would only move the strict-mode
+        // violation, so that heal accepts a unique candidate only.
+        const ambiguous = why.matched !== undefined;
+        const best = ranked.find((p) => p.score >= cfg.minScore && (!ambiguous || p.count === 1));
+        const event = {
+            fingerprint: this.deps.scenario?.fingerprint ?? '',
+            runId: this.deps.runId ?? '',
+            stepIndex: this.deps.stepIndex?.() ?? 0,
+            action,
+            description: ctx.description,
+            pageUrl: page.url(),
+            originalSelector: String(primary),
+            context: { ...ctx, name: ctx.name instanceof RegExp ? ctx.name.toString() : ctx.name },
+            strategyUsed: best ? best.strategy : null,
+            healedSelector: best ? best.selector : null,
+            candidates: ranked.map(({ locator: _l, baseScore: _b, ...rest }) => rest),
+            succeeded: Boolean(best),
+            durationMs: Date.now() - t0,
+            at: new Date().toISOString(),
+        };
+        this.record(event);
+        const probed = ranked.map((p) => `${p.strategy}=${p.score.toFixed(2)}`).join(', ') || 'none';
+        if (!best) {
+            throw new SdodsError('HEAL_FAILED', ambiguous
+                ? `"${ctx.description}" (${String(primary)}) matched ${why.matched} elements and no healing candidate narrowed it to one that fits "${action}" with a score ≥ ${cfg.minScore}.`
+                : `Could not locate "${ctx.description}" (${String(primary)}) and no healing candidate scored ≥ ${cfg.minScore}.`, {
+                hint: ambiguous
+                    ? `Probed: ${probed}. Make the locator specific to one element: an exact name or label, a role, or a test id.`
+                    : `Probed: ${probed}. Add role/name/testId/label to the heal context or fix the locator.`,
+                details: { candidates: event.candidates },
+                cause: why.cause,
+            });
         }
+        this.log.warn(`healed "${ctx.description}": ${String(primary)}${ambiguous ? ` (matched ${why.matched})` : ''} → ${best.selector} via ${best.strategy} (score ${best.score.toFixed(2)}, ${event.durationMs} ms). Update the page object.`);
+        return best.locator.first();
     }
     async probe(c, timeoutMs, action) {
         const t0 = Date.now();

package/dist/heal/strategies.d.ts

@@ -1,5 +1,15 @@
-import type { Page } from '@playwright/test';
-import type { HealContext, HealProbe } from './types.js';
+import type { Locator, Page } from '@playwright/test';
+import type { AriaRole, HealAction, HealContext, HealProbe } from './types.js';
+export declare function rolesFor(action: HealAction): AriaRole[];
+/** `locator` narrowed to elements whose role fits `action`; `locator` itself when none is defined. */
+export declare function withActionRole(page: Page, locator: Locator, action: HealAction): Locator;
+/**
+ * Candidates for a primary locator that matched several elements: the primary narrowed to the
+ * roles that fit the action (and the context's own role, when it names one), as a single union.
+ * A union keeps a genuine tie ambiguous — an input and a select both labelled "Country" still
+ * count 2 for a fill — rather than letting role order break it silently.
+ */
+export declare function disambiguationCandidates(page: Page, primary: Locator, ctx: HealContext, action: HealAction): Omit<HealProbe, 'score' | 'count' | 'visible' | 'enabled' | 'ms'>[];
 /** Build candidate locators from the context, ordered by base score (higher = more semantic). */
 export declare function buildCandidates(page: Page, ctx: HealContext): Omit<HealProbe, 'score' | 'count' | 'visible' | 'enabled' | 'ms'>[];
 //# sourceMappingURL=strategies.d.ts.map

package/dist/heal/strategies.js

@@ -1,3 +1,45 @@
+/**
+ * The roles an element must have for an action to make sense on it. `assert` and `hover` apply to
+ * anything, so they have none. A contenteditable editor has no role at all, which is why callers
+ * treat a role filter as a preference, never as the only way to reach an element.
+ */
+const ACTION_ROLES = {
+    fill: ['textbox', 'searchbox', 'combobox', 'spinbutton'],
+    select: ['combobox', 'listbox'],
+    check: ['checkbox', 'radio', 'switch'],
+    click: ['button', 'link', 'menuitem', 'tab', 'option', 'checkbox', 'radio', 'switch'],
+    assert: [],
+    hover: [],
+};
+export function rolesFor(action) {
+    return ACTION_ROLES[action];
+}
+/** `locator` narrowed to elements whose role fits `action`; `locator` itself when none is defined. */
+export function withActionRole(page, locator, action) {
+    const roles = rolesFor(action);
+    if (roles.length === 0)
+        return locator;
+    return locator.and(roles.map((r) => page.getByRole(r)).reduce((union, next) => union.or(next)));
+}
+/**
+ * Candidates for a primary locator that matched several elements: the primary narrowed to the
+ * roles that fit the action (and the context's own role, when it names one), as a single union.
+ * A union keeps a genuine tie ambiguous — an input and a select both labelled "Country" still
+ * count 2 for a fill — rather than letting role order break it silently.
+ */
+export function disambiguationCandidates(page, primary, ctx, action) {
+    const roles = [...new Set([...(ctx.role ? [ctx.role] : []), ...rolesFor(action)])];
+    if (roles.length === 0)
+        return [];
+    return [
+        {
+            strategy: 'role-filter',
+            selector: `${String(primary)}.and(${roles.map((r) => `getByRole('${r}')`).join('.or(')}${')'.repeat(roles.length - 1)})`,
+            locator: primary.and(roles.map((r) => page.getByRole(r)).reduce((union, next) => union.or(next))),
+            baseScore: 1.0,
+        },
+    ];
+}
 /** Build candidate locators from the context, ordered by base score (higher = more semantic). */
 export function buildCandidates(page, ctx) {
     const out = [];

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './data/index.js';
 export * from './heal/index.js';
 export * from './shots/index.js';
 export * from './lint/index.js';
+export * from './evidence/index.js';
 export { BasePage } from './pages/base-page.js';
 export { PageRegistry } from './fixtures/pages.js';
 export { AuthStateCache } from './fixtures/auth.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './data/index.js';
 export * from './heal/index.js';
 export * from './shots/index.js';
 export * from './lint/index.js';
+export * from './evidence/index.js';
 export { BasePage } from './pages/base-page.js';
 export { PageRegistry } from './fixtures/pages.js';
 export { AuthStateCache } from './fixtures/auth.js';

package/dist/lint/index.d.ts

@@ -20,6 +20,7 @@ export declare function detectUndefinedSteps(project: ProjectConfig & {
     message: string;
     file?: string;
     line?: number;
+    rule?: string;
 }>>;
 export declare function formatFindings(result: LintResult): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/lint/index.js

@@ -1,9 +1,10 @@
 import { readdirSync, statSync, existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, resolve } from 'node:path';
 import { execa } from 'execa';
 import { BROWSERS_FOR_SKIP, KNOWN_VALUE_TAGS, LAYER_TAGS, RUNNER_SPECIAL_TAGS, VALUE_TAG, taxonomyFromProject, } from '../config/tags.js';
 import { moduleForFeature } from '../config/workspace.js';
 import { parseFeatureFile, scenariosOf } from './gherkin.js';
+import { checkStepAmbiguity } from './steps.js';
 export * from './gherkin.js';
 export function listFeatureFiles(root) {
     const out = [];
@@ -30,8 +31,10 @@ export async function lintProject(opts) {
     const errors = [];
     const warnings = [];
     const rel = (f) => relative(project.root, f).replace(/\\/g, '/');
+    const parsedFeatures = [];
     for (const file of files) {
         const parsed = parseFeatureFile(file);
+        parsedFeatures.push(parsed);
         for (const e of parsed.errors)
             errors.push({
                 severity: 'error',
@@ -213,16 +216,25 @@ export async function lintProject(opts) {
                 seen.set(key, sc.line);
         }
     }
+    // A phrasing matched by two definitions stops bddgen generating anything (#60).
+    const ambiguity = await checkStepAmbiguity({ project, features: parsedFeatures });
+    errors.push(...ambiguity.errors);
+    warnings.push(...ambiguity.warnings);
     if (opts.undefinedSteps && opts.repoRoot) {
         const found = await detectUndefinedSteps(project, opts.repoRoot);
-        for (const f of found)
+        for (const f of found) {
+            const rule = f.rule ?? 'steps/undefined';
+            // The static check above usually saw this ambiguity already; do not report it twice.
+            if (errors.some((e) => e.rule === rule && e.file === f.file && e.line === f.line))
+                continue;
             errors.push({
                 severity: 'error',
-                rule: 'steps/undefined',
+                rule,
                 message: f.message,
                 file: f.file ?? '',
                 line: f.line,
             });
+        }
     }
     return { errors, warnings, filesChecked: files.length };
 }
@@ -266,6 +278,35 @@ export async function detectUndefinedSteps(project, repoRoot) {
                 .slice(0, 10)
                 .join(' | '),
         });
+    // bddgen stops at the first ambiguous step. This parser only knew the missing-step block, so an
+    // ambiguity (#60) — or any other generation failure — came back as "no findings".
+    const ambiguous = /^Step: (.+?) # (.+\.feature):(\d+)(?::\d+)?$/;
+    for (let i = 0; i < lines.length; i++) {
+        const s = ambiguous.exec(lines[i].trim());
+        if (!s || !/Multiple definitions matched/.test(lines[i - 1] ?? ''))
+            continue;
+        const variants = [];
+        for (let j = i + 1; j < lines.length && lines[j].trim().startsWith('- '); j++)
+            variants.push(lines[j].trim().slice(2));
+        out.push({
+            rule: 'steps/ambiguous',
+            message: `Multiple definitions matched "${s[1]}": ${variants.join('; ')}`,
+            file: relative(project.root, resolve(repoRoot, s[2])).replace(/\\/g, '/'),
+            line: Number(s[3]),
+        });
+    }
+    if (!out.length) {
+        const tail = text
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .slice(-5)
+            .join(' | ');
+        out.push({
+            rule: 'steps/bddgen',
+            message: `bddgen failed to generate specs (exit ${result.exitCode}): ${tail || '(no output)'}`,
+        });
+    }
     return out;
 }
 export function formatFindings(result) {

package/dist/lint/steps.d.ts

@@ -0,0 +1,13 @@
+import type { LintFinding, ProjectConfig } from '@sdods/contracts';
+import type { ParsedFeature } from './gherkin.js';
+export interface AmbiguityCheckOptions {
+    project: ProjectConfig & {
+        root: string;
+    };
+    features: ParsedFeature[];
+}
+export declare function checkStepAmbiguity(opts: AmbiguityCheckOptions): Promise<{
+    errors: LintFinding[];
+    warnings: LintFinding[];
+}>;
+//# sourceMappingURL=steps.d.ts.map