feat: add vitest test runner with fixture loader and mock activation

Configures vitest as the primary test runner for the v6 Local Testing
& Simulation Framework (Phase 47: Mock Infrastructure, issue #249).

Changes:
- package.json: add vitest ^2.0.0 devDependency; npm test → vitest run;
  npm run test:watch → vitest; npm run test:node preserves existing
  node --test runner for .test.cjs files
- vitest.config.js: node environment, setupFiles: ['./test/setup.js'],
  includes .test.js/.spec.js, excludes .test.cjs (node:test incompatible)
- test/setup.js: auto-activates mock-github and mock-gsd-agent in
  beforeEach/afterEach; conditional require — works when PRs #258/#259
  are not yet merged to main; exports mockGitHub/mockGsdAgent
- test/loadFixture.js: loadFixture(name) helper that reads from
  test/fixtures/; supports namespaced paths (e.g. 'github/issue-view');
  throws descriptive errors on missing/invalid fixtures

Closes #249

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Author: 2 people

package.json

@@ -16,7 +16,9 @@
   "scripts": {
     "build": "pkgroll --clean-dist --src .",
     "dev": "pkgroll --watch --src .",
-    "test": "node --test test/*.test.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:node": "node --test test/*.test.cjs",
     "lint": "eslint lib/ bin/ test/",
     "prepublishOnly": "npm run build",
     "completions": "node bin/generate-completions.cjs",
@@ -31,7 +33,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.0.2",
-    "pkgroll": "^2.26.3"
+    "pkgroll": "^2.26.3",
+    "vitest": "^2.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

test/loadFixture.js

@@ -0,0 +1,65 @@
+/**
+ * test/loadFixture.js — Fixture loader helper
+ *
+ * Loads JSON fixture files from test/fixtures/.
+ *
+ * Usage:
+ *
+ *   import { loadFixture } from './loadFixture.js';
+ *
+ *   const issueData = loadFixture('github/issue-view');
+ *   const plannerOutput = loadFixture('agents/gsd-planner');
+ *
+ * Fixture file resolution:
+ *   loadFixture('github/issue-view')  →  test/fixtures/github/issue-view.json
+ *   loadFixture('agents/gsd-planner') →  test/fixtures/agents/gsd-planner.json
+ *   loadFixture('my-fixture')         →  test/fixtures/my-fixture.json
+ *
+ * @param {string} name - Fixture name, optionally prefixed with subdirectory.
+ *   Forward slashes are used as path separators (platform-independent).
+ * @returns {unknown} Parsed JSON content of the fixture file.
+ * @throws {Error} if the fixture file is not found.
+ * @throws {Error} if the fixture file contains invalid JSON.
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the test/fixtures/ directory.
+ * All fixture names are resolved relative to this directory.
+ */
+export const FIXTURES_DIR = path.resolve(__dirname, 'fixtures');
+
+/**
+ * Load a fixture by name and return its parsed JSON content.
+ *
+ * @param {string} name - Fixture identifier, e.g. 'github/issue-view' or 'agents/gsd-planner'
+ * @returns {unknown} Parsed JSON value — may be an object, array, string, number, or boolean.
+ */
+export function loadFixture(name) {
+  // Normalize forward slashes to platform path separator
+  const normalizedName = name.split('/').join(path.sep);
+  const fixturePath = path.resolve(FIXTURES_DIR, `${normalizedName}.json`);
+
+  if (!fs.existsSync(fixturePath)) {
+    throw new Error(
+      `loadFixture: fixture not found: "${name}"\n` +
+      `  Looked for: ${fixturePath}\n` +
+      `  Fixtures directory: ${FIXTURES_DIR}`
+    );
+  }
+
+  const raw = fs.readFileSync(fixturePath, 'utf-8').trim();
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `loadFixture: fixture "${name}" is not valid JSON (${fixturePath}): ${err.message}`
+    );
+  }
+}

test/setup.js

@@ -0,0 +1,88 @@
+/**
+ * test/setup.js — Vitest global setup
+ *
+ * Auto-activates mock-github and mock-gsd-agent before each test, and
+ * deactivates them after. Both mocks are conditionally required — the
+ * setup works correctly even when lib/mock-github.cjs or
+ * lib/mock-gsd-agent.cjs are not yet present (e.g., when PRs #258 and
+ * #259 are not yet merged to main).
+ *
+ * To use mocks in a vitest test file:
+ *
+ *   import { mockGitHub, mockGsdAgent } from './setup.js';
+ *
+ *   test('my test', () => {
+ *     // mocks are already active (activated in beforeEach)
+ *     mockGitHub.setResponse('gh issue view', '{"number":999}');
+ *     // ...
+ *   });
+ *
+ * To use a scenario:
+ *
+ *   import { mockGitHub } from './setup.js';
+ *
+ *   beforeEach(() => {
+ *     // Override the global beforeEach activation with a scenario
+ *     mockGitHub.deactivate();
+ *     mockGitHub.activate('pr-error');
+ *   });
+ */
+
+import { beforeEach, afterEach } from 'vitest';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Conditional mock loading
+// ---------------------------------------------------------------------------
+
+// Conditionally load mock-github — gracefully skip if not present
+// (lib/mock-github.cjs lands via PR #258)
+let mockGitHub = null;
+try {
+  mockGitHub = require(path.join(repoRoot, 'lib', 'mock-github.cjs'));
+} catch (_e) {
+  // mock-github.cjs not available — tests run without GitHub API interception
+}
+
+// Conditionally load mock-gsd-agent — gracefully skip if not present
+// (lib/mock-gsd-agent.cjs lands via PR #259)
+let mockGsdAgent = null;
+try {
+  mockGsdAgent = require(path.join(repoRoot, 'lib', 'mock-gsd-agent.cjs'));
+} catch (_e) {
+  // mock-gsd-agent.cjs not available — tests run without agent spawn interception
+}
+
+// ---------------------------------------------------------------------------
+// Auto-activate hooks
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  if (mockGitHub && typeof mockGitHub.activate === 'function') {
+    mockGitHub.activate();
+  }
+  if (mockGsdAgent && typeof mockGsdAgent.activate === 'function') {
+    mockGsdAgent.activate();
+  }
+});
+
+afterEach(() => {
+  if (mockGitHub && typeof mockGitHub.deactivate === 'function') {
+    mockGitHub.deactivate();
+  }
+  if (mockGsdAgent && typeof mockGsdAgent.deactivate === 'function') {
+    mockGsdAgent.deactivate();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Exports — available for test files that need direct mock access
+// ---------------------------------------------------------------------------
+
+export { mockGitHub, mockGsdAgent };

vitest.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    setupFiles: ['./test/setup.js'],
+    // Target .test.js and .spec.js files for vitest
+    // Exclude .test.cjs files — those use node:test (run via npm run test:node)
+    include: ['test/**/*.{test,spec}.{js,mjs}'],
+    exclude: ['test/**/*.test.cjs'],
+  },
+});