simplify some stuff

Author: kantord

tests/bdd/steps/global.steps.ts

@@ -14,13 +14,7 @@ When(
   },
 );
 
-// Backward-compatible convenience wrapper for "button" steps
-When(
-  "I click the {string} button",
-  async function (this: PlaywrightWorld, label: string) {
-    await this.page.getByRole("button", { name: label }).click();
-  },
-);
+// Intentionally avoid per-role variants (e.g., button) to keep steps DRY and consistent.
 
 Then(
   "I should see the text {string}",

tests/bdd/support/parameter-types.ts

@@ -1,6 +1,10 @@
 import { defineParameterType } from "@cucumber/cucumber";
 import type { AriaRole } from "@playwright/test";
-import { roleAliases, validAriaRoles } from "./roles.ts";
+import {
+  allowedRolePhrases,
+  preferredPhraseByRole,
+  validAriaRoles,
+} from "./roles.ts";
 
 defineParameterType({
   name: "role",
@@ -9,30 +13,29 @@ defineParameterType({
   transformer: (text: string): AriaRole => {
     const input = text.trim().toLowerCase();
 
-    // 1) Exact match
-    if (validAriaRoles.has(input)) {
-      return input as AriaRole;
-    }
-
-    // 2) Compact variant: remove spaces and hyphens
-    const compact = input.replace(/[\s-]+/g, "");
-    if (validAriaRoles.has(compact)) {
-      return compact as AriaRole;
+    // Accept only canonical phrases to reduce variants
+    const canonical = allowedRolePhrases[input];
+    if (canonical) {
+      return canonical;
     }
 
-    // 3) Aliases
-    const alias = roleAliases[input];
-    if (alias) {
-      return alias;
+    // If user provided an ARIA role directly, recommend the canonical phrase
+    if (validAriaRoles.has(input)) {
+      const role = input as AriaRole;
+      const preferred = preferredPhraseByRole[role];
+      if (preferred && preferred !== input) {
+        throw new Error(
+          `Use canonical role phrase "${preferred}" instead of "${input}".`,
+        );
+      }
+      // Role equals its canonical phrase (e.g., "button", "link", "checkbox")
+      return role;
     }
 
-    // 4) Helpful error
-    const sample = Array.from(validAriaRoles).slice(0, 15).join(", ");
+    // Helpful error with allowed phrases
+    const examples = Object.keys(allowedRolePhrases).slice(0, 10).join(", ");
     throw new Error(
-      `Unknown role "${text}".\n` +
-        `- Tried: "${input}" and "${compact}".\n` +
-        "- Add an alias in roleAliases if this is a valid custom phrase.\n" +
-        `- Example known roles: ${sample} ...`,
+      `Unknown role phrase "${text}". Use one of the canonical phrases (e.g., ${examples} ...).`,
     );
   },
 });

tests/bdd/support/roles.ts

@@ -1,15 +1,32 @@
 import type { AriaRole } from "@playwright/test";
 import { roles as ariaRolesMap } from "aria-query";
 
-// Set of all valid ARIA roles sourced from aria-query
+// Set of all valid ARIA roles sourced from aria-query (for diagnostics)
 export const validAriaRoles = new Set<string>([...ariaRolesMap.keys()]);
 
-// Map human-friendly phrases to real ARIA roles (keep this minimal and sensible)
-export const roleAliases: Record<string, AriaRole> = {
+// Canonical phrases allowed in features → mapped to ARIA role
+// Keep exactly one human-facing variant per role to minimize duplication
+export const allowedRolePhrases: Record<string, AriaRole> = {
+  // common interactive roles
+  button: "button",
+  link: "link",
+  checkbox: "checkbox",
   "menu item": "menuitem",
   "radio button": "radio",
-  "check box": "checkbox",
-  // common synonyms
-  dropdown: "combobox",
-  "list box": "listbox",
+  combobox: "combobox",
+  listbox: "listbox",
+  // useful extras (read-only)
+  heading: "heading",
+  textbox: "textbox",
 };
+
+// Inverse lookup for recommendations (ARIA role → preferred phrase)
+export const preferredPhraseByRole: Record<AriaRole, string> = Object.entries(
+  allowedRolePhrases,
+).reduce(
+  (acc, [phrase, role]) => {
+    acc[role] = phrase;
+    return acc;
+  },
+  {} as Record<AriaRole, string>,
+);