@ai-qa/workflow 2.0.0

package/scripts/executor.js

@@ -0,0 +1,142 @@
+const { DIRS, CONFIG, ensureDir, timestamp, log } = require('./utils');
+const path = require('path');
+const fs = require('fs');
+const { execSync, spawn } = require('child_process');
+
+function executeTests(testName, options = {}) {
+  const testCfg = CONFIG.test || {};
+  const {
+    headed = CONFIG.browser && CONFIG.browser.headed || false,
+    timeout = testCfg.timeout || 120000,
+    retries = testCfg.retries || 0,
+    workers = testCfg.workers || 1,
+    screenshots = 'off',
+  } = options;
+
+  const runId = `run-${timestamp()}`;
+  const runDir = path.join(DIRS.testResults, runId);
+  ensureDir(runDir);
+
+  log('EXECUTOR', `Run ID: ${runId}`);
+  log('EXECUTOR', `Test: ${testName || 'all tests'}`);
+
+  const args = ['playwright', 'test'];
+
+  if (testName) {
+    let testFile = testName.endsWith('.spec.ts') ? testName : `${testName}.spec.ts`;
+    if (testFile.includes('/') || testFile.includes('\\')) {
+      args.push(testFile);
+    } else {
+      args.push(path.join('tests', testFile));
+    }
+  }
+
+  args.push('--reporter=list,json');
+
+  if (headed) args.push('--headed');
+  if (retries > 0) args.push(`--retries=${retries}`);
+  if (workers) args.push(`--workers=${workers}`);
+  if (timeout) args.push(`--timeout=${timeout}`);
+  if (screenshots === 'off') args.push('--screenshot=off');
+  if (screenshots === 'only-on-failure') args.push('--screenshot=only-on-failure');
+
+  const outputPath = path.join(runDir, 'execution-output.json');
+  const resultPath = path.join(runDir, 'execution-result.json');
+
+  log('EXECUTOR', `Command: npx ${args.join(' ')}`);
+
+  const startTime = Date.now();
+
+  try {
+    const stdout = execSync(`npx ${args.join(' ')}`, {
+      cwd: DIRS.ROOT,
+      encoding: 'utf-8',
+      timeout: 300000,
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    fs.writeFileSync(outputPath, stdout, 'utf-8');
+
+    const result = {
+      runId,
+      test: testName || 'all',
+      success: true,
+      exitCode: 0,
+      duration: Date.now() - startTime,
+      timestamp: new Date().toISOString(),
+      output: stdout.substring(0, 50000),
+      failedTests: [],
+      passedTests: [],
+    };
+
+    writeMarkdown(resultPath, JSON.stringify(result, null, 2));
+    log('EXECUTOR', `Tests passed (${result.duration}ms)`);
+
+    return result;
+  } catch (err) {
+    const stderr = err.stderr || '';
+    const stdout = err.stdout || '';
+
+    const combinedOutput = stdout + '\n' + stderr;
+    fs.writeFileSync(outputPath, combinedOutput, 'utf-8');
+
+    const failedTests = extractFailedTests(combinedOutput);
+
+    const result = {
+      runId,
+      test: testName || 'all',
+      success: false,
+      exitCode: err.status || 1,
+      duration: Date.now() - startTime,
+      timestamp: new Date().toISOString(),
+      error: err.message,
+      output: combinedOutput.substring(0, 50000),
+      failedTests,
+    };
+
+    writeMarkdown(resultPath, JSON.stringify(result, null, 2));
+    log('EXECUTOR', `Tests failed (${result.duration}ms) - ${failedTests.length} failure(s)`);
+
+    return result;
+  }
+}
+
+function extractFailedTests(output) {
+  const failed = [];
+  const lines = output.split('\n');
+
+  let current = null;
+  for (const line of lines) {
+    const failMatch = line.match(/\s+×\s+\d+\)\s+\[(.+?)\]\s+(.+)/);
+    if (failMatch) {
+      failed.push({ file: failMatch[1], test: failMatch[2].trim() });
+      continue;
+    }
+
+    const failSimple = line.match(/\s+×\s+(.+)/);
+    if (failSimple && !line.includes('ms')) {
+      current = { test: failSimple[1].trim(), error: '' };
+      continue;
+    }
+
+    if (current && line.trim()) {
+      current.error += line.trim() + ' ';
+    }
+
+    if (current && line.trim() === '') {
+      failed.push(current);
+      current = null;
+    }
+  }
+
+  return failed;
+}
+
+if (require.main === module) {
+  const testName = process.argv[2];
+  const headed = process.argv.includes('--headed');
+  executeTests(testName, { headed });
+}
+
+module.exports = { executeTests };

package/scripts/generator.js

@@ -0,0 +1,130 @@
+const { DIRS, CONFIG, readMarkdown, writeMarkdown, slugify, log } = require('./utils');
+const path = require('path');
+const fs = require('fs');
+
+function generateTestSpec(planName) {
+  const planPath = path.join(DIRS.specs, planName);
+  if (!fs.existsSync(planPath)) {
+    console.error(`Test plan not found: ${planPath}`);
+    console.log(`Available plans: ${require('./utils').listTestPlans().join(', ')}`);
+    process.exit(1);
+  }
+
+  const content = readMarkdown(planPath);
+  const specName = planName.replace('-test-plan.md', '');
+  const specPath = path.join(DIRS.tests, `${specName}.spec.ts`);
+
+  log('GENERATOR', `Generating test spec from: ${planName}`);
+
+  const spec = generateSpecContent(content, specName, planName);
+
+  writeMarkdown(specPath, spec);
+  log('GENERATOR', `Test spec saved: tests/${specName}.spec.ts`);
+
+  return { specName, specPath };
+}
+
+function generateSpecContent(planContent, specName, planFileName) {
+  const featureMatch = planContent.match(/\*\*Feature\*\*:\s*(.+)/);
+  const feature = featureMatch ? featureMatch[1].trim() : specName;
+
+  const scenarios = extractScenarios(planContent);
+
+  const browserType = CONFIG.browser.type || 'chromium';
+  const cdpPort = CONFIG.browser.cdpPort || 9222;
+  const cdpImport = browserType === 'edge' ? "import { startEdgeCDP } from '../cdpSession';" : `import { chromium } from '@playwright/test';`;
+
+  let setupBlock;
+  if (browserType === 'edge') {
+    setupBlock = `    // const { page } = await startEdgeCDP();\n    // global.page = page;`;
+  } else {
+    setupBlock = `    // const browser = await chromium.launch({ headless: !process.env.HEADED });\n    // const page = await browser.newPage();\n    // global.page = page;`;
+  }
+
+  let spec = `import { test, expect } from '@playwright/test';
+${cdpImport}
+
+test.describe('${feature.replace(/'/g, "\\'")}', () => {
+
+  test.beforeEach(async () => {
+${setupBlock}
+  });
+
+  test.afterEach(async () => {
+    // Cleanup if needed
+  });
+
+`;
+
+  scenarios.forEach((scenario, idx) => {
+    const safeTitle = scenario.title.replace(/['"]/g, "'");
+    spec += `  test('${safeTitle}', async () => {\n`;
+    spec += `    // TODO: Implement test steps from plan\n`;
+    spec += `    // Reference: specs/${planFileName} (Scenario ${idx + 3}.1)\n`;
+    spec += `    // \n`;
+
+    scenario.steps.forEach((step, si) => {
+      const truncated = step.length > 100 ? step.substring(0, 97) + '...' : step;
+      spec += `    // Step ${si + 1}: ${truncated}\n`;
+    });
+
+    spec += `    // \n`;
+    spec += `    // Expected: ${scenario.expected || 'Workflow completes successfully'}\n`;
+    spec += `    \n`;
+    spec += `  });\n\n`;
+  });
+
+  spec += `});\n`;
+
+  return spec;
+}
+
+function extractScenarios(content) {
+  const scenarios = [];
+  const lines = content.split('\n');
+  let current = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    const scenarioMatch = line.match(/###\s+\d+\.\d+\s+Scenario:\s*(.+)/i);
+    if (scenarioMatch) {
+      if (current) scenarios.push(current);
+      current = { title: scenarioMatch[1].trim(), steps: [], expected: '' };
+      continue;
+    }
+
+    if (current) {
+      const stepMatch = line.match(/^\d+\.\s+(.+)/);
+      if (stepMatch && !line.match(/^\d+\.\s+\*\*/)) {
+        current.steps.push(stepMatch[1].trim());
+      }
+
+      const expectedMatch = line.match(/Expected Results?[:\]]\s*(.+)/i);
+      if (expectedMatch) {
+        current.expected = expectedMatch[1].trim();
+      }
+
+      if (line.match(/---/) && current.steps.length > 0) {
+        scenarios.push(current);
+        current = null;
+      }
+    }
+  }
+
+  if (current) scenarios.push(current);
+
+  return scenarios;
+}
+
+if (require.main === module) {
+  const planName = process.argv[2];
+  if (!planName) {
+    console.log('Usage: node scripts/generator.js <test-plan-file.md>');
+    console.log(`Available: ${require('./utils').listTestPlans().join(', ')}`);
+    process.exit(1);
+  }
+  generateTestSpec(planName);
+}
+
+module.exports = { generateTestSpec };

package/scripts/healer.js

@@ -0,0 +1,207 @@
+const { DIRS, ensureDir, timestamp, log } = require('./utils');
+const path = require('path');
+const fs = require('fs');
+
+const KNOWN_BUG_PATTERNS = [
+  { pattern: /element\(s\) not found/i, type: 'selector' },
+  { pattern: /strict mode violation/i, type: 'selector' },
+  { pattern: /Target closed/i, type: 'environment' },
+  { pattern: /net::ERR_/i, type: 'environment' },
+  { pattern: /timeout/i, type: 'timing' },
+  { pattern: /page\.goto/i, type: 'navigation' },
+  { pattern: /Cannot find module/i, type: 'test-syntax' },
+];
+
+function classifyFailure(errorMessage) {
+  if (!errorMessage) return { type: 'unknown', fixable: false };
+  for (const rule of KNOWN_BUG_PATTERNS) {
+    if (rule.pattern.test(errorMessage)) {
+      return { type: rule.type, fixable: rule.type !== 'environment' };
+    }
+  }
+  return { type: 'unknown', fixable: false };
+}
+
+function selfHeal(runId, projectName, options = {}) {
+  const { maxAttempts = 2 } = options;
+
+  const runDir = runId
+    ? path.join(DIRS.testResults, runId)
+    : findLatestRunDir();
+
+  if (!runDir || !fs.existsSync(runDir)) {
+    log('HEALER', 'No execution results found to heal');
+    return { healed: [], remaining: [], defects: [] };
+  }
+
+  const resultPath = path.join(runDir, 'execution-result.json');
+  if (!fs.existsSync(resultPath)) {
+    log('HEALER', 'No execution result found');
+    return { healed: [], remaining: [], defects: [] };
+  }
+
+  const result = JSON.parse(fs.readFileSync(resultPath, 'utf-8'));
+
+  if (result.success) {
+    log('HEALER', 'All tests passed - nothing to heal');
+    return { healed: [], remaining: [], defects: [] };
+  }
+
+  const screenshotDir = path.join(DIRS.testResults, 'screenshots', projectName || 'unknown');
+  ensureDir(screenshotDir);
+
+  const defects = [];
+  let remainingFailures = [...(result.failedTests || [])];
+
+  log('HEALER', `Found ${remainingFailures.length} failed test(s)`);
+  log('HEALER', `Screenshots will be saved to: test-results/screenshots/${projectName || 'unknown'}/`);
+
+  remainingFailures = remainingFailures.filter(failure => {
+    const classification = classifyFailure(failure.error);
+    const screenshotPath = path.join(screenshotDir, `${slugify(failure.test || 'failure')}.png`);
+
+    defects.push({
+      test: failure.test || failure.file,
+      error: failure.error ? failure.error.substring(0, 200) : 'Unknown',
+      classification: classification.type,
+      verdict: classification.fixable ? 'FIXABLE' : 'BUG',
+      action: classification.fixable
+        ? 'Attempting auto-heal'
+        : 'Cannot auto-fix — reporting as defect',
+      screenshot: screenshotPath,
+    });
+    log('HEALER', `  ${classification.fixable ? '⚠️' : '⛔'} ${failure.test || failure.file} — ${classification.type}${classification.fixable ? '' : ' (BUG)'}`);
+
+    if (!classification.fixable) return false;
+    return true;
+  });
+
+  const healingLog = [];
+  let attempt = 0;
+
+  while (attempt < maxAttempts && remainingFailures.length > 0) {
+    attempt++;
+    log('HEALER', `Healing attempt ${attempt}/${maxAttempts}`);
+
+    const healed = [];
+    const stillFailing = [];
+
+    for (const failure of remainingFailures) {
+      log('HEALER', `  Re-running: ${failure.test || failure.file}`);
+      const healedResult = attemptHealStrategy(failure, attempt, runDir);
+
+      if (healedResult.success) {
+        healed.push({ ...failure, healedOnAttempt: attempt, strategy: healedResult.strategy });
+        const defect = defects.find(d => d.test === failure.test);
+        if (defect) defect.healed = true;
+        log('HEALER', `  ✓ Healed: ${failure.test || failure.file}`);
+      } else {
+        stillFailing.push(failure);
+        log('HEALER', `  ✗ Still failing: ${failure.test || failure.file}`);
+        const defect = defects.find(d => d.test === failure.test);
+        if (defect) {
+          defect.verdict = 'UNSTABLE';
+          defect.action = 'Requires manual investigation';
+        }
+      }
+    }
+
+    healingLog.push({ attempt, healed, stillFailing, timestamp: new Date().toISOString() });
+    remainingFailures = stillFailing;
+  }
+
+  remainingFailures.forEach(f => {
+    if (!defects.find(d => d.test === f.test)) {
+      defects.push({
+        test: f.test || f.file,
+        error: f.error ? f.error.substring(0, 200) : 'Failed after healing',
+        classification: 'unresolved',
+        verdict: 'UNSTABLE',
+        action: 'Requires manual investigation',
+      });
+    }
+  });
+
+  const healingReport = {
+    projectName: projectName || 'unknown',
+    screenshotDir: `test-results/screenshots/${projectName || 'unknown'}/`,
+    runId: path.basename(runDir),
+    originalResult: { total: result.failedTests ? result.failedTests.length : 0 },
+    healingAttempts: healingLog,
+    totalHealed: healingLog.reduce((sum, a) => sum + a.healed.length, 0),
+    totalRemaining: remainingFailures.length,
+    totalDefects: defects.length,
+    defects,
+    timestamp: new Date().toISOString(),
+    finalStatus: remainingFailures.length === 0 && defects.filter(d => d.verdict !== 'FIXABLE').length === 0 ? 'all-passed'
+      : remainingFailures.length === 0 ? 'all-passed-with-defects'
+      : 'partial',
+  };
+
+  const reportPath = path.join(runDir, 'healing-report.json');
+  fs.writeFileSync(reportPath, JSON.stringify(healingReport, null, 2), 'utf-8');
+
+  log('HEALER', `Healing complete:`);
+  log('HEALER', `  Healed: ${healingReport.totalHealed}`);
+  log('HEALER', `  Defects found: ${defects.filter(d => d.verdict === 'BUG').length}`);
+  log('HEALER', `  Screenshots: test-results/screenshots/${projectName || 'unknown'}/`);
+
+  if (defects.length > 0) {
+    console.log('\n  Defects:');
+    defects.forEach(d => {
+      const icon = d.verdict === 'BUG' ? '⛔ BUG' : d.verdict === 'UNSTABLE' ? '⚠️ UNSTABLE' : '✓ FIXED';
+      console.log(`    ${icon} ${d.test}`);
+      console.log(`       → ${d.classification}: ${d.error.substring(0, 100)}`);
+      console.log(`       → Screenshot: ${d.screenshot}`);
+    });
+  }
+
+  return { healed: healingLog.flatMap(a => a.healed), remaining: remainingFailures, defects, reportPath };
+}
+
+function attemptHealStrategy(failure, attempt, runDir) {
+  const strategies = [
+    { name: 'retry-standard' },
+    { name: 'retry-longer-timeout', timeout: 60000 },
+  ];
+
+  const strategy = strategies[Math.min(attempt - 1, strategies.length - 1)];
+  const testFile = failure.file || failure.test || '';
+
+  try {
+    const args = ['npx', 'playwright', 'test', testFile, '--reporter=list'];
+    if (strategy.timeout) args.push(`--timeout=${strategy.timeout}`);
+
+    require('child_process').execSync(args.join(' '), {
+      cwd: DIRS.ROOT,
+      encoding: 'utf-8',
+      timeout: 120000,
+      stdio: 'pipe',
+    });
+
+    return { success: true, strategy: strategy.name };
+  } catch {
+    return { success: false, strategy: strategy.name };
+  }
+}
+
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').substring(0, 80);
+}
+
+function findLatestRunDir() {
+  if (!fs.existsSync(DIRS.testResults)) return null;
+  const dirs = fs.readdirSync(DIRS.testResults)
+    .map(d => ({ name: d, path: path.join(DIRS.testResults, d) }))
+    .filter(d => fs.statSync(d.path).isDirectory())
+    .sort((a, b) => fs.statSync(b.path).mtimeMs - fs.statSync(a.path).mtimeMs);
+  return dirs.length > 0 ? dirs[0].path : null;
+}
+
+if (require.main === module) {
+  const runId = process.argv[2];
+  const projectName = process.argv[3];
+  selfHeal(runId, projectName);
+}
+
+module.exports = { selfHeal };

package/scripts/planner.js

@@ -0,0 +1,142 @@
+const { DIRS, CONFIG, parseUserStory, readMarkdown, writeMarkdown, slugify, log } = require('./utils');
+const path = require('path');
+
+function generateTestPlan(storyName) {
+  const storyPath = path.join(DIRS.userStory, storyName);
+  if (!require('fs').existsSync(storyPath)) {
+    console.error(`User story not found: ${storyPath}`);
+    console.log(`Available stories: ${require('./utils').listUserStories().join(', ')}`);
+    process.exit(1);
+  }
+
+  const story = parseUserStory(storyPath);
+  const planId = slugify(story.id || story.title || storyName.replace('.md', ''));
+  const planPath = path.join(DIRS.specs, `${planId}-test-plan.md`);
+
+  log('PLANNER', `Generating test plan from: ${storyName}`);
+  log('PLANNER', `Story: ${story.metaTitle || story.title}`);
+
+  const plan = generatePlanContent(story, planId);
+
+  writeMarkdown(planPath, plan);
+  log('PLANNER', `Test plan saved: specs/${planId}-test-plan.md`);
+
+  return { planId, planPath };
+}
+
+function generatePlanContent(story, planId) {
+  const date = new Date().toISOString().split('T')[0];
+
+  let plan = `# Test Plan: ${story.metaTitle || story.title}
+
+**ID**: PLAN-${(story.id || planId).toUpperCase()}
+**Feature**: ${story.title || story.metaTitle || 'N/A'}
+**Status**: Draft
+**User Story Ref**: ${story.id || 'N/A'}
+**Generated**: ${date}
+
+---
+
+## 1. Overview
+
+${story.description || 'Automated test plan derived from user story.'}
+
+---
+
+## 2. Preconditions
+
+`;
+
+  if (story.preconditions && story.preconditions.length > 0) {
+    story.preconditions.forEach(p => { plan += `- ${p}\n`; });
+  } else {
+    plan += `- Environment: ${CONFIG.project.url}\n`;
+    plan += `- Browser: ${CONFIG.browser.type === 'edge' ? 'Microsoft Edge via CDP' : 'Chromium'} (Port ${CONFIG.browser.cdpPort})\n`;
+    plan += `- User credentials as specified in user story\n`;
+  }
+
+  plan += `
+
+---
+
+## 3. Test Scenarios
+
+`;
+
+  if (story.acceptanceCriteria) {
+    const sections = story.acceptanceCriteria.split(/(?=###\s+\d)/);
+    sections.forEach((section, idx) => {
+      const trimmed = section.trim();
+      if (!trimmed) return;
+
+      const titleMatch = trimmed.match(/###\s+\d+\.\s*(.+?)(?:\n|$)/);
+      const title = titleMatch ? titleMatch[1].trim() : `Scenario ${idx + 1}`;
+
+      const steps = parseSteps(trimmed);
+
+      plan += `### ${idx + 3}.1 Scenario: ${title}\n`;
+      plan += `**Steps**:\n`;
+      steps.forEach((s, i) => { plan += `${i + 1}. ${s}\n`; });
+      plan += `\n**Expected Results**:\n`;
+      plan += `- Feature behaves as described in acceptance criteria\n`;
+      plan += `- No errors or unexpected behavior\n`;
+      plan += `\n---\n\n`;
+    });
+  } else {
+    plan += `### 3.1 Scenario: Happy Path\n`;
+    plan += `**Steps**:\n`;
+    plan += `1. Login with the specified user credentials\n`;
+    plan += `2. Navigate to the feature\n`;
+    plan += `3. Execute the primary workflow\n`;
+    plan += `4. Verify success state\n\n`;
+    plan += `**Expected Results**:\n`;
+    plan += `- Workflow completes successfully\n\n`;
+    plan += `---\n\n`;
+  }
+
+  plan += `## 4. Success Criteria\n`;
+  plan += `- All scenarios pass without errors\n`;
+  plan += `- Screenshots are captured for key verification points\n`;
+  plan += `- Allure report is generated with test results\n\n`;
+
+  plan += `---\n\n`;
+  plan += `> **AI Instructions**: Review this test plan. Verify scenarios cover all acceptance criteria.\n`;
+  plan += `> Add edge cases, negative scenarios, and boundary tests where applicable.\n`;
+  plan += `> Update status from "Draft" to "Reviewed" once validated.\n`;
+
+  return plan;
+}
+
+function parseSteps(text) {
+  const steps = [];
+  const lines = text.split('\n');
+  let inSteps = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (/^\d+\.\s+/.test(trimmed)) {
+      inSteps = true;
+      steps.push(trimmed.replace(/^\d+\.\s+/, ''));
+    } else if (inSteps && trimmed.startsWith('-')) {
+      steps.push(trimmed.replace(/^- /, ''));
+    } else if (inSteps && trimmed === '') {
+      continue;
+    } else if (inSteps) {
+      break;
+    }
+  }
+
+  return steps.length > 0 ? steps : ['Execute the workflow as described in the user story.'];
+}
+
+if (require.main === module) {
+  const storyName = process.argv[2];
+  if (!storyName) {
+    console.log('Usage: node scripts/planner.js <user-story-file.md>');
+    console.log(`Available: ${require('./utils').listUserStories().join(', ')}`);
+    process.exit(1);
+  }
+  generateTestPlan(storyName);
+}
+
+module.exports = { generateTestPlan };