feat(@angular/cli): add 'test' and 'e2e' MCP tools

amishne · amishne · commit c61bfb9f9ec9 · 2025-12-08T14:53:21.000-08:00
This adds new tools for running unit and end-to-end tests via the MCP server.
diff --git a/packages/angular/cli/src/commands/mcp/mcp-server.ts b/packages/angular/cli/src/commands/mcp/mcp-server.ts
@@ -20,10 +20,12 @@ import { DEVSERVER_START_TOOL } from './tools/devserver/devserver-start';
 import { DEVSERVER_STOP_TOOL } from './tools/devserver/devserver-stop';
 import { DEVSERVER_WAIT_FOR_BUILD_TOOL } from './tools/devserver/devserver-wait-for-build';
 import { DOC_SEARCH_TOOL } from './tools/doc-search';
+import { E2E_TOOL } from './tools/e2e';
 import { FIND_EXAMPLE_TOOL } from './tools/examples/index';
 import { MODERNIZE_TOOL } from './tools/modernize';
 import { ZONELESS_MIGRATION_TOOL } from './tools/onpush-zoneless-migration/zoneless-migration';
 import { LIST_PROJECTS_TOOL } from './tools/projects';
+import { TEST_TOOL } from './tools/test';
 import { type AnyMcpToolDeclaration, registerTools } from './tools/tool-registry';
 
 /**
@@ -48,7 +50,13 @@ const STABLE_TOOLS = [
  * The set of tools that are available but not enabled by default.
  * These tools are considered experimental and may have limitations.
  */
