feat: add apex/agent testing capabilities to MCP @W-18609330@

package.json

@@ -43,6 +43,7 @@
     "@modelcontextprotocol/sdk": "^1.12.3",
     "@oclif/core": "^4.3.3",
     "@salesforce/agents": "^0.15.2",
+    "@salesforce/apex-node": "^8.1.32",
     "@salesforce/core": "^8.14.0",
     "@salesforce/kit": "^3.1.6",
     "@salesforce/source-deploy-retrieve": "^12.20.1",

src/index.ts

@@ -22,12 +22,13 @@ import * as core from './tools/core/index.js';
 import * as orgs from './tools/orgs/index.js';
 import * as data from './tools/data/index.js';
 import * as users from './tools/users/index.js';
+import * as testing from './tools/testing/index.js';
 import * as metadata from './tools/metadata/index.js';
 import Cache from './shared/cache.js';
 import { Telemetry } from './telemetry.js';
 import { SfMcpServer } from './sf-mcp-server.js';
 
-const TOOLSETS = ['all', 'orgs', 'data', 'users', 'metadata'] as const;
+const TOOLSETS = ['all', 'testing', 'orgs', 'data', 'users', 'metadata'] as const;
 
 /**
  * Sanitizes an array of org usernames by replacing specific orgs with a placeholder.
@@ -193,6 +194,15 @@ You can also use special values to control access to orgs:
       users.registerToolAssignPermissionSet(server);
     }
 
+    // ************************
+    // testing TOOLS
+    // ************************
+    if (all || enabledToolsets.has('testing')) {
+      this.logToStderr('Registering testing tools');
+      testing.registerToolRunApexTest(server);
+      testing.registerToolRunAgentTest(server);
+    }
+
     // ************************
     // METADATA TOOLS
     // ************************

src/tools/testing/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './sf-run-apex-tests.js';
+export * from './sf-run-agent-tests.js';

src/tools/testing/sf-run-agent-tests.ts

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import { AgentTester } from '@salesforce/agents';
+import { Duration } from '@salesforce/kit';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+import { textResponse } from '../../shared/utils.js';
+import { getConnection } from '../../shared/auth.js';
+import { SfMcpServer } from '../../sf-mcp-server.js';
+
+const runAgentTestsParam = z.object({
+  agentApiName: z.string().describe(
+    `Agent test to run
+            if unsure, list all files matching the pattern *.aiEvaluationDefinition-meta.xml
+            only one test can be executed at a time
+`
+  ),
+  usernameOrAlias: usernameOrAliasParam,
+  directory: directoryParam,
+});
+
+export type AgentRunTests = z.infer<typeof runAgentTestsParam>;
+
+/*
+ * Run Agent tests in a Salesforce org.
+ *
+ * Parameters:
+ * - agentApiName: this will be the aiEvaluationDefinition's name
+ * - usernameOrAlias: Username or alias of the Salesforce org to run tests in.
+ * - directory: Directory of the local project.
+ *
+ * Returns:
+ * - textResponse: Test result.
+ */
+export const registerToolRunAgentTest = (server: SfMcpServer): void => {
+  server.tool(
+    'sf-run-agent-tests',
+    `Run Agent tests in an org. 
+
+AGENT INSTRUCTIONS:
+If the user doesn't specify what to test, take context from the currently open file
+This will ONLY run Agent tests, NOT apex tests, lightning tests, flow tests, or any other type of test.
+
+this should be chosen when a file in the 'aiEvaluationDefinitions' directory is mentioned
+
+EXAMPLE USAGE:
+Run tests for the X agent
+Run this test
+`,
+    runAgentTestsParam.shape,
+    async ({ usernameOrAlias, agentApiName, directory }) => {
+      if (!usernameOrAlias)
+        return textResponse(
+          'The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool',
+          true
+        );
+
+      // needed for org allowlist to work
+      process.chdir(directory);
+      const connection = await getConnection(usernameOrAlias);
+
+      try {
+        const agentTester = new AgentTester(connection);
+        const test = await agentTester.start(agentApiName);
+        const result = await agentTester.poll(test.runId, { timeout: Duration.minutes(10) });
+        return textResponse(`Test result: ${JSON.stringify(result)}`);
+      } catch (e) {
+        return textResponse(`Failed to run Agent Tests: ${e instanceof Error ? e.message : 'Unknown error'}`, true);
+      }
+    }
+  );
+};

