[ZEPHYR] Get a specific test case

docs/products/SmartBear MCP Server/zephyr-integration.md

@@ -20,3 +20,10 @@ The following environment variables configure the Zephyr integration:
 
 - **Purpose**: Retrieve projects available within your Zephyr account.
 - **Returns**: A list of projects along with their properties, including information about if they have Zephyr enabled or not.
+
+### Get Test Case
+
+- **Purpose**: Retrieve the test case available within your Zephyr projects by key
+- **Parameters:** Test case key
+- **Returns**: A test case along with its properties.
+- **Use case**: Retrieve detailed information about a test case.

src/tests/unit/zephyr/tool/test-case/get-test-case.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from "vitest";
+import { TestCaseSchema } from "../../../../../zephyr/common/types.js";
+import {
+  GetTestCase,
+  GetTestCaseInputSchema,
+} from "../../../../../zephyr/tool/test-case/get-test-case.js";
+
+describe("GetTestCase", () => {
+  const mockApiClient = { get: vi.fn() };
+  const instance = new GetTestCase(mockApiClient as any);
+
+  it("should set specification correctly", () => {
+    expect(instance.specification.title).toBe("Get Test Case");
+    expect(instance.specification.summary).toBe(
+      "Get details of test case specified by key in Zephyr",
+    );
+    expect(instance.specification.readOnly).toBe(true);
+    expect(instance.specification.idempotent).toBe(true);
+    expect(instance.specification.inputSchema).toBe(GetTestCaseInputSchema);
+    expect(instance.specification.outputSchema).toBe(TestCaseSchema);
+  });
+
+  it("should call apiClient.get with correct params and return formatted content", async () => {
+    const responseMock = {
+      id: 1,
+      key: "SA-T10",
+      name: "Check axial pump",
+      project: {
+        id: 10005,
+        self: "https://api.example.com/projects/10005",
+      },
+      createdOn: "2018-05-15T13:15:13Z",
+      objective: "To ensure the axial pump can be enabled",
+      precondition: "Latest version of the axial pump available",
+      estimatedTime: 138000,
+      labels: ["Regression", "Performance", "Automated"],
+      component: {
+        id: 10001,
+        self: "https://<jira-instance>.atlassian.net/rest/api/2/component/10001",
+      },
+      priority: {
+        id: 10002,
+        self: "https://<api-base-url>/priorities/10002",
+      },
+      status: {
+        id: 10000,
+        self: "https://<api-base-url>/statuses/10000",
+      },
+      folder: {
+        id: 100006,
+        self: "https://<api-base-url>/folders/10006",
+      },
+      owner: {
+        self: "https://<jira-instance>.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g",
+        accountId: "5b10a2844c20165700ede21g",
+      },
+      testScript: {
+        self: "https://<api-base-url>/testCases/PROJ-T1/testscript",
+      },
+      customFields: {
+        "Build Number": 20,
+        "Release Date": "2020-01-01",
+        "Pre-Condition(s)":
+          "User should have logged in. <br> User should have navigated to the administration panel.",
+        Implemented: false,
+        Category: ["Performance", "Regression"],
+        Tester: "fa2e582e-5e15-521e-92e3-47e6ca2e7256",
+      },
+      links: {
+        self: "https://api.zephyrscale.smartbear.com/v2/testcases/14/links",
+        issues: [
+          {
+            self: "https://api.zephyrscale.smartbear.com/v2/testcases/14/links",
+            issueId: 10100,
+            id: 1,
+            target:
+              "https://<jira-instance>.atlassian.net/rest/api/2/issue/10000",
+            type: "COVERAGE",
+          },
+        ],
+        webLinks: [
+          {
+            self: "https://api.zephyrscale.smartbear.com/v2/testcases/14/links",
+            description: "A link to atlassian.com",
+            url: "https://atlassian.com",
+            id: 1,
+            type: "COVERAGE",
+          },
+        ],
+      },
+    };
+    mockApiClient.get.mockResolvedValueOnce(responseMock);
+    const args = { testCaseKey: "SA-T10" };
+    const result = await instance.handle(args, {});
+    expect(mockApiClient.get).toHaveBeenCalledWith("/testcases/SA-T10");
+    expect(result.structuredContent).toBe(responseMock);
+  });
+
+  it("should handle apiClient.get throwing error", async () => {
+    mockApiClient.get.mockRejectedValueOnce(new Error("API error"));
+    await expect(
+      instance.handle({ testCaseKey: "SA-T10" }, {}),
+    ).rejects.toThrow("API error");
+  });
+
+  it("should handle apiClient.get returning unexpected data", async () => {
+    mockApiClient.get.mockResolvedValueOnce(undefined);
+    const result = await instance.handle({ testCaseKey: "SA-T10" }, {});
+    expect(result.structuredContent).toBeUndefined();
+  });
+});

src/zephyr/client.ts

@@ -5,6 +5,7 @@ import type {
 } from "../common/types.js";
 import { ApiClient } from "./common/api-client.js";
 import { GetProjects } from "./tool/project/get-projects.js";
