feat(testmanagement): apply custom templates via the v1 create endpoint

The public v2 create endpoint silently drops template_id, so a custom template
could never be applied through it. The v1 create endpoint DOES honour
template_id — verified end-to-end against prod.

When template_id is set, createTestCase now routes to
POST /api/v1/projects/{numericId}/test-cases (API-TOKEN auth, folder in the
body) instead of v2. custom_fields are translated from the MCP's by-name shape
to v1's by-id shape (field name -> id, option value -> option id) via form
fields, so multi-select custom fields keep working alongside a template. When
no template_id is given, the proven v2 path is unchanged (zero regression).

Verified live (project PR-141254, throwaway folder, cleaned up): a create with
template_id=656127 + custom_fields {aaas:[m40,m48]} + priority + tags + steps
produced template_id=656127 and both custom-field values, isError:false.

Tests: +2 (v1 routing shape/auth, custom_fields name->id translation). 198 green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gaurav-singh-9227

src/tools/testmanagement-utils/create-testcase.ts

@@ -168,7 +168,7 @@ export const CreateTestCaseSchema = z.object({
     .number()
     .optional()
     .describe(
-      "Numeric ID of a custom template (find via listTestCaseTemplates). Takes precedence over 'template'.",
+      "Numeric ID of a custom template (from listTestCaseTemplates); applies that template. Overrides 'template'.",
     ),
 });
 
@@ -258,6 +258,60 @@ async function fetchAppliedTemplateId(
   }
 }
 
+/**
+ * The v1 create endpoint (used when a template_id is requested) keys
+ * custom_fields by numeric field id with option *ids* — unlike the v2 endpoint,
+ * which keys by field name with option *values*. Translate the MCP's by-name
+ * shape into v1's by-id shape using the project's form fields. Best-effort:
+ * unknown fields/options pass through unchanged.
+ */
+async function toV1CustomFields(
+  customFields: Record<string, CustomFieldValue>,
+  numericProjectId: string,
+  config: BrowserStackConfig,
+): Promise<Record<string, CustomFieldValue>> {
+  let defs: any[] = [];
+  try {
+    const formFields = await fetchFormFields(numericProjectId, config);
+    defs = Array.isArray(formFields?.custom_fields)
+      ? formFields.custom_fields
+      : [];
+  } catch {
+    return customFields;
+  }
+
+  const byName = new Map<string, any>(defs.map((f) => [f.field_name, f]));
+  const out: Record<string, CustomFieldValue> = {};
+
+  for (const [name, value] of Object.entries(customFields)) {
+    const def = byName.get(name);
+    if (!def) {
+      out[name] = value; // unknown field name — leave as-is
+      continue;
+    }
+    const isOptionField =
+      def.field_type === "field_dropdown" ||
+      def.field_type === "field_multi_dropdown";
+    if (isOptionField) {
+      const optionIdByValue = new Map<string, string | number>();
+      for (const o of (def.option_values ?? []) as Array<{
+        option_value: string | number;
+        id: string | number;
+      }>) {
+        optionIdByValue.set(String(o.option_value), o.id);
+      }
+      const toOptionId = (v: string | number): string | number =>
+        optionIdByValue.get(String(v)) ?? v;
+      out[String(def.id)] = Array.isArray(value)
+        ? value.map(toOptionId)
+        : toOptionId(value as string | number);
+    } else {
+      out[String(def.id)] = value;
+    }
+  }
+  return out;
+}
+
 export async function createTestCase(
   params: TestCaseCreateRequest,
   config: BrowserStackConfig,
@@ -272,23 +326,62 @@ export async function createTestCase(
     );
   }
 