-export const EXPERIMENTAL_TOOLS = [BUILD_TOOL, MODERNIZE_TOOL, ...DEVSERVER_TOOLS] as const;
+export const EXPERIMENTAL_TOOLS = [
+  BUILD_TOOL,
+  E2E_TOOL,
+  MODERNIZE_TOOL,
+  TEST_TOOL,
+  ...DEVSERVER_TOOLS,
+] as const;
 
 /**
  * Experimental tools that are grouped together under a single name.
diff --git a/packages/angular/cli/src/commands/mcp/tools/e2e.ts b/packages/angular/cli/src/commands/mcp/tools/e2e.ts
@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { z } from 'zod';
+import { CommandError, type Host, LocalWorkspaceHost } from '../host';
+import { createStructuredContentOutput } from '../utils';
+import { type McpToolContext, type McpToolDeclaration, declareTool } from './tool-registry';
+
+const e2eStatusSchema = z.enum(['success', 'failure']);
+type E2eStatus = z.infer<typeof e2eStatusSchema>;
+
+const e2eToolInputSchema = z.object({
+  project: z
+    .string()
+    .optional()
+    .describe(
+      'Which project to test in a monorepo context. If not provided, tests the default project.',
+    ),
+});
+
+export type E2eToolInput = z.infer<typeof e2eToolInputSchema>;
+
+const e2eToolOutputSchema = z.object({
+  status: e2eStatusSchema.describe('E2E execution status.'),
+  logs: z.array(z.string()).optional().describe('Output logs from `ng e2e`.'),
+});
+
+export type E2eToolOutput = z.infer<typeof e2eToolOutputSchema>;
+
+export async function runE2e(input: E2eToolInput, host: Host, context: McpToolContext) {
+  const projectName = input.project;
+
+  if (context.workspace) {
+    let targetProject;
+    const projects = context.workspace.projects;
+
+    if (projectName) {
+      targetProject = projects.get(projectName);
+    } else {
+      // Try to find default project
+      const defaultProjectName = context.workspace.extensions['defaultProject'] as
+        | string
+        | undefined;
+      if (defaultProjectName) {
+        targetProject = projects.get(defaultProjectName);
+      } else if (projects.size === 1) {
+        targetProject = Array.from(projects.values())[0];
+      }
+    }
+
+    if (targetProject) {
+      if (!targetProject.targets.has('e2e')) {
+        return createStructuredContentOutput({
+          status: 'failure',
+          logs: [
+            `No e2e target is defined for project '${projectName ?? 'default'}'. Please setup e2e testing first.`,
+          ],
+        });
+      }
+    }
+  }
+
+  // Build "ng"'s command line.
+  const args = ['e2e'];
+  if (input.project) {
+    args.push(input.project);
+  }
+
+  let status: E2eStatus = 'success';
+  let logs: string[] = [];
+
+  try {
+    logs = (await host.runCommand('ng', args)).logs;
+  } catch (e) {
+    status = 'failure';
+    if (e instanceof CommandError) {
+      logs = e.logs;
+    } else if (e instanceof Error) {
+      logs = [e.message];
+    } else {
+      logs = [String(e)];
+    }
+  }
+
+  const structuredContent: E2eToolOutput = {
+    status,
+    logs,
+  };
+
+  return createStructuredContentOutput(structuredContent);
+}
+
+export const E2E_TOOL: McpToolDeclaration<
+  typeof e2eToolInputSchema.shape,
+  typeof e2eToolOutputSchema.shape
+> = declareTool({
+  name: 'e2e',
+  title: 'E2E Tool',
+  description: `
+<Purpose>
+Perform an end-to-end test with ng e2e.
+</Purpose>
+<Use Cases>
+* Running end-to-end tests for the project.
+</Use Cases>
+<Operational Notes>
+* This tool runs "ng e2e".
+* It will error if no "e2e" target is defined in the project, to avoid interactive setup prompts.
+</Operational Notes>
+`,
+  isReadOnly: false,
+  isLocalOnly: true,
+  inputSchema: e2eToolInputSchema.shape,
+  outputSchema: e2eToolOutputSchema.shape,
+  factory: (context) => (input) => runE2e(input, LocalWorkspaceHost, context),
+});
diff --git a/packages/angular/cli/src/commands/mcp/tools/e2e_spec.ts b/packages/angular/cli/src/commands/mcp/tools/e2e_spec.ts
@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { workspaces } from '@angular-devkit/core';
+import { AngularWorkspace } from '../../../utilities/config';
+import { CommandError, Host } from '../host';
+import type { MockHost } from '../testing/mock-host';
+import { runE2e } from './e2e';
+import type { McpToolContext } from './tool-registry';
+
+describe('E2E Tool', () => {
+  let mockHost: MockHost;
+  let mockContext: McpToolContext;
+  let mockProjects: workspaces.ProjectDefinitionCollection;
+  let mockWorkspace: AngularWorkspace;
+
+  beforeEach(() => {
+    mockHost = {
+      runCommand: jasmine.createSpy<Host['runCommand']>('runCommand').and.resolveTo({ logs: [] }),
+    } as unknown as MockHost;
+
+    mockProjects = new workspaces.ProjectDefinitionCollection();
+    const mockWorkspaceDefinition: workspaces.WorkspaceDefinition = {
+      projects: mockProjects,
+      extensions: {},
+    };
+
+    mockWorkspace = new AngularWorkspace(mockWorkspaceDefinition, '/test/angular.json');
+    mockContext = {
+      workspace: mockWorkspace,
+    } as McpToolContext;
+  });
+
+  function addProject(name: string, targets: Record<string, workspaces.TargetDefinition> = {}) {
+    mockProjects.set(name, {
+      root: `projects/${name}`,
+      extensions: {},
+      targets: new workspaces.TargetDefinitionCollection(targets),
+    });
+  }
+
+  it('should construct the command correctly with defaults', async () => {
+    await runE2e({}, mockHost, mockContext);
+    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', ['e2e']);
+  });
+
+  it('should construct the command correctly with a specified project', async () => {
+    addProject('my-app', { e2e: { builder: 'mock-builder' } });
+
+    await runE2e({ project: 'my-app' }, mockHost, mockContext);
+    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', ['e2e', 'my-app']);
+  });
+
+  it('should error if project does not have e2e target', async () => {
+    addProject('my-app', { build: { builder: 'mock-builder' } });
+
+    const { structuredContent } = await runE2e({ project: 'my-app' }, mockHost, mockContext);
+
+    expect(structuredContent.status).toBe('failure');
+    expect(structuredContent.logs?.[0]).toContain("No e2e target is defined for project 'my-app'");
+    expect(mockHost.runCommand).not.toHaveBeenCalled();
+  });
+
+  it('should error if default project does not have e2e target and no project specified', async () => {
+    mockWorkspace.extensions['defaultProject'] = 'my-app';
+    addProject('my-app', { build: { builder: 'mock-builder' } });
+
+    const { structuredContent } = await runE2e({}, mockHost, mockContext);
+
+    expect(structuredContent.status).toBe('failure');
+    expect(structuredContent.logs?.[0]).toContain("No e2e target is defined for project 'default'");
+    expect(mockHost.runCommand).not.toHaveBeenCalled();
+  });
+
+  it('should proceed if no workspace context is available (fallback)', async () => {
+    // If context.workspace is undefined, it should try to run ng e2e (which might fail or prompt, but tool runs it)
+    const noWorkspaceContext = {} as McpToolContext;
+    await runE2e({}, mockHost, noWorkspaceContext);
+    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', ['e2e']);
+  });
+
+  it('should handle a successful e2e run', async () => {
+    addProject('my-app', { e2e: { builder: 'mock-builder' } });
+    const e2eLogs = ['E2E passed'];
+    mockHost.runCommand.and.resolveTo({ logs: e2eLogs });
+
+    const { structuredContent } = await runE2e({ project: 'my-app' }, mockHost, mockContext);
+
+    expect(structuredContent.status).toBe('success');
+    expect(structuredContent.logs).toEqual(e2eLogs);
+  });
+
+  it('should handle a failed e2e run', async () => {
+    addProject('my-app', { e2e: { builder: 'mock-builder' } });
+    const e2eLogs = ['E2E failed'];
+    mockHost.runCommand.and.rejectWith(new CommandError('Failed', e2eLogs, 1));
+
+    const { structuredContent } = await runE2e({ project: 'my-app' }, mockHost, mockContext);
+
+    expect(structuredContent.status).toBe('failure');
+    expect(structuredContent.logs).toEqual(e2eLogs);
+  });
+});
diff --git a/packages/angular/cli/src/commands/mcp/tools/test.ts b/packages/angular/cli/src/commands/mcp/tools/test.ts
@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { z } from 'zod';
+import { CommandError, type Host, LocalWorkspaceHost } from '../host';
+import { createStructuredContentOutput } from '../utils';
+import { type McpToolDeclaration, declareTool } from './tool-registry';
+
+const testStatusSchema = z.enum(['success', 'failure']);
+type TestStatus = z.infer<typeof testStatusSchema>;
+
+const testToolInputSchema = z.object({
+  project: z
+    .string()
+    .optional()
+    .describe('Which project to test in a monorepo context. If not provided, tests all projects.'),
+  filter: z.string().optional().describe('Filter the executed tests by spec name.'),
+});
+
+export type TestToolInput = z.infer<typeof testToolInputSchema>;
+
+const testToolOutputSchema = z.object({
+  status: testStatusSchema.describe('Test execution status.'),
+  logs: z.array(z.string()).optional().describe('Output logs from `ng test`.'),
+});
+
+export type TestToolOutput = z.infer<typeof testToolOutputSchema>;
+
+export async function runTest(input: TestToolInput, host: Host) {
+  // Build "ng"'s command line.
+  const args = ['test'];
+  if (input.project) {
+    args.push(input.project);
+  }
+
+  // This is ran by the agent so we want a non-watched, headless test.
+  args.push('--browsers', 'ChromeHeadless');
+  args.push('--watch', 'false');
+
+  if (input.filter) {
+    args.push('--filter', input.filter);
+  }
+
+  let status: TestStatus = 'success';
+  let logs: string[] = [];
+
+  try {
+    logs = (await host.runCommand('ng', args)).logs;
+  } catch (e) {
+    status = 'failure';
+    if (e instanceof CommandError) {
+      logs = e.logs;
+    } else if (e instanceof Error) {
+      logs = [e.message];
+    } else {
+      logs = [String(e)];
+    }
+  }
+
+  const structuredContent: TestToolOutput = {
+    status,
+    logs,
+  };
+
+  return createStructuredContentOutput(structuredContent);
+}
+
+export const TEST_TOOL: McpToolDeclaration<
+  typeof testToolInputSchema.shape,
+  typeof testToolOutputSchema.shape
+> = declareTool({
+  name: 'test',
+  title: 'Test Tool',
+  description: `
+<Purpose>
+Perform a one-off, non-watched unit test execution with ng test.
+</Purpose>
+<Use Cases>
+* Running unit tests for the project.
+* Verifying code changes with tests.
+</Use Cases>
+<Operational Notes>
+* This tool runs "ng test" with "--watch false".
+* It supports filtering by spec name if the underlying builder supports it (e.g., 'unit-test' builder).
+</Operational Notes>
+`,
+  isReadOnly: false,
+  isLocalOnly: true,
+  inputSchema: testToolInputSchema.shape,
+  outputSchema: testToolOutputSchema.shape,
+  factory: () => (input) => runTest(input, LocalWorkspaceHost),
+});
diff --git a/packages/angular/cli/src/commands/mcp/tools/test_spec.ts b/packages/angular/cli/src/commands/mcp/tools/test_spec.ts
