@sun-asterisk/sungen 3.2.29 → 3.2.30

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -8,6 +8,9 @@ import { SelectorType } from '../../../utils/selector-types';
 import { DataResolver } from './data-resolver';
 import { DiagnosticsCollector } from '../diagnostics';
 import { DEFAULT_CONTENT_NAMED_ROLES } from '../app-profile';
+import { reportUnknownEntryFields } from './selector-entry-fields';
+import { reportUnknownSelectorTypes } from './selector-type-validation';
+import { normalizeNth, reportInvalidNth } from './selector-nth-validation';
 
 // Structured selector format v2
 interface SelectorEntry {
@@ -15,7 +18,8 @@ interface SelectorEntry {
   type?: SelectorType;    // Locator strategy
   value?: string;         // Natural language value for the locator (e.g., 'button', 'link' for role)
   name?: string;          // Accessible name for role-based selectors (e.g., 'Login', 'Submit')
-  nth?: number;           // Element index (undefined = no .nth(), 0+ = .nth(N))
+  nth?: number;           // Element index: undefined = no positional filter, 0+ = that index,
+                          // -1 = the last match. Anything else is dropped + SG-W018 (#720)
   exact?: boolean;        // Whether to use exact matching (default: false)
   inputMethod?: string;   // 'pressSequentially' for contenteditable/rich-text elements
 
@@ -53,6 +57,22 @@ interface SelectorEntry {
   // entry, which positions ONE row (`tbody tr:first-child`) — a shape is a property of the table.
   rows?: string;
 
+  // === Checked/selected state signal (issue #730) ===
+  // How a control publishes its on/off state when it publishes NO ARIA. A Tailwind checkbox or
+  // card picker — a <div> with a class swap and no <input>, no role, no aria-checked/aria-pressed —
+  // has no state for `check`/`uncheck` to drive or for `is checked`/`is selected` to read, so every
+  // such step failed with "it has no on/off state to set" no matter how right the selector was.
+  // `checked: { class: 'is-checked' }` names the class that marks the ON state.
+  //
+  // `selected:` is an ALIAS for the same signal, not a second one: a card picker declaring
+  // `checked:` reads wrong, and `is selected` on a non-ARIA element already falls through to the
+  // checked family (selected-assertion.hbs). Declaring both is a conflict — see resolveFromEntry.
+  // `checked.attribute` is the same signal published as a boolean attribute ('true'/'false')
+  // instead of a class, for a control that swaps `data-checked` rather than a class token.
+  // Declare ONE of the two per entry: class and attribute are two ways to read one state.
+  checked?: { class?: string; attribute?: string };
+  selected?: { class?: string; attribute?: string };
+
   // === v2: Assertion Helpers ===
   attribute?: string;     // Attribute to check (for "has" assertions)
   pattern?: string;       // Regex for attribute value
@@ -123,7 +143,7 @@ export interface ResolvedSelector {
   role?: string;        // For role-based selectors (e.g., 'button', 'link')
   name?: string;        // For accessible name in role selectors
   locator?: string;     // CSS locator for fallback
-  nth?: number;         // Index for .nth() if multiple matches exist
+  nth?: number;         // Index for .nth() if multiple matches exist (0+, or -1 = last match)
   exact?: boolean;      // Whether to use exact matching (default: false)
   inputMethod?: string; // 'pressSequentially' for contenteditable/rich-text elements
 
@@ -140,6 +160,11 @@ export interface ResolvedSelector {
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
   expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
+  // Class / boolean attribute marking the ON state, normalised from `checked:`/`selected:`
+  // (issue #730). Flat rather than an object because ONE resolved signal is what every consumer
+  // needs — the two YAML spellings are an authoring convenience, not two different things.
+  checkedClass?: string;
+  checkedAttribute?: string;
   anchor?: ResolvedSelector;  // page entries only — the rendered-content proof behind `see [X] page` (#662)
 }
 
@@ -188,7 +213,7 @@ export class SelectorResolver {
     return this.platform === 'mobile' && !!r && r.strategy === 'role' && !r.name;
   }
 
-  /** Attach the compile-diagnostics collector (SG-W003) */
+  /** Attach the compile-diagnostics collector (SG-W003, SG-W016, SG-W030) */
   setDiagnostics(collector: DiagnosticsCollector): void {
     this.diagnostics = collector;
   }
@@ -595,9 +620,137 @@ export class SelectorResolver {
     });
   }
 
+  /** Encode `{{var}}` references inside a table's `columns: { <col>: { header } }` map. */
+  private static resolveColumnHeaders(
+    columns: NonNullable<SelectorEntry['columns']>,
+  ): NonNullable<SelectorEntry['columns']> {
+    const out: NonNullable<SelectorEntry['columns']> = {};
+    for (const [key, col] of Object.entries(columns)) {
+      out[key] = col && typeof col.header === 'string'
+        ? { ...col, header: SelectorResolver.resolveTemplateVars(col.header) }
+        : col;
+    }
+    return out;
+  }
+
+  /**
+   * Normalise `checked:` / `selected:` into the one signal consumers read (issue #730). The two
+   * spellings are an authoring convenience for the same thing — `checked:` on a toggle, `selected:`
+   * on a card/tab picker — so they collapse here rather than at every call site. Each spelling can
+   * publish the state as a class token or as a boolean attribute; one entry declares one of them.
+   *
+   * Validated at CODEGEN because every failure mode here is silent at run time: the class token
+   * lands inside `[class~="..."]`, where a quote breaks the selector and whitespace can never match
+   * (the `~=` operator matches ONE whitespace-separated token, so 'a b' matches nothing at all and
+   * the step would just time out claiming the control never changed state); an attribute name has
+   * the same exposure inside `[name="true"]`. Refused rather than warned-and-dropped, unlike
+   * `expanded:`: dropping this signal leaves the step with nothing to read, so it would fail again
+   * with the original "no on/off state" error and hide the real cause.
+   */
+  private resolveCheckedSignal(
+    entry: SelectorEntry,
+    label: string,
+  ): { class?: string; attribute?: string } | undefined {
+    const signal: { class?: string; attribute?: string } = {};
+    // Recorded BEFORE it is thrown, every time. A pattern that resolves its selector inside a
+    // `catch {}` — several do, to fall back when a `[Ref]` simply is not in the file — would
+    // otherwise swallow the refusal whole and emit a step against an unresolved locator, with
+    // nothing anywhere naming the entry. The throw is what stops the file; the diagnostic is what
+    // survives a caller that decided not to be stopped, and what `--strict` counts.
+    const refuse = (message: string): never => {
+      this.diagnostics?.add('SG-E031', message, { feature: this.featureName });
+      throw new Error(message);
+    };
+
+    for (const key of ['class', 'attribute'] as const) {
+      const fromChecked = entry.checked?.[key]?.trim();
+      const fromSelected = entry.selected?.[key]?.trim();
+
+      if (fromChecked && fromSelected && fromChecked !== fromSelected) {
+        refuse(
+          `Selector "[${label}]" declares both \`checked.${key}\` ("${fromChecked}") and ` +
+          `\`selected.${key}\` ("${fromSelected}") with different values. They are two spellings of ONE ` +
+          `signal — how the control marks its ON state — so only one can be right. Keep \`checked:\` for ` +
+          `a toggle/checkbox or \`selected:\` for a card/tab picker, and delete the other.`
+        );
+      }
+
+      const value = fromChecked || fromSelected;
+      if (!value) continue;
+
+      if (/\s/.test(value)) {
+        refuse(
+          `Selector "[${label}]" declares checked/selected ${key} "${value}", which contains whitespace. ` +
+          `This must be ONE ${key === 'class' ? 'class token, not a class list' : 'attribute name'}: the ` +
+          `generated matcher tests a single token, so a multi-token value can never match and the step ` +
+          `would time out rather than fail clearly. Pick the one ${key} that marks the ON state ` +
+          `(e.g. '${key === 'class' ? 'border-link' : 'data-checked'}', not ` +
+          `'${key === 'class' ? 'card border-link' : 'data-checked aria-checked'}').`
+        );
+      }
+      if (value.includes('"') || value.includes('\\')) {
+        refuse(
+          `Selector "[${label}]" declares checked/selected ${key} "${value}", which contains a quote or ` +
+          `backslash. The value is embedded in a [${key === 'class' ? 'class~="..."' : 'name="true"'}] CSS ` +
+          `selector, which those characters would break. A ${key} carrying them is almost certainly a typo.`
+        );
+      }
+      signal[key] = value;
+    }
+
+    if (signal.class && signal.attribute) {
+      refuse(
+        `Selector "[${label}]" declares both a checked/selected \`class\` ("${signal.class}") and ` +
+        `\`attribute\` ("${signal.attribute}"). One control publishes its ON state one way — declaring ` +
+        `two lets an action drive one signal while the assertion after it reads the other. Keep the one ` +
+        `the component actually swaps.`
+      );
+    }
+
+    return signal.class || signal.attribute ? signal : undefined;
+  }
+
   /**
    * Resolve from new structured entry format
    */
+  /**
+   * An `expanded:` signal's `class` / `attribute` value is pasted into the generated spec — into a
+   * string literal, a regex, a `classList.contains()` argument. selectors.yaml is often generated
+   * from the page under test, so a value carrying a quote, a `${`, whitespace or any other character
+   * a class or attribute name cannot legitimately contain is refused (diagnostic + the field is
+   * dropped) rather than compiled into code. Dropping it leaves a working step — codegen falls back
+   * to driving/asserting `aria-expanded` — which is why this warns where the checked/selected signal,
+   * whose fallback is the failure it exists to fix, refuses outright.
+   */
+  private validatedStateSignal(
+    signal: { class?: string; attribute?: string },
+    field: string,
+    label: string,
+  ): { class?: string; attribute?: string } | undefined {
+    // Letters, digits and the punctuation real class/attribute names use — including Tailwind
+    // arbitrary values (`bg-[#eff6ff]`, `!mt-0`, `@md:flex`, `w-[calc(100%-2rem)]`). Excluded on
+    // purpose: whitespace, quotes, backticks, backslash, `$`/`{`/`}` — the characters that could
+    // close a literal or open an interpolation in the generated code.
+    const SAFE = /^[A-Za-z0-9_\-:./[\]%#!@(),&+=*~|?]+$/;
+    const out: { class?: string; attribute?: string } = {};
+    for (const key of ['class', 'attribute'] as const) {
+      const value = signal[key];
+      if (value === undefined || value === null) continue;
+      const text = String(value);
+      if (SAFE.test(text)) { out[key] = text; continue; }
+      const warnKey = `w030:${label}:${field}.${key}`;
+      if (!this.warnedContentNamed.has(warnKey)) { // once per entry+field, not once per step that uses it
+        this.warnedContentNamed.add(warnKey);
+        this.diagnostics?.add(
+          'SG-W030',
+          `selector "${label}": ${field}.${key} ${JSON.stringify(text)} is not accepted as a ${key} name (no whitespace, quotes, backslash, \`$\`, \`{\` or \`}\`) — the value is ignored and the step compiles to its default form`,
+          { feature: this.featureName },
+        );
+      }
+    }
+    return out.class || out.attribute ? out : undefined;
+  }
+
   private resolveFromEntry(entry: SelectorEntry, originalLabel: string): ResolvedSelector {
     // Default values
     const locator = entry.locator || '';
@@ -619,9 +772,22 @@ export class SelectorResolver {
       : (entry.name ?? '');
     const value = SelectorResolver.resolveTemplateVars(rawValue);
     const name = SelectorResolver.resolveTemplateVars(rawName);
-    const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
+    // `nth:` is the one field whose VALUE nothing used to check (#720): anything non-null was
+    // handed to the adapters, which disagreed about it — web dropped `-1` silently, mobile emitted
+    // `$$(...)[-1]`. Normalised to a real index (integer >= -1) or `undefined` HERE, so no template
+    // ever renders a value it cannot express; the out-of-contract write is reported as SG-W018 at
+    // the file load point below.
+    const nth = normalizeNth(entry.nth);
     const exact = entry.exact === true || entry.match === 'exact';
-    const inputMethod = entry.inputMethod;
+    // `contenteditable: true` is the MANUAL override for a rich-text editor (#712). It was a
+    // documented, plumbed field that nothing read: the rich-text decision lives in driver-ui's
+    // fill pattern, which gates on `inputMethod` to pick `fill-editor-action`, so an author who
+    // followed the selector reference and wrote `contenteditable: true` got a plain `.fill()` and
+    // no diagnostic. Forcing the input method HERE rather than adding a second condition in the
+    // pattern keeps ONE rich-text signal on ResolvedSelector, so every consumer — current and
+    // future — reads the intent off a single field. An explicit `inputMethod` is more specific and
+    // still wins, so the two may be mixed without surprise.
+    const inputMethod = entry.inputMethod ?? (entry.contenteditable ? 'pressSequentially' : undefined);
 
     // v2 fields
     const v2Fields: Partial<ResolvedSelector> = {};
@@ -631,12 +797,21 @@ export class SelectorResolver {
     if (entry.trigger) v2Fields.trigger = entry.trigger;
     if (entry.frame) v2Fields.frame = entry.frame;
     if (entry.contenteditable) v2Fields.contenteditable = true;
-    if (entry.columns) v2Fields.columns = entry.columns;
+    // A column's `header` is DOM text like any other selector field, so a `{{var}}` in it is a
+    // runtime reference — the same i18n escape hatch `name:`/`value:` have. Encoded here rather
+    // than at the read site so every consumer of the map gets it (issue #674).
+    if (entry.columns) v2Fields.columns = SelectorResolver.resolveColumnHeaders(entry.columns);
     if (entry.pagination) v2Fields.pagination = entry.pagination;
     if (typeof entry.rows === 'string' && entry.rows.trim()) v2Fields.rows = entry.rows.trim();
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
-    if (entry.expanded) v2Fields.expanded = entry.expanded;
+    if (entry.expanded) {
+      const expanded = this.validatedStateSignal(entry.expanded, 'expanded', originalLabel);
+      if (expanded || entry.expanded.state) v2Fields.expanded = { ...expanded, ...(entry.expanded.state ? { state: entry.expanded.state } : {}) };
+    }
+    const checked = this.resolveCheckedSignal(entry, originalLabel);
+    if (checked?.class) v2Fields.checkedClass = checked.class;
+    if (checked?.attribute) v2Fields.checkedAttribute = checked.attribute;
     // The anchor is a selector in its own right; it must not inherit the PAGE's label as its
     // accessible name, so it resolves against its own name (or nothing).
     if (entry.anchor) v2Fields.anchor = this.resolveFromEntry(entry.anchor, entry.anchor.name ?? '');
@@ -672,7 +847,26 @@ export class SelectorResolver {
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly.
     // `exact` travels along: a locator LIST filtered by a test-data value (hasText) matches by
     // substring by default, and `exact: true` in the YAML opts into the anchored full-text match.
-    if (type === 'locator') {
+    //
+    // `upload` rides the SAME branch rather than getting a case of its own. A file input is
+    // addressed by CSS in practice (`input[type=file]`, an id, a testid wrapper), and the selector
+    // reference has always documented `upload` as `page.locator(value).setInputFiles()` — so the
+    // two spellings must resolve identically or teams migrating off the workaround get a silent
+    // behaviour change. It had no case at all before, so it fell through to `default:` and
+    // compiled to `getByPlaceholder('<the CSS string>')` — a locator hunting an input whose
+    // placeholder ATTRIBUTE is the literal text `input[type=file]`, which no page has. It failed
+    // at run time with no diagnostic, and the only way out was to work out for oneself that
+    // `type: locator` had to be used instead, which no page of the reference says (issue #690).
+    //
+    // Handled HERE, above the generic `locator:`-field branch below, because that branch returns
+    // strategy 'css' and drops `exact` — putting `upload` in the switch left the two spellings
+    // diverging for any entry that sets `locator:`. `withExtras` still stamps the declared
+    // `selectorType`, so a consumer that needs to tell an upload from a plain locator still can.
+    //
+    // `exact` is inert for the upload action itself (`setInputFiles` takes no text filter), but it
+    // is NOT dead: the same key reused by a filtered step (`… with {{v}}`) reaches has-text-value,
+    // which reads `exact` regardless of strategy.
+    if (type === 'locator' || type === 'upload') {
       const locatorValue = locator && locator.trim() ? locator : value;
       return withExtras({
         strategy: 'locator',
@@ -798,7 +992,14 @@ export class SelectorResolver {
         });
 
       default:
-        // Fallback to placeholder
+        // Reached by the NON_STRATEGY_SELECTOR_TYPES (`page`/`table`/`column`/`frame`, whose
+        // consumers read the entry or `selectorType` rather than `strategy`) and by a type this
+        // compiler does not know at all — YAML is untyped at run time, so a misspelling lands
+        // here too. The placeholder result is inert for the first group and wrong for the second,
+        // but it MUST NOT throw: `page` alone reaches this branch on every page assertion.
+        // What must never arrive here is a STRATEGY type — that is the #690 defect, and
+        // tests/codegen/selector-type-dispatch.run.ts fails the build if one does (it checks the
+        // resolved strategy, so an early return above satisfies it as well as a `case` here).
         return withExtras({
           strategy: 'placeholder',
           value,
@@ -813,13 +1014,18 @@ export class SelectorResolver {
    * Returns metadata only - no framework-specific code
    */
   private resolveByPriority(element: LegacySelectorElement): ResolvedSelector {
+    // The legacy format never passes through the SG-W018 file check (that walks new-format
+    // entries), so it is normalised here instead — a template must never see an index it cannot
+    // express, whichever door the entry came through.
+    const nth = normalizeNth(element.nth);
+
     // Extract data-testid from locator if present
     const testIdMatch = element.locator.match(/\[data-testid=["']([^"']+)["']\]/);
     if (testIdMatch) {
       return {
         strategy: 'testid',
         value: testIdMatch[1],
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -830,7 +1036,7 @@ export class SelectorResolver {
         role: 'button',
         name: element.value,
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -838,7 +1044,7 @@ export class SelectorResolver {
       return {
         strategy: 'placeholder',
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -846,7 +1052,7 @@ export class SelectorResolver {
       return {
         strategy: 'label',
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -854,7 +1060,7 @@ export class SelectorResolver {
       return {
         strategy: 'text',
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -865,7 +1071,7 @@ export class SelectorResolver {
         strategy: 'id',
         value: idMatch[1],
         locator: `#${idMatch[1]}`,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -874,7 +1080,7 @@ export class SelectorResolver {
       strategy: 'css',
       value: element.locator,
       locator: element.locator,
-      nth: element.nth,
+      nth,
     };
   }
 
@@ -924,6 +1130,29 @@ export class SelectorResolver {
       }
     }
 
+    // SG-W004 — a field nothing reads (#712). Reported HERE, at the one cached load point, so a
+    // table named by twenty row steps warns once rather than twenty times.
+    reportUnknownEntryFields(selectors as Record<string, unknown>, {
+      feature: featureName,
+      diagnostics: this.diagnostics,
+    });
+
+    // SG-E027 — a `type:` nothing dispatches (#711). Same load point and same once-per-file
+    // reason as SG-W004 above: the two checks are the same question one level apart (an unknown
+    // KEY vs an unknown VALUE for a known key), and both want the file in hand to name the entry.
+    reportUnknownSelectorTypes(selectors as Record<string, unknown>, {
+      feature: featureName,
+      diagnostics: this.diagnostics,
+    });
+
+    // SG-W018 — an `nth:` value outside the contract (#720). Third of the same family at the same
+    // load point: SG-W004 asks whether anything READS the key, SG-E027 whether the `type:` VALUE
+    // dispatches, this one whether the `nth:` VALUE is an index the adapters can express.
+    reportInvalidNth(selectors as Record<string, unknown>, {
+      feature: featureName,
+      diagnostics: this.diagnostics,
+    });
+
     this.selectorCache.set(cacheKey, selectors);
     return selectors;
   }

package/src/generators/test-generator/utils/selector-type-validation.ts

@@ -0,0 +1,87 @@
+/**
+ * SG-E027 — an entry `type:` the compiler does not know (issue #711).
+ *
+ * `selectors.yaml` is YAML, so `type:` is an arbitrary string at run time. `VALID_SELECTOR_TYPES`
+ * constrained it only through the `SelectorType` TypeScript union, and nothing imported that list
+ * for a runtime check — so any value the resolver did not recognise fell to the strategy switch's
+ * `default:` branch, which returns `{ strategy: 'placeholder' }`, and the entry's `value:` was
+ * emitted as literal placeholder text:
+ *
+ *   save:
+ *     type: 'testId'        # note the capital I
+ *     value: 'btn-save'
+ *                           → await page.getByPlaceholder('btn-save').click();
+ *
+ * Same family as #690 (a valid type with no dispatch) and #712 (a documented field with no
+ * consumer): the DECLARED surface was wider than the IMPLEMENTED one and nothing compared the two.
+ * Here the gap was the widest of the three, because an unknown type is not a fixed list of
+ * oversights — it is every possible misspelling.
+ *
+ * Checked HERE, at the selector-file load, rather than in the strategy switch. The switch CANNOT
+ * throw: `type: page` reaches its `default:` on every page assertion (its `value` is a URL, not a
+ * locator) and `StepMapper.checkPageStepFallback` resolves inside a try/catch that would read
+ * a throw as "not a page" and emit a false SG-W013. Validating at the load point also buys a
+ * better message — the file, the entry key and the nearest valid spelling — and reports once per
+ * entry rather than once per step that names it.
+ */
+
+import type { DiagnosticsCollector } from '../diagnostics';
+import { VALID_SELECTOR_TYPES } from '../../../utils/selector-types';
+import { nearestMatch } from './nearest-match';
+import { walkSelectorEntries } from './selector-entry-walk';
+
+export interface UnknownSelectorType {
+  /** Dotted path to the offending entry, e.g. `save` or `greeting.ios`. */
+  path: string;
+  /** The unrecognised `type:` value exactly as written. */
+  type: string;
+  /** A near-miss valid type, when one is close enough to be worth naming. */
+  suggestion?: string;
+}
+
+/** Every entry in `file` whose `type:` is not a member of `VALID_SELECTOR_TYPES`. */
+export function collectUnknownSelectorTypes(file: Record<string, unknown>): UnknownSelectorType[] {
+  const out: UnknownSelectorType[] = [];
+  walkSelectorEntries(file, {
+    entry(entry, path) {
+      const type = entry.type;
+      // Only a STRING type is judged here. A non-string `type:` (a YAML nesting slip) is a
+      // different defect with a different fix, and SG-W004's field walk is not the owner of it
+      // either — naming it as an unknown type would print `[object Object]` at the author.
+      if (typeof type !== 'string') return;
+      if ((VALID_SELECTOR_TYPES as readonly string[]).includes(type)) return;
+      out.push({ path, type, suggestion: nearestMatch(type, VALID_SELECTOR_TYPES) });
+    },
+  });
+  return out;
+}
+
+/** True when this entry kind is one the compiler knows how to resolve. */
+export function isKnownSelectorType(type: unknown): boolean {
+  return typeof type === 'string' && (VALID_SELECTOR_TYPES as readonly string[]).includes(type);
+}
+
+/**
+ * SG-E027 — report every entry whose `type:` nothing dispatches.
+ *
+ * Runs once per selector FILE (the resolver's load is cached), so an entry named by twenty steps
+ * is reported once. Silent when there is no diagnostics channel attached — `generate` must not
+ * depend on diagnostics being wired.
+ */
+export function reportUnknownSelectorTypes(
+  file: Record<string, unknown>,
+  opts: { feature?: string; diagnostics?: DiagnosticsCollector },
+): void {
+  const sink = opts.diagnostics;
+  if (!sink) return;
+  for (const { path, type, suggestion } of collectUnknownSelectorTypes(file)) {
+    const hint = suggestion
+      ? ` Did you mean "${suggestion}"?`
+      : ` Valid types: ${VALID_SELECTOR_TYPES.join(', ')}.`;
+    sink.add('SG-E027',
+      `selectors.yaml entry "${path}" declares type: "${type}", which is not a selector type — `
+      + `the entry resolves to getByPlaceholder("<its value>"), a locator that cannot match, so `
+      + `every step naming it now throws instead of failing later as a mystery timeout.${hint}`,
+      { feature: opts.feature });
+  }
+}