-  const body = { test_case: testCaseParams };
   const authString = getBrowserStackAuth(config);
   const [username, password] = authString.split(":");
 
   try {
     const tmBaseUrl = await getTMBaseURL(config);
-    const response = await apiClient.post({
-      url: `${tmBaseUrl}/api/v2/projects/${encodeURIComponent(
+
+    // The public v2 create endpoint silently drops template_id, so a specific
+    // (custom) template cannot be applied through it. The v1 create endpoint
+    // DOES honour template_id — but it needs the numeric project id, the folder
+    // in the body, API-TOKEN auth, and custom_fields keyed by id. Use v1 only
+    // when a template_id is requested; otherwise keep the proven v2 path so
+    // existing behaviour (incl. custom_fields by name) is unchanged.
+    let request: { url: string; headers: Record<string, string>; body: any };
+    if (testCaseParams.template_id !== undefined) {
+      const numericProjectId = await projectIdentifierToId(
         params.project_identifier,
-      )}/folders/${encodeURIComponent(params.folder_id)}/test-cases`,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization:
-          "Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
-      },
-      body,
-    });
+        config,
+      );
+      const v1TestCase: Record<string, any> = { ...testCaseParams };
+      delete v1TestCase.project_identifier;
+      delete v1TestCase.folder_id;
+      delete v1TestCase.custom_fields;
+      v1TestCase.test_case_folder_id = Number(params.folder_id);
+      if (testCaseParams.custom_fields) {
+        v1TestCase.custom_fields = await toV1CustomFields(
+          testCaseParams.custom_fields,
+          numericProjectId,
+          config,
+        );
+      }
+      request = {
+        url: `${tmBaseUrl}/api/v1/projects/${encodeURIComponent(
+          numericProjectId,
+        )}/test-cases`,
+        headers: {
+          "Content-Type": "application/json",
+          "API-TOKEN": authString,
+        },
+        body: { folder_id: Number(params.folder_id), test_case: v1TestCase },
+      };
+    } else {
+      request = {
+        url: `${tmBaseUrl}/api/v2/projects/${encodeURIComponent(
+          params.project_identifier,
+        )}/folders/${encodeURIComponent(params.folder_id)}/test-cases`,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization:
+            "Basic " +
+            Buffer.from(`${username}:${password}`).toString("base64"),
+        },
+        body: { test_case: testCaseParams },
+      };
+    }
+
+    const response = await apiClient.post(request);
 
     const { data } = response.data;
     if (!data.success) {
@@ -325,7 +418,7 @@ export async function createTestCase(
       if (appliedId !== undefined && appliedId !== Number(params.template_id)) {
         content.push({
           type: "text",
-          text: `Warning: requested template_id ${params.template_id} was not applied — the test case uses template_id ${appliedId}. The public Test Management create API does not currently apply a chosen template; verify the id via listTestCaseTemplates and that it is linked to this project.`,
+          text: `Warning: requested template_id ${params.template_id} was not applied — the test case uses template_id ${appliedId}. Confirm the id via listTestCaseTemplates and that the template is linked to this project.`,
         });
       }
     }

tests/tools/testmanagement.test.ts

@@ -1314,6 +1314,63 @@ describe('createTestCase — template & multi-select custom_fields', () => {
     expect(text).toContain('template_id 656127 was not applied');
     expect(text).toContain('template_id 2');
   });
+
+  // template_id is honoured only by the v1 create endpoint (v2 strips it), so a
+  // template_id request must route to /api/v1/.../test-cases with API-TOKEN auth
+  // and the folder carried in the body.
+  it('routes to the v1 create endpoint with API-TOKEN auth when template_id is set', async () => {
+    (apiClientMock.post as Mock).mockResolvedValueOnce(respWithId(656127));
+
+    await createTestCaseReal(
+      { ...baseArgs, folder_id: '50', template_id: 656127 },
+      mockConfig as any,
+    );
+
+    const call = (apiClientMock.post as Mock).mock.calls[0][0];
+    expect(call.url).toContain('/api/v1/projects/');
+    expect(call.url).toContain('/test-cases');
+    expect(call.url).not.toContain('/folders/'); // folder goes in the body for v1
+    expect(call.headers['API-TOKEN']).toBe('fake-user:fake-key');
+    expect(call.headers.Authorization).toBeUndefined();
+    expect(call.body.folder_id).toBe(50);
+    expect(call.body.test_case.test_case_folder_id).toBe(50);
+    expect(call.body.test_case.template_id).toBe(656127);
+    // MCP-only params must not leak into the v1 test_case payload.
+    expect(call.body.test_case.project_identifier).toBeUndefined();
+    expect(call.body.test_case.folder_id).toBeUndefined();
+  });
+
+  it('translates custom_fields name→id and option value→id on the v1 path', async () => {
+    const api = await import('../../src/tools/testmanagement-utils/TCG-utils/api');
+    (api.fetchFormFields as Mock).mockResolvedValueOnce({
+      default_fields: {},
+      custom_fields: [
+        {
+          field_name: 'aaas',
+          id: 194184,
+          field_type: 'field_multi_dropdown',
+          option_values: [
+            { option_value: 'm40', id: 111 },
+            { option_value: 'm48', id: 222 },
+          ],
+        },
+      ],
+    });
+    (apiClientMock.post as Mock).mockResolvedValueOnce(respWithId(656127));
+
+    await createTestCaseReal(
+      {
+        ...baseArgs,
+        folder_id: '50',
+        template_id: 656127,
+        custom_fields: { aaas: ['m40', 'm48'] },
+      },
+      mockConfig as any,
+    );
+
+    const body = (apiClientMock.post as Mock).mock.calls[0][0].body;
+    expect(body.test_case.custom_fields).toEqual({ 194184: [111, 222] });
+  });
 });
 
 // PMAA-131: multi-select custom fields on the update (PATCH) path.