genat-mcp 2.2.6 → 2.2.8

package/README.md

@@ -4,6 +4,8 @@ MCP server that exposes a **GenAT** tool: generate accessibility tests for a URL
 
 Full setup (n8n workflow, services, usage) is in the [project README](../README.md).
 
+**For teams:** See [GENAT_OVERVIEW.md](GENAT_OVERVIEW.md) for a concise, presentation-ready overview. Suitable as a source for NotebookLM or other AI tools to create slide decks.
+
 ## Install
 
 **If the package is published to npm** (otherwise you get 404):
@@ -39,6 +41,7 @@ npm install /path/to/n8n_playwright_tests/mcp-genat
 | **N8N_SCOPE_TO_REGIONS** | No       | (none)  | Comma-separated regions to focus tests on (e.g. `header,main,table`). Used as default when the tool is invoked without `scopeToRegions`; also used by run-genat.mjs. |
 | **N8N_ANALYZE_STATES** | No       | (off)   | Set to `1`, `true`, or `yes` to analyze dropdown/combobox expanded states and include state-specific violations in generated tests. Used as default when the tool is invoked without `analyzeStates`; also used by run-genat.mjs. Increases analysis time. |
 | **GENAT_PROJECT_ROOT** | No       | (cwd)   | Base path for resolving `parentProjectFolder`. When set, `parentProjectFolder` is resolved relative to this path. Use when your project is outside the MCP's working directory. Example: if your pytest project is at `/Users/me/projects/ill_tests`, set `GENAT_PROJECT_ROOT=/Users/me/projects` and use `parentProjectFolder ill_tests` in the prompt. |
+| **GENAT_FETCH_TIMEOUT_MS** | No       | 600000 (10 min) | Max time in milliseconds to wait for the n8n webhook response. Increase if GenAT times out before the workflow completes (e.g. complex pages with JIRA + AI Agent). Set in MCP env, e.g. `GENAT_FETCH_TIMEOUT_MS=900000` for 15 minutes. |
 
 ## Framework detection and auto-discovery
 
