@bearcreekai/testing-kx-mcp 1.0.0

package/bin.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for testing-kx MCP server.
+ * Usage: npx @knowledgexpert/testing-kx-mcp
+ *
+ * This starts the MCP server via stdio transport.
+ * It auto-downloads test files on first run if not present.
+ */
+
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// When running via npx, the package is in a temp directory.
+// We need the test files to be in a known location.
+const HOME = process.env.HOME || process.env.USERPROFILE;
+const DATA_DIR = path.join(HOME, '.testing-kx');
+const REPO_URL = process.env.TESTING_KX_REPO || 'https://github.com/BearCreekAI/testing-kx.git';
+
+async function ensureTestFiles() {
+  // If running from the actual repo (not npx), test files are already here
+  const localTests = path.join(__dirname, '..', 'tests');
+  if (fs.existsSync(localTests)) {
+    // We're in the repo — set PROJECT_ROOT and run
+    process.env.TESTING_KX_ROOT = path.resolve(__dirname, '..');
+    return;
+  }
+
+  // Running via npx — check if test files are cached at ~/.testing-kx
+  if (fs.existsSync(path.join(DATA_DIR, 'tests'))) {
+    process.env.TESTING_KX_ROOT = DATA_DIR;
+    console.error(`Using cached test files from ${DATA_DIR}`);
+
+    // Pull latest in background (non-blocking)
+    const pull = spawn('git', ['pull', '--quiet'], { cwd: DATA_DIR, stdio: 'ignore', shell: true });
+    pull.unref();
+    return;
+  }
+
+  // First run — clone the repo
+  console.error(`First run: downloading test files to ${DATA_DIR}...`);
+  try {
+    const clone = spawn('git', ['clone', '--depth', '1', REPO_URL, DATA_DIR], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: true,
+    });
+
+    await new Promise((resolve, reject) => {
+      clone.on('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`Git clone failed with code ${code}`));
+      });
+      clone.on('error', reject);
+    });
+
+    // Install dependencies
+    console.error('Installing dependencies...');
+    const install = spawn('npm', ['ci', '--production'], {
+      cwd: DATA_DIR,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: true,
+    });
+
+    await new Promise((resolve, reject) => {
+      install.on('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`npm install failed with code ${code}`));
+      });
+      install.on('error', reject);
+    });
+
+    // Install playwright browsers
+    console.error('Installing Playwright browsers...');
+    const pwInstall = spawn('npx', ['playwright', 'install', 'chromium'], {
+      cwd: DATA_DIR,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: true,
+    });
+
+    await new Promise((resolve, reject) => {
+      pwInstall.on('close', (code) => {
+        if (code === 0) resolve();
+        else reject(new Error(`Playwright install failed with code ${code}`));
+      });
+      pwInstall.on('error', reject);
+    });
+
+    process.env.TESTING_KX_ROOT = DATA_DIR;
+    console.error('Setup complete!');
+  } catch (err) {
+    console.error(`Setup failed: ${err.message}`);
+    console.error('Falling back to local mode. Make sure you have the testing-kx repo cloned.');
+    process.exit(1);
+  }
+}
+
+await ensureTestFiles();
+
+// Now start the actual MCP server
+await import('./server.js');

package/lib/playwright-runner.js

