genat-mcp 2.2.7 → 2.3.0

package/README.md

@@ -2,7 +2,9 @@
 
 MCP server that exposes a **GenAT** tool: generate accessibility tests for a URL based on your project folder. It detects framework (TypeScript, JavaScript, or Python, BDD, Page Object), calls an n8n GenAT workflow, and returns (or writes) generated test files.
 
-Full setup (n8n workflow, services, usage) is in the [project README](../README.md).
+Full setup (n8n workflow, services, usage) is in the [project README](../README.md). GenAT workflows also instruct the AI to align with **OCLC internal Confluence** pages ([Accessibility Guidelines and Resources](https://confluence.oclc.org/spaces/UAD/pages/103062358/Accessibility+Guidelines+and+Resources), [OCLC Accessibility Release Blockers](https://confluence.oclc.org/spaces/UXUI/pages/119232333/OCLC+Accessibility+Release+Blockers)); the MCP sends optional extra context from [oclc-accessibility-confluence-context.md](oclc-accessibility-confluence-context.md) or `GENAT_OCLC_ACCESSIBILITY_CONTEXT`.
+
+**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
 
@@ -40,6 +42,7 @@ npm install /path/to/n8n_playwright_tests/mcp-genat
 | **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. |
+| **GENAT_OCLC_ACCESSIBILITY_CONTEXT** | No       | (bundled file) | Optional multiline text sent as `oclcAccessibilityContext` in the webhook body. Overrides the default [oclc-accessibility-confluence-context.md](oclc-accessibility-confluence-context.md) (OCLC UAD guidelines + UXUI release blockers links and notes). Use to paste updated Confluence excerpts without republishing the package. |
 
 ## Framework detection and auto-discovery
 
@@ -49,6 +52,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):**
@@ -156,6 +161,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
@@ -206,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/` 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

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { detectFramework } from './detect-framework.js';
 import { detectLogin } from './detect-login.js';
 import { writeGeneratedFiles } from './write-files.js';
+import { loadOclcAccessibilityContext } from './oclc-context.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;
@@ -55,7 +56,7 @@ function insecureHttpsFetch(url, { method = 'GET', headers = {}, body, signal })
 const server = new McpServer(
   {
     name: 'GenAT',
-    version: '2.2.7',
+    version: '2.3.0',
   },
   {
     capabilities: {
@@ -151,6 +152,7 @@ server.registerTool(
     const maxAssertionsResolved = maxAssertions ?? (process.env.N8N_MAX_ASSERTIONS ? parseInt(process.env.N8N_MAX_ASSERTIONS, 10) : null);
     const scopeToRegionsResolved = scopeToRegions?.length ? scopeToRegions : (process.env.N8N_SCOPE_TO_REGIONS ? process.env.N8N_SCOPE_TO_REGIONS.split(',').map((s) => s.trim()).filter(Boolean) : null);
     const analyzeStatesResolved = analyzeStates || /^1|true|yes$/i.test(process.env.N8N_ANALYZE_STATES || '');
+    const oclcAccessibilityContext = loadOclcAccessibilityContext();
 
     const body = {
       url,
@@ -158,6 +160,8 @@ server.registerTool(
       bddFramework: framework.bddFramework,
       pageObject: framework.pageObject,
       projectSummary: framework.projectSummary,
+      ...(framework.projectLayoutHints && { projectLayoutHints: framework.projectLayoutHints }),
+      ...(oclcAccessibilityContext && { oclcAccessibilityContext }),
       ...(SERVICE_BASE_URL && { serviceBaseUrl: SERVICE_BASE_URL }),
       ...(maxAssertionsResolved != null && !isNaN(maxAssertionsResolved) && { maxAssertions: maxAssertionsResolved }),
       ...(scopeToRegionsResolved?.length && { scopeToRegions: scopeToRegionsResolved }),
@@ -239,8 +243,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/oclc-accessibility-confluence-context.md

@@ -0,0 +1,51 @@
+# OCLC internal accessibility sources (GenAT)
+
+GenAT injects this file into the n8n workflow as **oclcAccessibilityContext** so generated tests align with internal guidance, in addition to WCAG 2.1 AA and related standards from the accessibility analyzer.
+
+Source URLs (canonical):
+
+- **UAD — Accessibility Guidelines and Resources:** https://confluence.oclc.org/spaces/UAD/pages/103062358/Accessibility+Guidelines+and+Resources
+- **UXUI — OCLC Accessibility Release Blockers:** https://confluence.oclc.org/spaces/UXUI/pages/119232333/OCLC+Accessibility+Release+Blockers
+
+---
+
+## Summary: UAD Accessibility Guidelines and Resources
+
+**Policy / Definition of done:** Net-new applications (new UI stack, e.g. React/Angular with Material UI) are expected to be accessible and internationalized. Interfaces must be usable and inclusive.
+
+**Principles:** Follow **POUR** — Perceivable, Operable, Understandable, Robust. Accessibility is broader than screen-reader-only compliance.
+
+**Build (high level):**
+
+- Use Storybook with accessibility tooling where applicable.
+- Valid, well-structured HTML; landmark regions; semantic elements (`main`, `nav`, headings, etc.) over generic `div`/`span` when defining structure.
+- Relative sizing (**rem**/**em**), sensible line-height; avoid locking users out of zoom.
+- Prefer **native** HTML controls (`button`, `a`, `input`, `select`, `form`) over custom reimplementations.
+- Use `<a>` for navigation (with real `href`); use `<button>` for actions (style as link if needed).
+- All images need appropriate **alt** text.
+- Use **ARIA** correctly; incorrect ARIA can harm more than help.
+- **Keyboard:** no traps; focus management after dynamic changes; follow WAI-ARIA authoring practices for composite widgets.
+- Tab order: interactive controls in a logical sequence; avoid `tabindex` on non-interactive elements except focus management (`tabindex="-1"` when appropriate).
+- Treat a11y issues in code review similarly to i18n/hardcoded strings.
+
+**Verify:** Target **WCAG 2.1 AA** plus real-world usability. Combine automated checks (e.g. axe, Pa11y), linting (e.g. eslint-plugin-jsx-a11y), integration/unit tests for behaviors (e.g. modal focus trap), browser tools, and **manual** testing including screen readers (VoiceOver, NVDA) with realistic navigation patterns.
+
+---
+
+## Summary: OCLC Accessibility Release Blockers
+
+**Intent:** Distinguish **critical failures** that must block a release vs. issues that can be fixed post-release.
+
+**The three release blockers** (minimum for OCLC interfaces):
+
+1. **Keyboard operable** — Everything operable without a mouse; no keyboard traps. Primary WCAG tie-in: **2.1.1 Keyboard**. Related: meaningful sequence, no keyboard trap, bypass blocks, focus order, focus visible.
+2. **High contrast** — Text **4.5:1**; non-text UI (icons, borders) **3:1** vs. background. Check hover/focus/selected states. Primary: **1.4.3 Contrast (Minimum)**. Related: use of color, non-text contrast.
+3. **Clearly labeled** — Text alternatives for non-text content; forms and controls have clear, distinguishable names/labels. Primary: **1.1.1 Non-text Content**. Related: info/relationships, link purpose, headings/labels, labels/instructions, name/role/value.
+
+OCLC aims for **WCAG 2.2 A and AA** broadly; prioritize **site-wide** issues (login, headers/footers, navigation, reusable components, contrast) when triaging.
+
+**For GenAT:** Generated tests should explicitly exercise these three themes (keyboard paths, contrast-relevant assertions where feasible, labels/roles/names) in addition to axe rule coverage.
+
+---
+
+Teams may override this file via env **`GENAT_OCLC_ACCESSIBILITY_CONTEXT`** to paste updated Confluence excerpts without republishing the package.

package/oclc-context.js

@@ -0,0 +1,24 @@
+/**
+ * Optional OCLC Confluence text appended to the n8n webhook body as oclcAccessibilityContext.
+ * Env GENAT_OCLC_ACCESSIBILITY_CONTEXT overrides the default file.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_FILE = join(__dirname, 'oclc-accessibility-confluence-context.md');
+const MAX_LEN = 120000;
+
+export function loadOclcAccessibilityContext() {
+  const fromEnv = process.env.GENAT_OCLC_ACCESSIBILITY_CONTEXT?.trim();
+  if (fromEnv) return fromEnv.slice(0, MAX_LEN);
+  if (existsSync(DEFAULT_FILE)) {
+    try {
+      return readFileSync(DEFAULT_FILE, 'utf8').trim().slice(0, MAX_LEN);
+    } catch {
+      return '';
+    }
+  }
+  return '';
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "genat-mcp",
-  "version": "2.2.7",
+  "version": "2.3.0",
   "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", "run-genat.mjs", "rules/genat-mcp.mdc"],
+  "files": ["index.js", "detect-framework.js", "detect-login.js", "write-files.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/run-genat.mjs

@@ -13,12 +13,14 @@
  *   N8N_MAX_ASSERTIONS - override assertion count (e.g. 25)
  *   N8N_SCOPE_TO_REGIONS - comma-separated regions (e.g. header,main,table)
  *   N8N_ANALYZE_STATES - set to 1 to analyze dropdown/combobox expanded states
+ *   GENAT_OCLC_ACCESSIBILITY_CONTEXT - optional; overrides bundled oclc-accessibility-confluence-context.md for the workflow prompt
  */
 import https from 'node:https';
 import { resolve } from 'node:path';
 import { detectFramework } from './detect-framework.js';
 import { detectLogin } from './detect-login.js';
 import { writeGeneratedFiles } from './write-files.js';
+import { loadOclcAccessibilityContext } from './oclc-context.js';
 
 const DEFAULT_WEBHOOK = 'http://localhost:5678/webhook-test/webhook-genat-login';
 const N8N_WEBHOOK_URL = process.env.N8N_WEBHOOK_URL || DEFAULT_WEBHOOK;
@@ -66,7 +68,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 = {};
@@ -79,6 +87,7 @@ async function main() {
     ? process.env.N8N_SCOPE_TO_REGIONS.split(',').map((s) => s.trim()).filter(Boolean)
     : null;
   const analyzeStates = /^1|true|yes$/i.test(process.env.N8N_ANALYZE_STATES || '');
+  const oclcAccessibilityContext = loadOclcAccessibilityContext();
 
   const body = {
     url,
@@ -86,6 +95,8 @@ async function main() {
     bddFramework: framework.bddFramework,
     pageObject: framework.pageObject,
     projectSummary: framework.projectSummary,
+    ...(framework.projectLayoutHints && { projectLayoutHints: framework.projectLayoutHints }),
+    ...(oclcAccessibilityContext && { oclcAccessibilityContext }),
     ...(maxAssertions != null && !isNaN(maxAssertions) && { maxAssertions }),
     ...(scopeToRegions?.length && { scopeToRegions }),
     ...(analyzeStates && { analyzeStates: true }),
@@ -116,6 +127,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);
   }