Feat: Add listTestRuns and updateTestRun utilities with corresponding schemas and tests

Author: ruturaj-browserstack

src/tools/testmanagement-utils/list-testruns.ts

@@ -0,0 +1,77 @@
+import axios from "axios";
+import config from "../../config";
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { formatAxiosError } from "../../lib/error";
+
+/**
+ * Schema for listing test runs with optional filters.
+ */
+export const ListTestRunsSchema = z.object({
+  project_identifier: z
+    .string()
+    .describe(
+      "Identifier of the project to fetch test runs from (e.g., PR-12345)",
+    ),
+  run_state: z
+    .string()
+    .optional()
+    .describe("Return all test runs with this state (comma-separated)"),
+});
+
+type ListTestRunsArgs = z.infer<typeof ListTestRunsSchema>;
+
+/**
+ * Fetches and formats the list of test runs for a project.
+ */
+export async function listTestRuns(
+  args: ListTestRunsArgs,
+): Promise<CallToolResult> {
+  try {
+    const params = new URLSearchParams();
+    if (args.run_state) {
+      params.set("run_state", args.run_state);
+    }
+
+    const url =
+      `https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(
+        args.project_identifier,
+      )}/test-runs?` + params.toString();
+
+    const resp = await axios.get(url, {
+      auth: {
+        username: config.browserstackUsername,
+        password: config.browserstackAccessKey,
+      },
+    });
+
+    const data = resp.data;
+    if (!data.success) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to list test runs: ${JSON.stringify(data)}`,
+            isError: true,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const runs = data.test_runs;
+    const count = runs.length;
+    const summary = runs
+      .map((tr: any) => `• ${tr.identifier}: ${tr.name} [${tr.run_state}]`)
+      .join("\n");
+
+    return {
+      content: [
+        { type: "text", text: `Found ${count} test run(s):\n\n${summary}` },
+        { type: "text", text: JSON.stringify(runs, null, 2) },
+      ],
+    };
+  } catch (err) {
+    return formatAxiosError(err, "Failed to list test runs");
+  }
+}

src/tools/testmanagement-utils/update-testrun.ts

@@ -0,0 +1,78 @@
+import axios from "axios";
+import config from "../../config";
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { formatAxiosError } from "../../lib/error";
+
+/**
+ * Schema for updating a test run with partial fields.
+ */
+export const UpdateTestRunSchema = z.object({
+  project_identifier: z
+    .string()
+    .describe("Project identifier (e.g., PR-12345)"),
+  test_run_id: z.string().describe("Test run identifier (e.g., TR-678)"),
+  test_run: z.object({
+    name: z.string().optional().describe("New name of the test run"),
+    run_state: z
+      .enum([
+        "new_run",
+        "in_progress",
+        "under_review",
+        "rejected",
+        "done",
+        "closed",
+      ])
+      .optional()
+      .describe("Updated state of the test run"),
+  }),
+});
+
+type UpdateTestRunArgs = z.infer<typeof UpdateTestRunSchema>;
+
+/**
+ * Partially updates an existing test run.
+ */
+export async function updateTestRun(
+  args: UpdateTestRunArgs,
+): Promise<CallToolResult> {
+  try {
+    const body = { test_run: args.test_run };
+    const url = `https://test-management.browserstack.com/api/v2/projects/${encodeURIComponent(
+      args.project_identifier,
+    )}/test-runs/${encodeURIComponent(args.test_run_id)}/update`;
+
+    const resp = await axios.patch(url, body, {
+      auth: {
+        username: config.browserstackUsername,
+        password: config.browserstackAccessKey,
+      },
+    });
+
+    const data = resp.data;
+    if (!data.success) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to update test run: ${JSON.stringify(data)}`,
+            isError: true,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Successfully updated test run ${args.test_run_id}`,
+        },
+        { type: "text", text: JSON.stringify(data.testrun || data, null, 2) },
+      ],
+    };
+  } catch (err) {
+    return formatAxiosError(err, "Failed to update test run");
+  }
+}

src/tools/testmanagement.ts

@@ -22,6 +22,16 @@ import {
   createTestRun,
 } from "./testmanagement-utils/create-testrun";
 
+import {
+  ListTestRunsSchema,
+  listTestRuns,
+} from "./testmanagement-utils/list-testruns";
+
+import {
+  UpdateTestRunSchema,
+  updateTestRun,
+} from "./testmanagement-utils/update-testrun";
+
 /**
  * Wrapper to call createProjectOrFolder util.
  */
@@ -98,7 +108,6 @@ export async function listTestCasesTool(
 }
 
 /**
- * CREATE TEST RUN
  * Creates a test run in BrowserStack Test Management.
  */
 export async function createTestRunTool(
@@ -122,6 +131,56 @@ export async function createTestRunTool(
   }
 }
 
+/**
+ * Lists test runs in a project with optional filters (date ranges, assignee, state, etc.)
+ */
+export async function listTestRunsTool(
+  args: z.infer<typeof ListTestRunsSchema>,
+): Promise<CallToolResult> {
+  try {
+    return await listTestRuns(args);
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Failed to list test runs: ${
+            err instanceof Error ? err.message : "Unknown error"
+          }. Please open an issue on GitHub if the problem persists`,
+          isError: true,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+/**
+ * Updates a test run in BrowserStack Test Management.
+ * This function allows for partial updates to an existing test run.
+ * It takes the project identifier and test run ID as parameters.
+ */
+export async function updateTestRunTool(
+  args: z.infer<typeof UpdateTestRunSchema>,
+): Promise<CallToolResult> {
+  try {
+    return await updateTestRun(args);
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Failed to update test run: ${
+            err instanceof Error ? err.message : "Unknown error"
+          }. Please open an issue on GitHub if the problem persists`,
+          isError: true,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
 /**
  * Registers both project/folder and test-case tools.
  */
@@ -153,4 +212,17 @@ export default function addTestManagementTools(server: McpServer) {
     CreateTestRunSchema.shape,
     createTestRunTool,
   );
+
+  server.tool(
+    "listTestRuns",
+    "List test runs in a project with optional filters (date ranges, assignee, state, etc.)",
+    ListTestRunsSchema.shape,
+    listTestRunsTool,
+  );
+  server.tool(
+    "updateTestRun",
+    "Update a test run in BrowserStack Test Management.",
+    UpdateTestRunSchema.shape,
+    updateTestRunTool,
+  );
 }

tests/tools/testmanagement.test.ts

@@ -1,6 +1,6 @@
 import { createProjectOrFolderTool } from '../../src/tools/testmanagement';
 import { createProjectOrFolder } from '../../src/tools/testmanagement-utils/create-project-folder';
-import { createTestCaseTool , createTestRunTool} from '../../src/tools/testmanagement';
+import { createTestCaseTool , createTestRunTool } from '../../src/tools/testmanagement';
 import { createTestCase, sanitizeArgs, TestCaseCreateRequest } from '../../src/tools/testmanagement-utils/create-testcase';
 import axios from 'axios';
 import { listTestCases } from '../../src/tools/testmanagement-utils/list-testcases';
@@ -28,7 +28,6 @@ jest.mock('../../src/config', () => ({
 }));
 jest.mock('../../src/tools/testmanagement-utils/create-testrun', () => ({
   createTestRun: jest.fn(),
-  // if you’re parsing args the same way as in the others, you can include the schema mock too:
   CreateTestRunSchema: {
     parse: (args: any) => args,
     shape: {},
@@ -197,7 +196,7 @@ describe('listTestCases util', () => {
   });
 });
 
-describe('createTestRunTool', () => {                                             
+describe('createTestRunTool', () => {
   beforeEach(() => {
     jest.clearAllMocks();
   });
@@ -242,3 +241,97 @@ describe('createTestRunTool', () => {
     expect(result.content[0].text).toContain('Unknown error');
   });
 });
+
+//
+// New tests for listTestRunsTool & updateTestRunTool
+//
+
+import { listTestRunsTool, updateTestRunTool } from '../../src/tools/testmanagement';
+import { listTestRuns } from '../../src/tools/testmanagement-utils/list-testruns';
+import { updateTestRun } from '../../src/tools/testmanagement-utils/update-testrun';
+
+jest.mock('../../src/tools/testmanagement-utils/list-testruns', () => ({
+  listTestRuns: jest.fn(),
+  ListTestRunsSchema: {
+    parse: (args: any) => args,
+    shape: {},
+  },
+}));
+jest.mock('../../src/tools/testmanagement-utils/update-testrun', () => ({
+  updateTestRun: jest.fn(),
+  UpdateTestRunSchema: {
+    parse: (args: any) => args,
+    shape: {},
+  },
+}));
+
+describe('listTestRunsTool', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const mockRuns = [
+    { identifier: 'TR-1', name: 'Run One', run_state: 'new_run' },
+    { identifier: 'TR-2', name: 'Run Two', run_state: 'done' },
+  ];
+  const projectId = 'PR-123';
+
+  it('should return summary and raw JSON on success', async () => {
+    (listTestRuns as jest.Mock).mockResolvedValue({
+      content: [
+        { type: 'text', text: `Found 2 test run(s):\n\n• TR-1: Run One [new_run]\n• TR-2: Run Two [done]` },
+        { type: 'text', text: JSON.stringify(mockRuns, null, 2) },
+      ],
+      isError: false,
+    });
+
+    const result = await listTestRunsTool({ project_identifier: projectId } as any);
+    expect(listTestRuns).toHaveBeenCalledWith({ project_identifier: projectId });
+    expect(result.isError).toBe(false);
+    expect(result.content[0].text).toContain('Found 2 test run(s):');
+    expect(result.content[1].text).toBe(JSON.stringify(mockRuns, null, 2));
+  });
+
+  it('should handle errors', async () => {
+    (listTestRuns as jest.Mock).mockRejectedValue(new Error('Network Error'));
+    const result = await listTestRunsTool({ project_identifier: projectId } as any);
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Failed to list test runs: Network Error');
+  });
+});
+
+describe('updateTestRunTool', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const args = {
+    project_identifier: 'PR-123',
+    test_run_id: 'TR-1',
+    test_run: { name: 'Updated Name', run_state: 'in_progress' },
+  };
+
+  it('should return success message and updated run JSON on success', async () => {
+    const updated = { name: 'Updated Name', run_state: 'in_progress', tags: [] };
+    (updateTestRun as jest.Mock).mockResolvedValue({
+      content: [
+        { type: 'text', text: `Successfully updated test run ${args.test_run_id}` },
+        { type: 'text', text: JSON.stringify(updated, null, 2) },
+      ],
+      isError: false,
+    });
+
+    const result = await updateTestRunTool(args as any);
+    expect(updateTestRun).toHaveBeenCalledWith(args);
+    expect(result.isError).toBe(false);
+    expect(result.content[0].text).toContain(`Successfully updated test run ${args.test_run_id}`);
+    expect(result.content[1].text).toBe(JSON.stringify(updated, null, 2));
+  });
+
+  it('should handle errors', async () => {
+    (updateTestRun as jest.Mock).mockRejectedValue(new Error('API Error'));
+    const result = await updateTestRunTool(args as any);
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Failed to update test run: API Error');
+  });
+});