genat-mcp 2.3.2 → 2.3.4

package/README.md

@@ -212,7 +212,7 @@ When creating run-genat.mjs: Use webhook-genat-login, NOT webhook-genat. Prefer
 
 - **url** (string): Page URL to analyze for accessibility.
 - **parentProjectFolder** (string): Path to the project root (TypeScript, JavaScript, or Python Playwright).
-- **writeToProject** (boolean, optional): If `true`, write generated files under `tests/accessibility/` by default; for **pytest-bdd** Python projects, files go under `features/` / `step_defs/` (or `tests/features`, `steps`, etc.) when those directories exist.
+- **writeToProject** (boolean, optional): If `true`, write generated files under `tests/accessibility/` by default; for **pytest-bdd** Python projects, files go under `features/` / `step_defs/` (or `tests/features`, `steps`, etc.) when those directories exist. New projects get **`step_defs/test_accessibility_steps.py`** when `accessibility_steps.py` is not already present.
 - **maxAssertions** (number, optional): Override default assertion count for complex pages (e.g. `25`).
 - **scopeToRegions** (string[], optional): Limit tests to specific regions (e.g. `["header", "main", "table"]`).
 - **analyzeStates** (boolean, optional): If `true`, run axe in expanded dropdown/combobox states and include state-specific violations. Increases analysis time.
@@ -225,8 +225,24 @@ Login credentials: provide in the prompt (loginUsername, loginPassword) or in pr
 
 Framework detection: language (TypeScript vs JavaScript vs Python), BDD (Cucumber, pytest-bdd, Behave), and Page Object pattern (e.g. `pages/` directory or `*Page.ts`, `*Page.js`, `*_page.py` files). Returns JSON with `testCode`, `featureFile`, `stepDefCode`, `pageObjectCode` (and `_written` paths when writing).
 
+**Response fields for calling applications:** When `stepDefCode` is present, the MCP may set **`_stepDefIncomplete`** (boolean) and **`_stepDefIncompleteReason`** (string) using a lightweight heuristic (unclosed strings/delimiters, line continuation at EOF). Treat `true` as a signal to warn the user, retry generation, or block merge—do not assume the step file is runnable. Other optional fields from the workflow include **`usedLogin`** and **`loginReason`** when using login-capable workflows.
+
 Generated tests include keyboard accessibility checks (Tab order, focus) by default. For complex pages, the workflow uses page complexity (regions, tables, widgets) to scale assertion count.
 