+import { GetTestCase } from "./tool/test-case/get-test-case.js";
 import type { ZephyrTool } from "./tool/zephyr-tool.js";
 
 export class ZephyrClient implements Client {
@@ -23,7 +24,10 @@ export class ZephyrClient implements Client {
     register: RegisterToolsFunction,
     _getInput: GetInputFunction,
   ): void {
-    const tools: ZephyrTool[] = [new GetProjects(this.apiClient)];
+    const tools: ZephyrTool[] = [
+      new GetProjects(this.apiClient),
+      new GetTestCase(this.apiClient),
+    ];
 
     tools.forEach((tool) => {
       register(tool.specification, tool.handle);

src/zephyr/common/types.ts

@@ -48,3 +48,101 @@ export function createListSchema<T extends ZodTypeAny>(itemSchema: T) {
 
 export const ZephyrProjectListSchema = createListSchema(ZephyrProjectSchema);
 export type ZephyrProjectList = z.infer<typeof ZephyrProjectListSchema>;
+
+export const TestCaseKeySchema = z
+  .string()
+  .regex(/^[A-Z0-9]+-T\d+$/)
+  .describe("The key of a Zephyr test case. Must match [A-Z0-9]+-T[0-9]+.");
+
+export const ReferenceSchema = z.object({
+  id: z.number().describe("The ID of the resource"),
+  self: z.string().url().describe("The API URL to get more resource details."),
+});
+
+export const JiraUserSchema = z.object({
+  self: z
+    .string()
+    .url()
+    .describe("Jira API URL to get more details about the user"),
+  accountId: z.string().describe("The Atlassian account ID of the user."),
+});
+
+export const CustomFieldsSchema = z
+  .record(z.any())
+  .describe("Custom fields with dynamic keys and values.");
+
+export const TypeSchema = z.enum(["COVERAGE", "RELATES", "BLOCKS"]);
+export const TestCaseLabelsSchema = z.enum([
+  "Regression",
+  "Performance",
+  "Automated",
+]);
+
+export const IssueLinkSchema = ReferenceSchema.merge(
+  z.object({
+    issueId: z.number().describe("ID of the linked issue."),
+    target: z.string().url().describe("Target URL of the linked issue."),
+    type: TypeSchema.describe("Type of the link (e.g., COVERAGE)."),
+  }),
+);
+
+export const WebLinkSchema = ReferenceSchema.merge(
+  z.object({
+    description: z.string().nullable().describe("Description of the web link."),
+    url: z.string().url().describe("URL of the web link."),
+    type: z.string().describe("Type of the web link."),
+  }),
+);
+
+export const TestCaseLinksSchema = z.object({
+  self: z.string().url().describe("API URL for the links resource."),
+  issues: z.array(IssueLinkSchema).describe("List of issue links."),
+  webLinks: z.array(WebLinkSchema).describe("List of web links."),
+});
+
+export const TestCaseSchema = z.object({
+  id: z.number().describe("The ID of the test case."),
+  key: z.string().describe("The key of the test case."),
+  name: z.string().describe("The name of the test case."),
+  project: ReferenceSchema,
+  createdOn: z.string().datetime().describe("Created on date (ISO 8601)."),
+  objective: z.string().nullable().describe("Objective of the test case."),
+  precondition: z
+    .string()
+    .nullable()
+    .describe("Precondition of the test case."),
+  estimatedTime: z
+    .number()
+    .nullable()
+    .describe("Estimated time to execute the test case in seconds."),
+  labels: z
+    .array(TestCaseLabelsSchema)
+    .nullable()
+    .describe("Labels associated with the test case."),
+  component: ReferenceSchema.nullable().describe("Component of the test case."),
+  priority: ReferenceSchema.describe("Priority of the test case."),
+  status: ReferenceSchema.nullable().describe(
+    "Current status of the test case.",
+  ),
+  folder: ReferenceSchema.nullable().describe(
+    "Folder containing the test case.",
+  ),
+  owner: JiraUserSchema.nullable().describe(
+    "Details about the test case owner",
+  ),
+  testScript: z
+    .object({
+      self: z
+        .string()
+        .url()
+        .describe("The API url for Test script or steps for the test case."),
+    })
+    .nullable()
+    .describe("Test script object for the test case."),
+  customFields: CustomFieldsSchema.nullable().describe(
+    "Custom fields for the test case.",
+  ),
+  links: TestCaseLinksSchema.nullable().describe(
+    "Links associated with the test case.",
+  ),
+});

src/zephyr/tool/test-case/get-test-case.ts

@@ -0,0 +1,52 @@
+import type { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ZodRawShape, z } from "zod";
+import type { ToolParams } from "../../../common/types.js";
+import type { ApiClient } from "../../common/api-client.js";
+import { TestCaseKeySchema, TestCaseSchema } from "../../common/types.js";
+import type { ZephyrTool } from "../zephyr-tool.js";
+
+export const GetTestCaseInputSchema = z.object({
+  testCaseKey: TestCaseKeySchema,
+});
+
+export class GetTestCase implements ZephyrTool {
+  private readonly apiClient: ApiClient;
+
+  constructor(apiClient: ApiClient) {
+    this.apiClient = apiClient;
+  }
+
+  specification: ToolParams = {
+    title: "Get Test Case",
+    summary: "Get details of test case specified by key in Zephyr",
+    readOnly: true,
+    idempotent: true,
+    inputSchema: GetTestCaseInputSchema,
+    outputSchema: TestCaseSchema,
+    examples: [
+      {
+        description: "Get the test case with key 'SA-T10'",
+        parameters: {
+          testCaseKey: "SA-T10",
+        },
+        expectedOutput: "The test case with its details",
+      },
+      {
+        description: "Get the test case with key 'MM2-T1'",
+        parameters: {
+          testCaseKey: "MM2-T1",
+        },
+        expectedOutput: "The test case with its details",
+      },
+    ],
+  };
+
+  handle: ToolCallback<ZodRawShape> = async (args: ZodRawShape) => {
+    const { testCaseKey } = GetTestCaseInputSchema.parse(args);
+    const response = await this.apiClient.get(`/testcases/${testCaseKey}`);
+    return {
+      structuredContent: response,
+      content: [],
+    };
+  };
+}