run_tests

Instructions

Implementation Reference

• src/managers/DevLifecycleManager.ts:134-208 (handler)

  Core implementation of runTests: resolves service path, invokes npm test with --json output, parses Jest JSON results, and returns structured pass/fail counts with failure details.

  async function runTests(servicePath: string, pattern?: string): Promise<TestResult> {
    const absPath = resolveSafe(repoDir, servicePath);
    const outputFile = join(tmpdir(), `mcp-dev-jest-${Date.now()}.json`);
  
    const npmArgs = [
      'test',
      '--',
      '--forceExit',
      '--json',
      `--outputFile=${outputFile}`,
    ];
    if (pattern) npmArgs.push(`--testNamePattern=${pattern}`);
  
    await proc.run('npm', npmArgs, {
      cwd: absPath,
      timeout: 120_000,
      env: { CI: 'true' },
    });
  
    let jsonStr: string;
    try {
      jsonStr = await readFile(outputFile, 'utf8');
    } catch {
      return {
        success: false,
        passed: 0,
        failed: 0,
        skipped: 0,
        failures: [
          {
            suite: 'runner',
            test: 'startup',
            messages: ['Jest did not produce output. Check npm test script exists.'],
          },
        ],
      };
    } finally {
      await unlink(outputFile).catch(() => {});
    }
  
    let json: JestJsonOutput;
    try {
      json = JSON.parse(jsonStr) as JestJsonOutput;
    } catch {
      return {
        success: false,
        passed: 0,
        failed: 0,
        skipped: 0,
        failures: [{ suite: 'runner', test: 'parse', messages: ['Failed to parse Jest JSON output'] }],
      };
    }
  
    const failures: TestFailure[] = [];
    for (const suite of json.testResults) {
      const suiteName = relative(repoDir, suite.testFilePath);
      for (const t of suite.assertionResults) {
        if (t.status === 'failed') {
          failures.push({
            suite: suiteName,
            test: t.fullName,
            messages: t.failureMessages.map((m) => m.slice(0, 1_500)),
          });
        }
      }
    }
  
    return {
      success: json.numFailedTests === 0,
      passed: json.numPassedTests,
      failed: json.numFailedTests,
      skipped: json.numPendingTests,
      failures,
    };
  }

• src/tools/dev-lifecycle.tool.ts:13-23 (schema)

  Zod schema RunTestsSchema defining input parameters: servicePath (required string) and pattern (optional string for Jest test name pattern).

  export const RunTestsSchema = z.object({
    servicePath: z
      .string()
      .describe(
        'Relative path from repo root to the service to test. E.g. "ops/control-panel/server".',
      ),
    pattern: z
      .string()
      .optional()
      .describe('Optional Jest test name pattern to run a subset of tests.'),
  });

• src/tools/dev-lifecycle.tool.ts:54-64 (registration)

  Registration of 'run_tests' tool on the MCP server with schema and handler that delegates to manager.runTests().

  server.tool(
    'run_tests',
    'Run Jest tests for a service. Returns pass/fail counts and structured failure details with test names and error messages. Optionally scope to a test name pattern.',
    RunTestsSchema.shape,
    async (args) => {
      const result = await manager.runTests(args.servicePath, args.pattern);
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    },
  );

• src/managers/DevLifecycleManager.ts:88-100 (helper)

  JestJsonOutput interface used to parse the Jest --json output file for test results.

  interface JestJsonOutput {
    numPassedTests: number;
    numFailedTests: number;
    numPendingTests: number;
    testResults: Array<{
      testFilePath: string;
      assertionResults: Array<{
        status: string;
        fullName: string;
        failureMessages: string[];
      }>;
    }>;
  }

• src/managers/DevLifecycleManager.ts:32-38 (helper)

  TestResult and TestFailure interfaces defining the return type structure for runTests.

  export interface TestResult {
    success: boolean;
    passed: number;
    failed: number;
    skipped: number;
    failures: TestFailure[];
  }