+### Feature ↔ step parity (consumer CI)
+
+GenAT does not guarantee that every Gherkin line has an implemented step. For **pytest-bdd** projects, the calling application or CI can:
+
+1. Parse `*.feature` step lines (after `Given`/`When`/`Then`/`And`/`But`).
+2. Confirm `test_accessibility_steps.py` or `accessibility_steps.py` (your step module) defines matching `@given`/`@when`/`@then` patterns (or run `pytest --collect-only` / a dry run).
+
+Keep this as an optional pre-merge check alongside `_stepDefIncomplete`.
+
+### pytest-bdd discovery and axe-playwright-python
+
+- **Pytest** collects `test_*.py` by default. GenAT now prefers writing **`step_defs/test_accessibility_steps.py`** for new projects; if **`accessibility_steps.py`** already exists, that path is used. Ensure **`@scenario`** test functions are in a collected module (often the same file when named `test_*.py`) or import step defs from **`conftest.py`** / **`pytest_plugins`**.
+- **axe-playwright-python (sync):** `from axe_playwright_python.sync_playwright import Axe`; `axe = Axe()`; `results = axe.run(page)`; read **`results.response`** (axe-core JSON) and **`results.violations_count`**. Do not invent other APIs—see [axe-playwright-python docs](https://pamelafox.github.io/axe-playwright-python/).
+
 ## Sample prompts
 
 See [prompts.md](prompts.md) for a full list of prompts including specific parent folders, login, JIRA, and combined options.

package/detect-framework.js

@@ -77,15 +77,21 @@ function collectProjectLayoutHints(root, scriptType, bddFramework) {
   }
 
   if (existsSync(join(root, 'step_defs'))) {
-    parts.push('Put step definitions under step_defs/ (e.g. accessibility_steps.py)');
+    parts.push(
+      'Put step definitions under step_defs/; prefer test_accessibility_steps.py (test_*.py) so pytest discovers @scenario tests, or keep accessibility_steps.py and import that module from conftest.py'
+    );
   } else if (existsSync(join(root, 'steps'))) {
-    parts.push('Put step definitions under steps/');
+    parts.push('Put step definitions under steps/; prefer test_*.py naming for pytest collection or import via conftest.py');
   } else if (existsSync(join(root, 'tests', 'step_defs'))) {
-    parts.push('Put step definitions under tests/step_defs/');
+    parts.push('Put step definitions under tests/step_defs/; prefer test_accessibility_steps.py or conftest import');
   } else {
-    parts.push('Prefer step_defs/ for pytest-bdd step modules');
+    parts.push('Prefer step_defs/ for pytest-bdd; use test_accessibility_steps.py for pytest discovery of scenario tests');
   }
 
+  parts.push(
+    'Pytest collects test_*.py by default; ensure BDD scenario functions (@scenario) live in a collected module or are pulled in via conftest/pytest_plugins'
+  );
+
   const conftestPaths = walkWithPaths(root, (f) => f === 'conftest.py');
   const fixtureNames = new Set();
   for (const p of conftestPaths.slice(0, 3)) {

package/detect-incomplete-step-def.js

@@ -0,0 +1,140 @@
+/**
+ * Lightweight heuristic: detect likely truncated or syntactically incomplete pytest-bdd step Python.
+ * For calling apps to surface _stepDefIncomplete and retry or warn.
+ */
+
+/**
+ * @param {string} code
+ * @returns {{ incomplete: boolean, reason: string | null }}
+ */
+export function detectStepDefIncomplete(code) {
+  if (code == null || typeof code !== 'string') {
+    return { incomplete: false, reason: null };
+  }
+  const t = code.replace(/\r\n/g, '\n').trimEnd();
+  if (t.length === 0) {
+    return { incomplete: true, reason: 'empty' };
+  }
+
+  const triples = (t.match(/"""/g) || []).length;
+  if (triples % 2 !== 0) {
+    return { incomplete: true, reason: 'unclosed_triple_double_quoted_string' };
+  }
+  const tripleSingle = (t.match(/'''/g) || []).length;
+  if (tripleSingle % 2 !== 0) {
+    return { incomplete: true, reason: 'unclosed_triple_single_quoted_string' };
+  }
+
+  const lines = t.split('\n');
+  const lastLine = lines[lines.length - 1];
+  if (/\\\s*$/.test(lastLine)) {
+    return { incomplete: true, reason: 'line_continuation_at_eof' };
+  }
+
+  const depth = bracketDepthAtEnd(t);
+  if (depth !== 0) {
+    return { incomplete: true, reason: 'unclosed_delimiters' };
+  }
+
+  return { incomplete: false, reason: null };
+}
+
+/**
+ * Rough balance of (), [], {} at end of file, skipping strings and comments.
+ * @param {string} s
+ * @returns {number} 0 if balanced, non-zero if likely incomplete
+ */
+function bracketDepthAtEnd(s) {
+  let i = 0;
+  const stack = [];
+  let state = 'code';
+
+  while (i < s.length) {
+    const c = s[i];
+
+    if (state === 'code') {
+      if (c === '#') {
+        while (i < s.length && s[i] !== '\n') i++;
+        continue;
+      }
+      if (s.slice(i, i + 3) === '"""') {
+        state = 'triple_double';
+        i += 3;
+        continue;
+      }
+      if (s.slice(i, i + 3) === "'''") {
+        state = 'triple_single';
+        i += 3;
+        continue;
+      }
+      if (c === '"' || c === "'") {
+        state = c === '"' ? 'string_double' : 'string_single';
+        i++;
+        continue;
+      }
+      if (c === '(') stack.push('(');
+      else if (c === '[') stack.push('[');
+      else if (c === '{') stack.push('{');
+      else if (c === ')' || c === ']' || c === '}') {
+        const want = c === ')' ? '(' : c === ']' ? '[' : '{';
+        if (stack.length === 0 || stack[stack.length - 1] !== want) {
+          return -1;
+        }
+        stack.pop();
+      }
+      i++;
+      continue;
+    }
+
+    if (state === 'string_single') {
+      if (c === '\\') {
+        i += 2;
+        continue;
+      }
+      if (c === "'") {
+        state = 'code';
+      }
+      i++;
+      continue;
+    }
+
+    if (state === 'string_double') {
+      if (c === '\\') {
+        i += 2;
+        continue;
+      }
+      if (c === '"') {
+        state = 'code';
+      }
+      i++;
+      continue;
+    }
+
+    if (state === 'triple_double') {
+      if (s.slice(i, i + 3) === '"""') {
+        state = 'code';
+        i += 3;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    if (state === 'triple_single') {
+      if (s.slice(i, i + 3) === "'''") {
+        state = 'code';
+        i += 3;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    i++;
+  }
+
+  if (state !== 'code') {
+    return 1;
+  }
+  return stack.length;
+}

package/index.js

@@ -11,6 +11,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { detectFramework } from './detect-framework.js';
 import { detectLogin } from './detect-login.js';
+import { detectStepDefIncomplete } from './detect-incomplete-step-def.js';
 import { finalizePytestBddStepDef } from './finalize-pytest-bdd-steps.js';
 import { resolvePytestBddPaths } from './pytest-bdd-paths.js';
 import { writeGeneratedFiles } from './write-files.js';
@@ -58,7 +59,7 @@ function insecureHttpsFetch(url, { method = 'GET', headers = {}, body, signal })
 const server = new McpServer(
   {
     name: 'GenAT',
-    version: '2.3.2',
+    version: '2.3.4',
   },
   {
     capabilities: {
@@ -283,6 +284,12 @@ server.registerTool(
       if (data.testCode) data.testCode = finalizePytestBddStepDef(resolvedPath, data.testCode, pathOverrides);
     }
 
+    if (data.stepDefCode && typeof data.stepDefCode === 'string') {
+      const inc = detectStepDefIncomplete(data.stepDefCode);
+      data._stepDefIncomplete = inc.incomplete;
+      if (inc.reason) data._stepDefIncompleteReason = inc.reason;
+    }
+
     if (writeToProject && resolvedPath && data) {
       if (data.bddFramework == null) data.bddFramework = framework.bddFramework;
       try {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "genat-mcp",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "mcpName": "io.github.asokans@oclc.org/genat",
   "description": "MCP server GenAT: generate accessibility tests via n8n workflow (url + project folder)",
   "type": "module",
   "main": "index.js",
   "bin": { "genat-mcp": "index.js" },
   "engines": { "node": ">=20" },
-  "files": ["index.js", "detect-framework.js", "detect-login.js", "write-files.js", "strip-gherkin-from-python-steps.js", "finalize-pytest-bdd-steps.js", "fix-pytest-bdd-scenario-path.js", "pytest-bdd-paths.js", "oclc-context.js", "oclc-accessibility-confluence-context.md", "run-genat.mjs", "rules/genat-mcp.mdc"],
+  "files": ["index.js", "detect-framework.js", "detect-login.js", "detect-incomplete-step-def.js", "write-files.js", "strip-gherkin-from-python-steps.js", "finalize-pytest-bdd-steps.js", "fix-pytest-bdd-scenario-path.js", "pytest-bdd-paths.js", "oclc-context.js", "oclc-accessibility-confluence-context.md", "run-genat.mjs", "rules/genat-mcp.mdc"],
   "keywords": ["mcp", "accessibility", "playwright", "n8n", "model-context-protocol", "a11y", "testing"],
   "repository": {
     "type": "git",

package/pytest-bdd-paths.js

@@ -1,11 +1,29 @@
 /**
  * Resolve pytest-bdd feature / step / spec paths from project layout (same rules as write-files).
+ * Step file: prefer legacy accessibility_steps.py if present; otherwise test_accessibility_steps.py
+ * so pytest discovers scenario tests (test_*.py).
  */
 import { existsSync } from 'fs';
 import { join } from 'path';
 
 const DEFAULT_DIR = 'tests/accessibility';
 
+const LEGACY_STEP = 'accessibility_steps.py';
+const TEST_STEP = 'test_accessibility_steps.py';
+
+/**
+ * @param {string} root
+ * @param {string[]} dirSegments - e.g. ['step_defs']
+ * @returns {string} relative path to step file
+ */
+function pickStepFileUnderDir(root, dirSegments) {
+  const legacy = join(...dirSegments, LEGACY_STEP);
+  const testNamed = join(...dirSegments, TEST_STEP);
+  if (existsSync(join(root, legacy))) return legacy;
+  if (existsSync(join(root, testNamed))) return testNamed;
+  return testNamed;
+}
+
 /**
  * @param {string} root
  * @returns {{ featureRel: string, stepRel: string, specRel: string }}
@@ -17,11 +35,11 @@ export function resolvePytestBddPaths(root) {
   else featureRel = join('features', 'accessibility.feature');
 
   let stepRel;
-  if (existsSync(join(root, 'step_defs'))) stepRel = join('step_defs', 'accessibility_steps.py');
-  else if (existsSync(join(root, 'steps'))) stepRel = join('steps', 'accessibility_steps.py');
-  else if (existsSync(join(root, 'tests', 'step_defs'))) stepRel = join('tests', 'step_defs', 'accessibility_steps.py');
-  else if (existsSync(join(root, 'tests', 'steps'))) stepRel = join('tests', 'steps', 'accessibility_steps.py');
-  else stepRel = join('step_defs', 'accessibility_steps.py');
+  if (existsSync(join(root, 'step_defs'))) stepRel = pickStepFileUnderDir(root, ['step_defs']);
+  else if (existsSync(join(root, 'steps'))) stepRel = pickStepFileUnderDir(root, ['steps']);
+  else if (existsSync(join(root, 'tests', 'step_defs'))) stepRel = pickStepFileUnderDir(root, ['tests', 'step_defs']);
+  else if (existsSync(join(root, 'tests', 'steps'))) stepRel = pickStepFileUnderDir(root, ['tests', 'steps']);
+  else stepRel = join('step_defs', TEST_STEP);
 
   const specRel = join(DEFAULT_DIR, 'accessibility_test.py');
   return { featureRel, stepRel, specRel };