list-test-cycle

Instructions

Implementation Reference

• src/tools/test_execution/list_test_cycle.ts:29-52 (handler)

  Main handler function that lists test cycles. Accepts projectId (required), id, name, and parentId (optional). If id is provided, fetches a single cycle and its children tree. Otherwise, fetches all cycles (optionally filtered by parentId) and optionally filters by name (case-insensitive).

  export async function listTestCycles(
    args: ListTestCyclesArgs
  ): Promise<QTestTestCycle | QTestTestCycle[]> {
    const { projectId, id, name, parentId } = args
  
    if (id !== undefined) {
      const raw = await qtestFetch(config, projectId, `/test-cycles/${id}`, 'GET')
      return fetchCycleTree(projectId, raw as QTestTestCycle)
    }
  
    const endpoint = parentId !== undefined
      ? `/test-cycles?parentId=${parentId}&parentType=test-cycle`
      : '/test-cycles'
  
    const raw = await qtestFetch(config, projectId, endpoint, 'GET')
    const all = extractArray<QTestTestCycle>(raw)
  
    if (name !== undefined) {
      const lower = name.toLowerCase()
      return all.filter((c) => c.name.toLowerCase() === lower)
    }
  
    return all
  }

• src/tools/test_execution/list_test_cycle.ts:12-27 (helper)

  Recursive helper function that fetches and attaches child cycles to a given test cycle, building a full hierarchy tree.

  async function fetchCycleTree(projectId: string, cycle: QTestTestCycle): Promise<QTestTestCycle> {
    const childrenRaw = await qtestFetch(
      config, projectId,
      `/test-cycles?parentId=${cycle.id}&parentType=test-cycle`,
      'GET'
    )
    const children = extractArray<QTestTestCycle>(childrenRaw)
    if (children.length > 0) {
      const childTrees: QTestTestCycle[] = []
      for (const child of children) {
        childTrees.push(await fetchCycleTree(projectId, child))
      }
      cycle.children = childTrees
    }
    return cycle
  }

• src/tools/test_execution/list_test_cycle.ts:5-10 (schema)

  TypeScript interface defining the input arguments for listTestCycles: projectId (string), id (optional number), name (optional string), parentId (optional number).

  export interface ListTestCyclesArgs {
    projectId: string
    id?: number
    name?: string
    parentId?: number
  }

• src/server.ts:135-150 (registration)

  Registration of the 'list-test-cycle' tool on the MCP server with input schema (projectId, id, name, parentId) and handler that delegates to listTestCycles().

  server.registerTool(
    'list-test-cycle',
    {
      description:
        'Test Execution — list qTest test cycles. Omit all optional args for root-level listing, provide id for a single cycle, or provide name to filter by name (case-insensitive exact match)',
      inputSchema: {
        projectId: z.string().describe('Numeric project ID as string'),
        id: z.number().int().optional().describe('Test cycle ID; returns a single cycle'),
        name: z.string().optional().describe('Filter cycles by name (case-insensitive exact match)'),
        parentId: z.number().int().optional().describe('List child cycles of this parent test cycle ID'),
      },
    },
    async ({ projectId, id, name, parentId }) => {
      const result = await listTestCycles({ projectId, id, name, parentId })
      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
    }

• src/types.ts:45-52 (schema)

  TypeScript type definition for QTestTestCycle, the return type shape: id, name, pid, parentId, description, and optional children array for hierarchical cycles.

  export interface QTestTestCycle {
    id: number
    name: string
    pid?: string
    parentId?: number
    description?: string
    children?: QTestTestCycle[]
  }