@vijaypjavvadi/bdd2pw 2.2.7 → 3.1.0

package/dist/transformers/visibilityRules.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * v3.1.0 — catch-all visibility rules.
+ *
+ * Why this exists: TestForge AI's handoff report (Issue 1, P0) showed
+ * that steps like "the user's name or profile indicator is visible in
+ * the UI" were falling through every existing visibility rule (which
+ * require specific noun-phrase shapes like "a Logout button" or "an
+ * error message") and ending up in the URL-slug rules, where the
+ * prose was tokenised into a regex that never matches a real URL.
+ * Result: silent always-failing tests that look like product bugs.
+ *
+ * These rules slot in BEFORE all URL-slug rules so any
+ * "is visible / displayed / shown / appears" phrasing is intercepted
+ * deterministically. The captured noun phrase is matched against the
+ * POM's fields (fuzzy / case-insensitive contains); if a field matches,
+ * we emit `expect(<pomVar>.<field>).toBeVisible()`. If nothing matches,
+ * we emit a clean `// TODO bdd2pw: ambiguous visibility step` warning
+ * — never a URL regex.
+ *
+ * Coverage:
+ *   - "<noun> is visible (in <where>)?"
+ *   - "<noun> is displayed (in <where>)?"
+ *   - "<noun> is shown (in <where>)?"
+ *   - "<noun> appears (on screen|in <where>)?"
+ *   - "<noun> should be visible / displayed / shown"
+ *   - "<noun> is enabled / clickable" → toBeEnabled()
+ *
+ * The noun can be arbitrary prose (apostrophes, "or", multiple words);
+ * we don't try to slugify it into a locator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VISIBILITY_RULES = void 0;
+/** Words that, if they appear inside a captured noun, suggest the
+ *  step refers to a navigation / URL claim rather than a UI element.
+ *  When found, we decline the visibility rule so URL rules can have
+ *  another chance. */
+const URL_HINT_WORDS = new Set([
+    "url",
+    "path",
+    "endpoint",
+    "page",
+    "route",
+]);
+/**
+ * Role hints THAT N6 SPECIFICALLY HANDLES. When the captured noun
+ * phrase ends with one of these, the existing N6 rule synthesises a
+ * cross-role locator ("a Logout button is visible" →
+ * `getByRole('button', { name: /Logout/i })` with link fallback). We
+ * decline our visibility rule so N6 wins.
+ *
+ * Kept narrow on purpose: nouns that end in `message`/`banner`/`alert`
+ * but DON'T fit N5c's "containing" shape (e.g. "the welcome banner is
+ * shown") should still get our TODO treatment, not be left orphaned.
+ */
+const N6_ROLE_TAIL = /\b(?:button|link|icon|element|tab)$/i;
+/**
+ * N5c handles "<an? <kind> message|alert|banner> containing '<value>'
+ * is displayed/shown" with `toContainText`. Whenever we see a noun that
+ * contains the literal word "containing", that's a strong signal it's
+ * N5c-shaped and we should decline so N5c can produce the right
+ * assertion.
+ */
+const N5C_LIKE = /\bcontaining\b/i;
+/**
+ * N7 handles negation-prefixed visibility steps ("No success message is
+ * shown", "No 'Log out' button appears", "No errors are displayed").
+ * The N7 pattern requires the step to START with "No ", so we decline
+ * our visibility rule whenever the captured noun begins with that
+ * negation prefix.
+ *
+ * The case-insensitive match also catches "no errors are displayed"
+ * just in case a future test exercises lowercase negation.
+ */
+const N7_NEGATION_PREFIX = /^no\s+/i;
+/**
+ * Decline this rule when the noun:
+ *   1. is the empty string,
+ *   2. contains URL hint words ("url", "page", "route", …),
+ *   3. ends with one of N6's role hints (button|link|icon|element|tab),
+ *   4. looks like an N5c "containing" phrase,
+ *   5. starts with the N7 negation prefix "No ".
+ */
+function shouldDeclineVisibilityRule(noun) {
+    const normalised = normaliseNoun(noun);
+    if (!normalised)
+        return true;
+    const tokens = normalised.split(/\s+/);
+    if (tokens.some((t) => URL_HINT_WORDS.has(t)))
+        return true;
+    if (N6_ROLE_TAIL.test(normalised))
+        return true;
+    if (N5C_LIKE.test(normalised))
+        return true;
+    if (N7_NEGATION_PREFIX.test(normalised))
+        return true;
+    return false;
+}
+/** Lowercase the noun phrase and squash whitespace for matching. */
+function normaliseNoun(s) {
+    return s.toLowerCase().replace(/\s+/g, " ").trim();
+}
+/**
+ * Try to find a POM field whose name contains the noun phrase (or vice
+ * versa). Returns `<pageVar>.<fieldName>` when a match is found,
+ * otherwise undefined.
+ *
+ * Conservative — only matches when one is a substring of the other,
+ * case-insensitive. We never invent locators; if nothing matches the
+ * caller emits a TODO.
+ */
+function resolveLocatorFromPom(noun, pom, pageVar) {
+    const target = normaliseNoun(noun).replace(/[^a-z0-9]/g, "");
+    if (!target)
+        return undefined;
+    for (const field of pom.fields) {
+        const fieldKey = field.fieldName.toLowerCase();
+        if (fieldKey.includes(target) || target.includes(fieldKey)) {
+            return `${pageVar}.${field.fieldName}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Shared build logic for visibility rules. Drives the matcher decision
+ * once the regex has captured the noun phrase and chosen the matcher.
+ */
+function buildVisibilityBinding(step, pom, pageVar, noun, matcher) {
+    // Decline the rule when the captured noun is shaped for an existing
+    // richer rule — URL rules (URL/path/page hints), or N5/N6/N7
+    // cross-role rules (role-hint tail). The visibility rules in this
+    // module are only meant to catch PROSE noun phrases that no other
+    // rule handles. See `shouldDeclineVisibilityRule` for the full list.
+    if (shouldDeclineVisibilityRule(noun))
+        return null;
+    const locator = resolveLocatorFromPom(noun, pom, pageVar);
+    if (!locator) {
+        // No POM field match — emit a clean TODO. CRUCIALLY, we do NOT
+        // fall through to a URL regex; this is the whole point of Issue 1.
+        return {
+            step,
+            warning: `ambiguous visibility step: no POM field matched "${noun.trim()}". ` +
+                `Add a locator field to the POM, or hand-edit the spec to point at the ` +
+                `right element. (bdd2pw will not synthesise a URL regex from a prose ` +
+                `noun — that produced always-failing tests in v3.0.0 and earlier.)`,
+        };
+    }
+    return {
+        step,
+        assertion: { locator, matcher },
+    };
+}
+exports.VISIBILITY_RULES = [
+    // V:01 — "<noun> is visible (in/on <where>)?"
+    // Catches the TestForge reproduction:
+    //   "the user's name or profile indicator is visible in the UI"
+    //
+    // The noun phrase can contain apostrophes, "or", multiple words. We
+    // capture greedily up to ` is visible` and then optionally consume
+    // a trailing " in/on <something>" clause.
+    {
+        pattern: /^(.+?)\s+is\s+visible(?:\s+(?:in|on)\s+the\s+(?:ui|page|screen))?$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "toBeVisible"),
+    },
+    // V:02 — "<noun> is displayed (in/on <where>)?"
+    {
+        pattern: /^(.+?)\s+is\s+displayed(?:\s+(?:in|on)\s+the\s+(?:ui|page|screen))?$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "toBeVisible"),
+    },
+    // V:03 — "<noun> is shown (in/on <where>)?"
+    {
+        pattern: /^(.+?)\s+is\s+shown(?:\s+(?:in|on)\s+the\s+(?:ui|page|screen))?$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "toBeVisible"),
+    },
+    // V:04 — "<noun> appears (on screen|in/on the ui/page)?"
+    {
+        pattern: /^(.+?)\s+appears(?:\s+(?:on\s+screen|in\s+the\s+(?:ui|page)|on\s+the\s+page))?$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "toBeVisible"),
+    },
+    // V:05 — "<noun> should be visible / displayed / shown"
+    {
+        pattern: /^(.+?)\s+should\s+be\s+(?:visible|displayed|shown)$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "toBeVisible"),
+    },
+    // V:06 — negative: "<noun> is (not visible|hidden|not displayed|not shown)"
+    {
+        pattern: /^(.+?)\s+is\s+(?:not\s+visible|hidden|not\s+displayed|not\s+shown)$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "not.toBeVisible"),
+    },
+    // V:07 — "<noun> is enabled / clickable"
+    {
+        pattern: /^(.+?)\s+is\s+(?:enabled|clickable)$/i,
+        build: (m, step, pom, pageVar) => buildVisibilityBinding(step, pom, pageVar, m[1], "toBeEnabled"),
+    },
+];
+// (end of visibilityRules.ts — v3.1.0)
+//# sourceMappingURL=visibilityRules.js.map

package/dist/transformers/visibilityRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibilityRules.js","sourceRoot":"","sources":["../../src/transformers/visibilityRules.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAcH;;;sBAGsB;AACtB,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,KAAK;IACL,MAAM;IACN,UAAU;IACV,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,YAAY,GAAG,sCAAsC,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AAEnC;;;;;;;;;GASG;AACH,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAErC;;;;;;;GAOG;AACH,SAAS,2BAA2B,CAAC,IAAY;IAC/C,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,SAAS,aAAa,CAAC,CAAS;IAC9B,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAC5B,IAAY,EACZ,GAAiB,EACjB,OAAe;IAEf,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QAC/C,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,OAAO,GAAG,OAAO,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,sBAAsB,CAC7B,IAAY,EACZ,GAAiB,EACjB,OAAe,EACf,IAAY,EACZ,OAA0D;IAE1D,oEAAoE;IACpE,6DAA6D;IAC7D,kEAAkE;IAClE,kEAAkE;IAClE,qEAAqE;IACrE,IAAI,2BAA2B,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,+DAA+D;QAC/D,mEAAmE;QACnE,OAAO;YACL,IAAI;YACJ,OAAO,EACL,oDAAoD,IAAI,CAAC,IAAI,EAAE,KAAK;gBACpE,wEAAwE;gBACxE,sEAAsE;gBACtE,mEAAmE;SACtE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;KAChC,CAAC;AACJ,CAAC;AAEY,QAAA,gBAAgB,GAAW;IACtC,8CAA8C;IAC9C,sCAAsC;IACtC,gEAAgE;IAChE,EAAE;IACF,oEAAoE;IACpE,mEAAmE;IACnE,0CAA0C;IAC1C;QACE,OAAO,EACL,qEAAqE;QACvE,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC;KAClE;IAED,gDAAgD;IAChD;QACE,OAAO,EACL,uEAAuE;QACzE,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC;KAClE;IAED,4CAA4C;IAC5C;QACE,OAAO,EACL,mEAAmE;QACrE,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC;KAClE;IAED,yDAAyD;IACzD;QACE,OAAO,EACL,kFAAkF;QACpF,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC;KAClE;IAED,wDAAwD;IACxD;QACE,OAAO,EAAE,sDAAsD;QAC/D,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC;KAClE;IAED,4EAA4E;IAC5E;QACE,OAAO,EACL,sEAAsE;QACxE,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,iBAAiB,CAAC;KACtE;IAED,yCAAyC;IACzC;QACE,OAAO,EAAE,uCAAuC;QAChD,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAC/B,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC;KAClE;CACF,CAAC;AACF,uCAAuC"}

package/dist/types.d.ts

@@ -88,6 +88,19 @@ export interface StepBinding {
     customBody?: string;
     /** Populated when no clean mapping was found. */
     warning?: string;
+    /**
+     * v3.0.0 — flag set by API-pattern rules (page.request.*). When ANY
+     * binding in a scenario is API-flagged, the renderer:
+     *   1. Adds `type APIResponse` to the @playwright/test import.
+     *   2. Injects `let apiResponse: APIResponse | null = null;` and
+     *      `let baseUrl: string = process.env.CLOUD_JOB_APP_URL ?? "";`
+     *      inside the describe block.
+     *   3. Prepends `apiResponse = null;` to the test body (per-test reset).
+     *
+     * UI-only scenarios in the same feature don't get any of that — the
+     * flag is per-binding, the emitter aggregates per-scenario.
+     */
+    apiContext?: true;
 }
 export interface ReviewItem {
     severity: "info" | "warn" | "error";
@@ -188,6 +201,24 @@ export interface ScaffoldOptions {
      * Default: false (purely additive minor bump).
      */
     selfHealing?: boolean;
+    /**
+     * v3.1.0 — opt-in instrumentation. See TestForge handoff Issue 4 and
+     * Issue 5.
+     *
+     * - `stepHooks`: every emitted `test.step` body calls
+     *   `(globalThis as any).__bdd2pwHooks?.beforeStep?.(testInfo, title)`
+     *   and `?.afterStep?.(...)`. Consumers wire the hook to do per-step
+     *   screenshots, custom reporters, artefact uploads, etc.
+     * - `stepMarkers`: each `test.step` is bracketed by stable
+     *   `// bdd2pw:step-open id="NNNN" title="..."` /
+     *   `// bdd2pw:step-close id="NNNN"` comments. Lets post-processors
+     *   slice the source without brace counting.
+     *
+     * Both default to false. Existing UI / API emission paths are
+     * byte-stable when these are off.
+     */
+    stepHooks?: boolean;
+    stepMarkers?: boolean;
 }
 export interface ScaffoldResult {
     filesWritten: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vijaypjavvadi/bdd2pw",
-  "version": "2.2.7",
+  "version": "3.1.0",
   "description": "Scaffold runnable Playwright TypeScript tests from Gherkin .feature files. Detects existing Page Objects, scans live pages via Microsoft Playwright MCP, emits POMs + specs, ready for execution. CLI + HTTP service. Optional governed LLM fallback (Anthropic / OpenAI / Gemini).",
   "bin": {
     "bdd2pw": "dist/cli.js"
@@ -59,7 +59,7 @@
   "dependencies": {
     "@cucumber/gherkin": "^28.0.0",
     "@cucumber/messages": "^24.1.0",
-    "@vijaypjavvadi/pw-emit": "^1.0.0",
+    "@vijaypjavvadi/pw-emit": "^1.2.0",
     "archiver": "^7.0.1",
     "chalk": "^4.1.2",
     "commander": "^12.1.0",