src/tools/testing/sf-run-apex-tests.ts

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { z } from 'zod';
+import { TestLevel, TestResult, TestService } from '@salesforce/apex-node';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+import { textResponse } from '../../shared/utils.js';
+import { getConnection } from '../../shared/auth.js';
+import { SfMcpServer } from '../../sf-mcp-server.js';
+
+const runApexTestsParam = z.object({
+  testLevel: z.enum([TestLevel.RunLocalTests, TestLevel.RunAllTestsInOrg, TestLevel.RunSpecifiedTests]).describe(
+    `Apex test level
+
+AGENT INSTRUCTIONS
+Choose the correct value based on what tests are meant to be executed in some of these ways:
+
+RunLocalTests="Run all tests in the org, except the ones that originate from installed managed and unlocked packages."
+RunAllTestsInOrg="Run all tests in the org, including tests of managed packages"
+RunSpecifiedTests="Run the Apex tests I specify, these will be specified in the classNames parameter"
+`
+  ),
+  classNames: z.array(z.string()).describe(
+    `Apex tests classes to run.
+            if Running all tests, all tests should be listed
+            if unsure, find apex classes matching the pattern *.cls, that include the @isTest decorator in the file and then join their test names together with ','
+`
+  ),
+  usernameOrAlias: usernameOrAliasParam,
+  directory: directoryParam,
+});
+
+export type ApexRunTests = z.infer<typeof runApexTestsParam>;
+
+/*
+ * Run Apex tests in a Salesforce org.
+ *
+ * Parameters:
+ * - testLevel: 'RunSpecifiedTests', 'RunLocalTests', 'RunAllTestsInOrg', used to specify the specific test-level.
+ * - classNames: if testLevel='RunSpecifiedTests', this will be the specified tests to run
+ * - usernameOrAlias: Username or alias of the Salesforce org to run tests in.
+ * - directory: Directory of the local project.
+ *
+ * Returns:
+ * - textResponse: Test result.
+ */
+export const registerToolRunApexTest = (server: SfMcpServer): void => {
+  server.tool(
+    'sf-run-apex-tests',
+    `Run Apex tests in an org. 
+
+AGENT INSTRUCTIONS:
+If the user doesn't specify what to test, take context from the currently open file
+This will ONLY run APEX tests, NOT agent tests, lightning tests, flow tests, or any other type of test.
+
+this should be chosen when a file in the 'classes' directory is mentioned
+
+EXAMPLE USAGE:
+Run tests A, B, C.
+Run the tests, find apex classes matching the pattern *.cls, that include the @isTest decorator in the file and then join their test names together with ','
+Run all tests in the org.
+`,
+    runApexTestsParam.shape,
+    async ({ testLevel, usernameOrAlias, classNames, directory }) => {
+      if (testLevel !== TestLevel.RunSpecifiedTests && classNames?.length && classNames?.length >= 1) {
+        return textResponse("You can't specify which tests to run without setting testLevel='RunSpecifiedTests'", true);
+      }
+
+      if (!usernameOrAlias)
+        return textResponse(
+          'The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool',
+          true
+        );
+
+      // needed for org allowlist to work
+      process.chdir(directory);
+
+      const connection = await getConnection(usernameOrAlias);
+      try {
+        const testService = new TestService(connection);
+
+        const payload = await testService.buildAsyncPayload(testLevel, classNames.join(','));
+        const result = (await testService.runTestAsynchronous(payload, false)) as TestResult;
+        return textResponse(`Test result: ${JSON.stringify(result)}`);
+      } catch (e) {
+        return textResponse(`Failed to run Apex Tests: ${e instanceof Error ? e.message : 'Unknown error'}`, true);
+      }
+    }
+  );
+};