@@ -0,0 +1,222 @@
+import { spawn } from 'child_process';
+import http from 'http';
+import https from 'https';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Support both running from repo (../.. from mcp/lib/) and via npx (TESTING_KX_ROOT env)
+const PROJECT_ROOT = process.env.TESTING_KX_ROOT || path.resolve(__dirname, '..', '..');
+const LOCK_FILE = path.join(PROJECT_ROOT, 'test-results', '.mcp-lock');
+const RESULTS_FILE = path.join(PROJECT_ROOT, 'test-results', 'results.json');
+
+// Module-level state
+let isRunning = false;
+let currentRun = null;
+
+/**
+ * Check if another process (Express server or manual CLI) is running tests.
+ */
+function isExternalRunActive() {
+  // Check if Express server's lock exists (it writes results.json actively)
+  // Also check our own lock file
+  if (fs.existsSync(LOCK_FILE)) {
+    try {
+      const lockData = JSON.parse(fs.readFileSync(LOCK_FILE, 'utf8'));
+      const lockAge = Date.now() - lockData.timestamp;
+      // If lock is older than 15 minutes, it's stale — remove it
+      if (lockAge > 15 * 60 * 1000) {
+        fs.unlinkSync(LOCK_FILE);
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+function acquireLock(runId) {
+  const lockData = { runId, timestamp: Date.now(), pid: process.pid };
+  fs.writeFileSync(LOCK_FILE, JSON.stringify(lockData));
+}
+
+function releaseLock() {
+  try {
+    if (fs.existsSync(LOCK_FILE)) fs.unlinkSync(LOCK_FILE);
+  } catch { /* ignore */ }
+}
+
+/**
+ * Get the current run status.
+ */
+export function getStatus() {
+  if (!isRunning || !currentRun) {
+    return { isRunning: false, currentRun: null };
+  }
+  return {
+    isRunning: true,
+    currentRun: {
+      runId: currentRun.id,
+      startTime: currentRun.startTime,
+      elapsedSeconds: Math.round((Date.now() - new Date(currentRun.startTime).getTime()) / 1000),
+      testLabel: currentRun.testLabel,
+      lastOutput: currentRun.output.slice(-500),
+    },
+  };
+}
+
+/**
+ * Check if a URL is reachable (server is running).
+ */
+export function checkServerHealth(url, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const client = url.startsWith('https') ? https : http;
+    const req = client.get(url, { timeout: timeoutMs }, (res) => {
+      resolve({ reachable: true, statusCode: res.statusCode });
+    });
+    req.on('error', () => resolve({ reachable: false }));
+    req.on('timeout', () => { req.destroy(); resolve({ reachable: false }); });
+  });
+}
+
+/**
+ * Spawn Playwright and run tests.
+ *
+ * @param {Object} opts
+ * @param {string} [opts.tag] - Test tag (@smoke, @regression, etc.)
+ * @param {string} [opts.file] - Specific test file
+ * @param {string} [opts.grep] - Playwright --grep pattern
+ * @param {string} [opts.baseUrl] - URL to test against (default: http://localhost:5173)
+ * @param {number} [opts.timeout] - Max wait in ms (default 600000)
+ * @returns {Promise<Object>} Structured test results
+ */
+export function runPlaywright(opts = {}) {
+  return new Promise(async (resolve, reject) => {
+    if (isRunning) {
+      reject(new Error('Tests are already running. Use get_test_status to check progress.'));
+      return;
+    }
+
+    if (isExternalRunActive()) {
+      reject(new Error('Tests are already running from another source (dashboard or CLI). Try again later.'));
+      return;
+    }
+
+    // Determine BASE_URL — MCP defaults to localhost (dev workflow)
+    const DEFAULT_LOCAL_URL = process.env.MCP_DEFAULT_URL || 'http://localhost:5173';
+    const baseUrl = opts.baseUrl || DEFAULT_LOCAL_URL;
+
+    // Health check — make sure the target server is running
+    const health = await checkServerHealth(baseUrl);
+    if (!health.reachable) {
+      reject(new Error(
+        `Cannot reach ${baseUrl} — is your local dev server running?\n\n` +
+        `Start your frontend first (e.g. "npm run dev"), then try again.\n` +
+        `If you intentionally want to test a different URL, pass baseUrl explicitly.`
+      ));
+      return;
+    }
+
+    isRunning = true;
+    const startTime = new Date();
+    const runId = Date.now().toString();
+
+    const testLabel = opts.tag ? `@${opts.tag} suite` : (opts.file || opts.grep || 'all');
+
+    currentRun = {
+      id: runId,
+      startTime: startTime.toISOString(),
+      testLabel,
+      output: '',
+    };
+
+    acquireLock(runId);
+
+    // Build playwright args
+    const args = ['playwright', 'test'];
+    if (opts.tag) {
+      args.push('--grep', `@${opts.tag}`);
+    } else if (opts.file) {
+      args.push(opts.file);
+    } else if (opts.grep) {
+      args.push('--grep', opts.grep);
+    }
+
+    const child = spawn('npx', args, {
+      cwd: PROJECT_ROOT,
+      env: { ...process.env, CI: 'true', BASE_URL: baseUrl },
+      shell: true,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      const text = data.toString();
+      stdout += text;
+      currentRun.output += text;
+    });
+
+    child.stderr.on('data', (data) => {
+      const text = data.toString();
+      stderr += text;
+      currentRun.output += text;
+    });
+
+    // Timeout handling
+    const timeout = opts.timeout || 600000;
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      isRunning = false;
+      currentRun = null;
+      releaseLock();
+      reject(new Error(`Test run timed out after ${timeout / 1000}s. Tests may still be running.`));
+    }, timeout);
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const endTime = new Date();
+      const duration = (endTime - startTime) / 1000;
+
+      // Read results.json
+      let results = null;
+      try {
+        if (fs.existsSync(RESULTS_FILE)) {
+          results = JSON.parse(fs.readFileSync(RESULTS_FILE, 'utf8'));
+        }
+      } catch (e) {
+        // results.json may not exist if all tests were filtered out
+      }
+
+      const runResult = {
+        id: runId,
+        startTime: startTime.toISOString(),
+        endTime: endTime.toISOString(),
+        durationSeconds: Math.round(duration),
+        status: code === 0 ? 'passed' : 'failed',
+        exitCode: code,
+        testLabel,
+        stdout: stdout.slice(-5000), // Keep last 5KB
+        results,
+      };
+
+      isRunning = false;
+      currentRun = null;
+      releaseLock();
+
+      resolve(runResult);
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      isRunning = false;
+      currentRun = null;
+      releaseLock();
+      reject(error);
+    });
+  });
+}

