Specter MCP

Instructions

Implementation Reference

• src/tools/testing/run-unit-tests.ts:48-82 (handler)

  Main handler function for the 'run_unit_tests' MCP tool. It destructures arguments, validates the platform, and delegates to platform-specific test execution functions (runAndroidTests or runIOSTests).

  export async function runUnitTests(args: RunUnitTestsArgs): Promise<RunUnitTestsResult> {
    const {
      platform,
      projectPath,
      sourceSet = 'test',
      testClass,
      testMethod,
      module = '',
      timeoutMs = 300000,
    } = args;
  
    // Validate platform
    if (!isPlatform(platform)) {
      throw Errors.invalidArguments(`Invalid platform: ${platform}. Must be 'android' or 'ios'`);
    }
  
    if (platform === 'android') {
      return runAndroidTests({
        projectPath,
        sourceSet,
        testClass,
        testMethod,
        module,
        timeoutMs,
      });
    } else {
      return runIOSTests({
        projectPath,
        sourceSet,
        testClass,
        testMethod,
        timeoutMs,
      });
    }
  }

• src/tools/testing/run-unit-tests.ts:16-43 (schema)

  TypeScript interfaces defining the input arguments (RunUnitTestsArgs) and output result structure (RunUnitTestsResult) for the run_unit_tests tool.

  export interface RunUnitTestsArgs {
    /** Target platform */
    platform: string;
    /** Project root directory */
    projectPath: string;
    /** Source set (commonTest, androidTest, iosTest) */
    sourceSet?: string;
    /** Specific test class to run */
    testClass?: string;
    /** Specific test method to run */
    testMethod?: string;
    /** Gradle module for KMM projects */
    module?: string;
    /** Timeout in milliseconds */
    timeoutMs?: number;
  }
  
  /**
   * Result structure for run_unit_tests
   */
  export interface RunUnitTestsResult {
    /** Test execution result */
    result: TestResult;
    /** Human-readable summary */
    summary: string;
    /** Extracted failures with suggestions */
    failures: ReturnType<typeof extractTestFailures>;
  }

• src/tools/testing/run-unit-tests.ts:158-201 (registration)

  The registration function for the 'run_unit_tests' tool. It registers the tool with the global ToolRegistry, providing the tool name, description, detailed input JSON schema, and the handler function.

  export function registerRunUnitTestsTool(): void {
    getToolRegistry().register(
      'run_unit_tests',
      {
        description:
          'Run unit tests for Android or iOS. Returns structured test results with pass/fail status and failure details.',
        inputSchema: createInputSchema(
          {
            platform: {
              type: 'string',
              enum: ['android', 'ios'],
              description: 'Target platform',
            },
            projectPath: {
              type: 'string',
              description: 'Path to the project root directory',
            },
            sourceSet: {
              type: 'string',
              description: 'Source set to test (test, commonTest, androidTest, iosTest)',
            },
            testClass: {
              type: 'string',
              description: 'Specific test class to run (optional)',
            },
            testMethod: {
              type: 'string',
              description: 'Specific test method to run (requires testClass)',
            },
            module: {
              type: 'string',
              description: 'Gradle module for KMM projects (e.g., :shared)',
            },
            timeoutMs: {
              type: 'number',
              description: 'Timeout in milliseconds (default: 300000)',
            },
          },
          ['platform', 'projectPath']
        ),
      },
      (args) => runUnitTests(args as unknown as RunUnitTestsArgs)
    );
  }

• src/tools/testing/run-unit-tests.ts:87-115 (helper)

  Helper function implementing Android unit test execution via Gradle. Checks ADB availability for instrumentation tests, runs tests, processes results into summary and failures.

  async function runAndroidTests(options: {
    projectPath: string;
    sourceSet: string;
    testClass?: string;
    testMethod?: string;
    module: string;
    timeoutMs: number;
  }): Promise<RunUnitTestsResult> {
    // Check if ADB is available
    const adbAvailable = await isAdbAvailable();
    if (!adbAvailable && options.sourceSet === 'androidTest') {
      throw Errors.platformUnavailable('android');
    }
  
    const testOptions: TestRunOptions = {
      projectPath: options.projectPath,
      sourceSet: options.sourceSet,
      testClass: options.testClass,
      testMethod: options.testMethod,
      module: options.module,
      timeoutMs: options.timeoutMs,
    };
  
    const result = await runGradleTests(testOptions);
    const summary = createTestSummary(result);
    const failures = extractTestFailures(result);
  
    return { result, summary, failures };
  }

• src/tools/register.ts:138-142 (registration)

  Invocation of the tool registration during central registerAllTools() call in server startup, ensuring the tool is registered in the global registry.

  const { registerRunUnitTestsTool } = await import('./testing/run-unit-tests.js');
  const { registerRunMaestroFlowTool } = await import('./testing/run-maestro-flow.js');
  const { registerRunLinterTool } = await import('./testing/run-linter.js');
  
  registerRunUnitTestsTool();