@@ -48,6 +51,8 @@ GenAT detects **language** (TypeScript, JavaScript, Python), **BDD framework** (
 
 **Path guidance:** Pass the project root (e.g. `.` or `/path/to/project`). GenAT will auto-discover the best folder when tests are in `tests/` or `e2e/`. For monorepos, pass the specific test project folder (e.g. `packages/e2e-tests`) when the root has mixed content.
 
+**pytest-bdd (Python):** When `scriptType` is Python and `bddFramework` is `pytest-bdd`, detection also scans `conftest.py` for common Playwright fixtures (`browser_page`, `page`, `base_url`, etc.) and prefers `features/` or `tests/features/` and `step_defs/` or `steps/` for layout hints. Those hints are sent as `projectLayoutHints` in the webhook body (and merged into `projectSummary`) so the n8n workflow can steer the model. Generated code uses **axe-playwright-python** (`from axe_playwright_python.sync_playwright import Axe`); ensure `pip install axe-playwright-python pytest-bdd pytest-playwright` (or your lockfile equivalent) in the project.
+
 ## Cursor MCP config
 
 **Using npx (local install):**
@@ -108,6 +113,24 @@ GenAT detects **language** (TypeScript, JavaScript, Python), **BDD framework** (
   }
 }
 ```
+
+**With GENAT_FETCH_TIMEOUT_MS** (increase timeout when workflow takes longer):
+
+```json
+{
+  "mcpServers": {
+    "GenAT": {
+      "command": "npx",
+      "args": ["genat-mcp"],
+      "env": {
+        "GENAT_FETCH_TIMEOUT_MS": "900000",
+        "N8N_WEBHOOK_URL": "https://n8n.example.com/webhook-test/webhook-genat-login"
+      }
+    }
+  }
+}
+```
+(900000 = 15 minutes. Default is 600000 = 10 minutes.)
 Then use `parentProjectFolder ill_tests` in the prompt to target `/Users/me/projects/ill_tests`.
 
 **With optional params for complex pages** (`N8N_MAX_ASSERTIONS`, `N8N_SCOPE_TO_REGIONS`, `N8N_ANALYZE_STATES`):
@@ -137,6 +160,7 @@ If the global binary is not on PATH, use the full path, e.g. `node $(npm root -g
 
 - **Node.js** 20+
 - **n8n** with a GenAT workflow imported and activated. Use [genat-accessibility-tests-with-login-jira.json](../workflows/genat-accessibility-tests-with-login-jira.json) (path `webhook-test/webhook-genat-login-jira`) for JIRA support, or [genat-accessibility-tests-with-login.json](../workflows/genat-accessibility-tests-with-login.json) (path `webhook-test/webhook-genat-login`). Set **N8N_WEBHOOK_URL** to the workflow's webhook URL.
+- **Optional v2 pipeline (Python / pytest-bdd quality):** Import [GenAT Accessibility Tests (with Login + JIRA) v2.json](../workflows/GenAT%20Accessibility%20Tests%20(with%20Login%20+%20JIRA)%20v2.json) and set **N8N_WEBHOOK_URL** to `…/webhook-test/webhook-genat-login-jira-v2`. v2 adds stricter pytest-bdd + Python rules (no nested markdown in code, layout hints, fixture-aware steps) and can run alongside the original workflow. The original v1 workflow is unchanged.
 - **DOM Analyzer** and **Accessibility Analyzer** services running (see main README: `npm run services` from repo root)
 
 ## Standalone script: run-genat.mjs
@@ -187,7 +211,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/` in the project folder.
+- **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.
 - **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.

package/detect-framework.js

@@ -57,9 +57,61 @@ function findBestProjectRoot(root) {
   return best;
 }
 
+/**
+ * Layout + conftest hints for pytest-bdd Python projects (empty string otherwise).
+ * @param {string} root
+ * @param {string} scriptType
+ * @param {string} bddFramework
+ * @returns {string}
+ */
+function collectProjectLayoutHints(root, scriptType, bddFramework) {
+  if (scriptType !== 'python' || bddFramework !== 'pytest-bdd') return '';
+
+  const parts = [];
+  if (existsSync(join(root, 'features'))) {
+    parts.push('Put new .feature files under features/');
+  } else if (existsSync(join(root, 'tests', 'features'))) {
+    parts.push('Put new .feature files under tests/features/');
+  } else {
+    parts.push('Prefer features/ at project root for Gherkin (.feature) files');
+  }
+
+  if (existsSync(join(root, 'step_defs'))) {
+    parts.push('Put step definitions under step_defs/ (e.g. accessibility_steps.py)');
+  } else if (existsSync(join(root, 'steps'))) {
+    parts.push('Put step definitions under steps/');
+  } else if (existsSync(join(root, 'tests', 'step_defs'))) {
+    parts.push('Put step definitions under tests/step_defs/');
+  } else {
+    parts.push('Prefer step_defs/ for pytest-bdd step modules');
+  }
+
+  const conftestPaths = walkWithPaths(root, (f) => f === 'conftest.py');
+  const fixtureNames = new Set();
+  for (const p of conftestPaths.slice(0, 3)) {
+    try {
+      const content = readFileSync(p, 'utf8');
+      const re = /def\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g;
+      let m;
+      while ((m = re.exec(content)) !== null) {
+        const name = m[1];
+        if (['page', 'browser_page', 'base_url', 'context', 'browser', 'playwright', 'request'].includes(name) || /_page$/.test(name)) {
+          fixtureNames.add(name);
+        }
+      }
+    } catch (_) {}
+  }
+  if (fixtureNames.size) {
+    parts.push(`Use these pytest fixtures from conftest (parameter names): ${[...fixtureNames].join(', ')}`);
+  }
+
+  parts.push('Dependencies: pip install axe-playwright-python pytest-bdd pytest-playwright');
+  return parts.join('; ');
+}
+
 /**
  * @param {string} parentProjectFolder - absolute or relative path to project root
- * @returns {{ scriptType: 'typescript'|'javascript'|'python', bddFramework: string, pageObject: boolean, projectSummary: string }}
+ * @returns {{ scriptType: 'typescript'|'javascript'|'python', bddFramework: string, pageObject: boolean, projectSummary: string, projectLayoutHints?: string }}
  */
 export function detectFramework(parentProjectFolder) {
   let root = resolve(parentProjectFolder);
@@ -69,6 +121,7 @@ export function detectFramework(parentProjectFolder) {
       bddFramework: 'none',
       pageObject: false,
       projectSummary: `Folder not found or empty; using defaults. (resolved: ${root})`,
+      projectLayoutHints: '',
     };
   }
 
@@ -284,16 +337,18 @@ export function detectFramework(parentProjectFolder) {
     }
   } catch (_) {}
 
-  const projectSummary = [
-    ...(summaryParts.length ? summaryParts : ['No framework hints detected']),
-    `(scanned: ${root})`,
-  ].join('; ');
+  const projectLayoutHints = collectProjectLayoutHints(root, scriptType, bddFramework);
+  const summaryWithHints = [...(summaryParts.length ? summaryParts : ['No framework hints detected'])];
+  if (projectLayoutHints) summaryWithHints.push(projectLayoutHints);
+
+  const projectSummary = [...summaryWithHints, `(scanned: ${root})`].join('; ');
 
   return {
     scriptType,
     bddFramework: ALLOWED_BDD.includes(bddFramework) ? bddFramework : 'none',
     pageObject,
     projectSummary,
+    ...(projectLayoutHints ? { projectLayoutHints } : {}),
   };
 }
 

package/index.js

@@ -16,12 +16,14 @@ import { writeGeneratedFiles } from './write-files.js';
 const N8N_WEBHOOK_URL = process.env.N8N_WEBHOOK_URL || 'http://localhost:5678/webhook-test/webhook-genat-login';
 const SERVICE_BASE_URL = process.env.SERVICE_BASE_URL || null;
 const N8N_INSECURE_TLS = /^1|true|yes$/i.test(process.env.N8N_INSECURE_TLS || '');
+const GENAT_FETCH_TIMEOUT_MS = Math.max(60000, parseInt(process.env.GENAT_FETCH_TIMEOUT_MS || '600000', 10) || 600000);
 
 /**
  * HTTPS fetch with rejectUnauthorized: false for self-signed/internal CA certs.
  * Returns a Response-like object { ok, status, text(), json() }.
+ * Supports signal for timeout.
  */
-function insecureHttpsFetch(url, { method = 'GET', headers = {}, body }) {
+function insecureHttpsFetch(url, { method = 'GET', headers = {}, body, signal }) {
   return new Promise((resolve, reject) => {
     const req = https.request(
       url,
@@ -29,6 +31,7 @@ function insecureHttpsFetch(url, { method = 'GET', headers = {}, body }) {
         method,
         headers: { 'Content-Type': 'application/json', ...headers },
         agent: new https.Agent({ rejectUnauthorized: false }),
+        signal,
       },
       (res) => {
         let data = '';
@@ -52,7 +55,7 @@ function insecureHttpsFetch(url, { method = 'GET', headers = {}, body }) {
 const server = new McpServer(
   {
     name: 'GenAT',
-    version: '2.2.6',
+    version: '2.2.8',
   },
   {
     capabilities: {
@@ -155,6 +158,7 @@ server.registerTool(
       bddFramework: framework.bddFramework,
       pageObject: framework.pageObject,
       projectSummary: framework.projectSummary,
+      ...(framework.projectLayoutHints && { projectLayoutHints: framework.projectLayoutHints }),
       ...(SERVICE_BASE_URL && { serviceBaseUrl: SERVICE_BASE_URL }),
       ...(maxAssertionsResolved != null && !isNaN(maxAssertionsResolved) && { maxAssertions: maxAssertionsResolved }),
       ...(scopeToRegionsResolved?.length && { scopeToRegions: scopeToRegionsResolved }),
@@ -171,10 +175,13 @@ server.registerTool(
     };
 
     const useInsecureTls = N8N_INSECURE_TLS && N8N_WEBHOOK_URL.startsWith('https://');
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), GENAT_FETCH_TIMEOUT_MS);
     const fetchOpts = {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
+      signal: controller.signal,
     };
     let response;
     try {
@@ -190,13 +197,15 @@ server.registerTool(
             text: JSON.stringify({
               error: 'Failed to call n8n webhook',
               message: err instanceof Error ? err.message : String(err),
-              hint: 'Set N8N_WEBHOOK_URL to your n8n webhook URL. For self-signed/internal certs, set N8N_INSECURE_TLS=1',
+              hint: err?.name === 'AbortError' ? `Request timed out after ${GENAT_FETCH_TIMEOUT_MS / 1000}s. Set GENAT_FETCH_TIMEOUT_MS in MCP env to increase (default 600000).` : 'Set N8N_WEBHOOK_URL to your n8n webhook URL. For self-signed/internal certs, set N8N_INSECURE_TLS=1',
               workaround: `Run: N8N_WEBHOOK_URL='${loginUrl}' N8N_INSECURE_TLS=1 node node_modules/genat-mcp/run-genat.mjs "<url>" .  Use node_modules/genat-mcp/run-genat.mjs only (delete any run-genat.mjs in project root that uses webhook-genat).`,
             }),
           },
         ],
         isError: true,
       };
+    } finally {
+      clearTimeout(timeoutId);
     }
 
     if (!response.ok) {
@@ -231,8 +240,9 @@ server.registerTool(
     }
 
     if (writeToProject && resolvedPath && data) {
+      if (data.bddFramework == null) data.bddFramework = framework.bddFramework;
       try {
-        const written = writeGeneratedFiles(resolvedPath, data);
+        const written = await writeGeneratedFiles(resolvedPath, data);
         data._written = written;
       } catch (err) {
         data._writeError = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genat-mcp",
-  "version": "2.2.6",
+  "version": "2.2.8",
   "mcpName": "io.github.asokans@oclc.org/genat",
   "description": "MCP server GenAT: generate accessibility tests via n8n workflow (url + project folder)",
   "type": "module",

package/run-genat.mjs

@@ -66,7 +66,13 @@ async function main() {
   try {
     framework = detectFramework(parentProjectFolder);
   } catch (err) {
-    framework = { scriptType: 'typescript', bddFramework: 'none', pageObject: false, projectSummary: '' };
+    framework = {
+      scriptType: 'typescript',
+      bddFramework: 'none',
+      pageObject: false,
+      projectSummary: '',
+      projectLayoutHints: '',
+    };
   }
 
   let login = {};
@@ -86,6 +92,7 @@ async function main() {
     bddFramework: framework.bddFramework,
     pageObject: framework.pageObject,
     projectSummary: framework.projectSummary,
+    ...(framework.projectLayoutHints && { projectLayoutHints: framework.projectLayoutHints }),
     ...(maxAssertions != null && !isNaN(maxAssertions) && { maxAssertions }),
     ...(scopeToRegions?.length && { scopeToRegions }),
     ...(analyzeStates && { analyzeStates: true }),
@@ -116,6 +123,7 @@ async function main() {
   }
 
   const data = await response.json();
+  if (data.bddFramework == null) data.bddFramework = framework.bddFramework;
   const written = await writeGeneratedFiles(parentProjectFolder, data);
   console.log('GenAT wrote:', written.join(', '));
 }

package/write-files.js

@@ -2,14 +2,36 @@
  * Write generated accessibility test files into the project folder.
  * Uses suggested paths from the workflow response when present.
  */
+import { existsSync } from 'fs';
 import { writeFile, mkdir } from 'fs/promises';
-import { join, resolve } from 'path';
+import { dirname, join, resolve } from 'path';
 
 const DEFAULT_DIR = 'tests/accessibility';
 
+/**
+ * @param {string} root
+ * @returns {{ featureRel: string, stepRel: string, specRel: string }}
+ */
+function resolvePytestBddPaths(root) {
+  let featureRel;
+  if (existsSync(join(root, 'features'))) featureRel = join('features', 'accessibility.feature');
+  else if (existsSync(join(root, 'tests', 'features'))) featureRel = join('tests', 'features', 'accessibility.feature');
+  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');
+
+  const specRel = join(DEFAULT_DIR, 'accessibility_test.py');
+  return { featureRel, stepRel, specRel };
+}
+
 /**
  * @param {string} parentProjectFolder - project root path
- * @param {{ testCode?: string, scriptType?: string, featureFile?: string, stepDefCode?: string, pageObjectCode?: string, suggestedPaths?: Record<string, string> }} data - workflow response
+ * @param {{ testCode?: string, scriptType?: string, bddFramework?: string, featureFile?: string, stepDefCode?: string, pageObjectCode?: string, suggestedPaths?: Record<string, string> }} data - workflow response
  * @returns {string[]} list of written file paths
  */
 export async function writeGeneratedFiles(parentProjectFolder, data) {
@@ -19,6 +41,8 @@ export async function writeGeneratedFiles(parentProjectFolder, data) {
 
   const written = [];
   const scriptType = (data.scriptType || 'typescript').toLowerCase();
+  const bddFramework = (data.bddFramework || 'none').toLowerCase();
+  const usePytestBddLayout = scriptType === 'python' && bddFramework === 'pytest-bdd';
 
   const defaultNames = {
     typescript: { spec: 'accessibility.spec.ts', steps: 'steps.ts', page: 'AccessibilityPage.ts' },
@@ -28,27 +52,92 @@ export async function writeGeneratedFiles(parentProjectFolder, data) {
   const names = defaultNames[scriptType] || defaultNames.typescript;
   const suggested = data.suggestedPaths || {};
 
+  if (usePytestBddLayout) {
+    const pb = resolvePytestBddPaths(root);
+    const dup =
+      data.testCode &&
+      data.stepDefCode &&
+      data.testCode.trim() === data.stepDefCode.trim();
+
+    if (data.featureFile) {
+      const relPath = suggested.feature || pb.featureRel;
+      const abs = join(root, relPath);
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, data.featureFile, 'utf8');
+      written.push(relPath);
+    }
+
+    if (dup) {
+      const relPath = suggested.stepDef || pb.stepRel;
+      const abs = join(root, relPath);
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, data.stepDefCode || data.testCode || '', 'utf8');
+      written.push(relPath);
+    } else {
+      if (data.stepDefCode) {
+        const relPath = suggested.stepDef || pb.stepRel;
+        const abs = join(root, relPath);
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, data.stepDefCode, 'utf8');
+        written.push(relPath);
+      }
+      if (data.testCode) {
+        if (data.stepDefCode) {
+          const relPath = suggested.spec || pb.specRel;
+          const abs = join(root, relPath);
+          await mkdir(dirname(abs), { recursive: true });
+          await writeFile(abs, data.testCode, 'utf8');
+          written.push(relPath);
+        } else {
+          const relPath = suggested.stepDef || pb.stepRel;
+          const abs = join(root, relPath);
+          await mkdir(dirname(abs), { recursive: true });
+          await writeFile(abs, data.testCode, 'utf8');
+          written.push(relPath);
+        }
+      }
+    }
+
+    if (data.pageObjectCode) {
+      const relPath = suggested.pageObject || join(DEFAULT_DIR, names.page);
+      const abs = join(root, relPath);
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, data.pageObjectCode, 'utf8');
+      written.push(relPath);
+    }
+
+    return written;
+  }
+
   if (data.testCode) {
     const relPath = suggested.spec || join(DEFAULT_DIR, names.spec);
-    await writeFile(join(root, relPath), data.testCode, 'utf8');
+    const abs = join(root, relPath);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, data.testCode, 'utf8');
     written.push(relPath);
   }
 
   if (data.featureFile) {
     const relPath = suggested.feature || join(DEFAULT_DIR, 'accessibility.feature');
-    await writeFile(join(root, relPath), data.featureFile, 'utf8');
+    const abs = join(root, relPath);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, data.featureFile, 'utf8');
     written.push(relPath);
   }
 
   if (data.stepDefCode) {
     const relPath = suggested.stepDef || join(DEFAULT_DIR, names.steps);
-    await writeFile(join(root, relPath), data.stepDefCode, 'utf8');
+    const abs = join(root, relPath);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, data.stepDefCode, 'utf8');
     written.push(relPath);
   }
 
   if (data.pageObjectCode) {
     const relPath = suggested.pageObject || join(DEFAULT_DIR, names.page);
-    await writeFile(join(root, relPath), data.pageObjectCode, 'utf8');
+    const abs = join(root, relPath);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, data.pageObjectCode, 'utf8');
     written.push(relPath);
   }