package/lib/result-parser.js

@@ -0,0 +1,207 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = process.env.TESTING_KX_ROOT || path.resolve(__dirname, '..', '..');
+const RESULTS_FILE = path.join(PROJECT_ROOT, 'test-results', 'results.json');
+const HISTORY_FILE = path.join(PROJECT_ROOT, 'test-results', 'test-history.json');
+
+/**
+ * Extract failures from Playwright JSON results.
+ * Mirrors server.js extractFailuresFromResults().
+ */
+export function extractFailures(results) {
+  const failures = [];
+  function walk(suites, parentPath) {
+    if (!suites) return;
+    for (const suite of suites) {
+      const suitePath = parentPath ? `${parentPath} > ${suite.title}` : suite.title;
+      if (suite.specs) {
+        for (const spec of suite.specs) {
+          if (!spec.ok && spec.tests) {
+            for (const test of spec.tests) {
+              if (test.status === 'unexpected' || test.status === 'failed') {
+                const errorResult = (test.results || []).find(r => r.status === 'failed');
+                failures.push({
+                  title: spec.title,
+                  file: spec.file || 'unknown',
+                  line: spec.line || '?',
+                  suitePath,
+                  errorMessage: errorResult?.error?.message || 'Unknown error',
+                  stack: errorResult?.error?.stack || '',
+                  retries: (test.results || []).length,
+                });
+              }
+            }
+          }
+        }
+      }
+      if (suite.suites) walk(suite.suites, suitePath);
+    }
+  }
+  walk(results.suites, '');
+  return failures;
+}
+
+/**
+ * Extract all tests with their status from results.
+ */
+function extractAllTests(results) {
+  const tests = [];
+  function walk(suites, parentPath) {
+    if (!suites) return;
+    for (const suite of suites) {
+      const suitePath = parentPath ? `${parentPath} > ${suite.title}` : suite.title;
+      if (suite.specs) {
+        for (const spec of suite.specs) {
+          if (spec.tests) {
+            for (const test of spec.tests) {
+              const lastResult = (test.results || []).at(-1);
+              tests.push({
+                title: spec.title,
+                file: spec.file || 'unknown',
+                suitePath,
+                status: test.status,
+                ok: spec.ok,
+                duration: lastResult?.duration || 0,
+              });
+            }
+          }
+        }
+      }
+      if (suite.suites) walk(suite.suites, suitePath);
+    }
+  }
+  walk(results.suites, '');
+  return tests;
+}
+
+/**
+ * Parse run results into a structured summary.
+ */
+export function parseSummary(runResult) {
+  const results = runResult.results;
+  if (!results) {
+    return {
+      runId: runResult.id,
+      status: runResult.status,
+      durationSeconds: runResult.durationSeconds,
+      message: 'No detailed results available (results.json not found)',
+    };
+  }
+
+  const stats = results.stats || {};
+  const failures = extractFailures(results);
+
+  return {
+    runId: runResult.id,
+    status: runResult.status,
+    durationSeconds: runResult.durationSeconds,
+    passed: stats.expected || 0,
+    failed: stats.unexpected || 0,
+    flaky: stats.flaky || 0,
+    skipped: stats.skipped || 0,
+    total: (stats.expected || 0) + (stats.unexpected || 0) + (stats.flaky || 0) + (stats.skipped || 0),
+    failedTests: failures.map(f => ({
+      name: f.title,
+      file: f.file,
+      error: f.errorMessage.slice(0, 200),
+    })),
+  };
+}
+
+/**
+ * Parse run results with full error details.
+ */
+export function parseDetailed(runResult) {
+  const summary = parseSummary(runResult);
+  const results = runResult.results;
+  if (!results) return summary;
+
+  const failures = extractFailures(results);
+  const allTests = extractAllTests(results);
+
+  return {
+    ...summary,
+    failedTests: failures.map(f => ({
+      name: f.title,
+      file: f.file,
+      line: f.line,
+      suitePath: f.suitePath,
+      error: f.errorMessage,
+      stack: f.stack.split('\n').slice(0, 30).join('\n'),
+      retries: f.retries,
+    })),
+    allTests: allTests.map(t => ({
+      name: t.title,
+      file: t.file,
+      status: t.ok ? 'passed' : (t.status === 'flaky' ? 'flaky' : 'failed'),
+      durationMs: t.duration,
+    })),
+  };
+}
+
+/**
+ * Parse only failures with full details.
+ */
+export function parseFailuresOnly(runResult) {
+  const results = runResult.results;
+  if (!results) {
+    return {
+      runId: runResult.id,
+      status: runResult.status,
+      message: 'No detailed results available',
+    };
+  }
+
+  const failures = extractFailures(results);
+  return {
+    runId: runResult.id,
+    status: runResult.status,
+    failureCount: failures.length,
+    failures: failures.map(f => ({
+      name: f.title,
+      file: f.file,
+      line: f.line,
+      suitePath: f.suitePath,
+      error: f.errorMessage,
+      stack: f.stack.split('\n').slice(0, 30).join('\n'),
+      retries: f.retries,
+    })),
+  };
+}
+
+/**
+ * Read the latest results.json from disk.
+ */
+export function readLatestResults() {
+  try {
+    if (fs.existsSync(RESULTS_FILE)) {
+      return JSON.parse(fs.readFileSync(RESULTS_FILE, 'utf8'));
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+/**
+ * Read test history from disk.
+ */
+export function readHistory(limit = 20) {
+  try {
+    if (fs.existsSync(HISTORY_FILE)) {
+      const data = JSON.parse(fs.readFileSync(HISTORY_FILE, 'utf8'));
+      return data.slice(0, limit);
+    }
+  } catch { /* ignore */ }
+  return [];
+}
+
+/**
+ * Find a specific run from history by ID.
+ */
+export function findRunById(runId) {
+  const history = readHistory(50);
+  return history.find(r => r.id === runId) || null;
+}