Fetch a Test Plan as JSON for AI Agents with tc getTestPlan

On this page

tc getTestPlan turns a curated TestCollab test plan into structured JSON for a script or AI testing agent. The agent can read each test case's steps and expected results, execute them against your application, write JUnit XML, and report the outcomes back to the same plan.

This is an optional agent-specific extension. A conventional automated suite uses the standard createTestPlan, test runner, and report path without getTestPlan.

The command fetches data only. It does not start a browser, choose an agent, execute a test, or upload a result.

Prerequisites

• @testcollab/cli installed on Node.js 18 or later
• A TestCollab project ID and test plan ID
• An API token whose user can view the project and plan
• An agent or script that can consume JSON and execute the described tests

For token setup, see Getting an API Token generated.

Fetch the plan

Store the token in the environment, then write the JSON to a file:

export TESTCOLLAB_TOKEN="your-token"
mkdir -p ./tmp

tc getTestPlan \
  --project 123 \
  --test-plan-id 456 \
  --output ./tmp/test-plan.json

The parent directory for --output must already exist. Without --output, JSON is written to standard output and progress messages are written to standard error, so piping remains safe:

tc getTestPlan \
  --project 123 \
  --test-plan-id 456 \
  > ./tmp/test-plan.json

What the JSON contains

A plan without configurations has this shape:

{
  "testPlan": {
    "id": 456,
    "title": "Nightly Regression",
    "status": "ready",
    "description": "Validate the staging release",
    "priority": "high",
    "totalCases": 1
  },
  "testCases": [
    {
      "id": 42,
      "testPlanTestCaseId": 789,
      "title": "Regular user cannot access admin settings",
      "description": "Use a non-admin fixture account",
      "priority": "high",
      "suite": "Permissions",
      "status": "unexecuted",
      "steps": [
        {
          "step": "Log in as the fixture user",
          "expectedResult": "The dashboard is displayed"
        },
        {
          "step": "Open /admin/settings",
          "expectedResult": "A 403 page is displayed"
        }
      ]
    }
  ]
}

The command returns:

• Plan ID, title, status, plain-text description, priority, and total case count
• Test case ID and its plan-specific testPlanTestCaseId
• Case title, plain-text description, priority, suite, and current status
• Ordered steps with their expected results
• Configuration definitions and per-configuration results when available

Plan statuses are mapped to draft, ready, finished, or finished_with_failures. Plan and case priorities are mapped to low, normal, or high. HTML is stripped from descriptions and step text.

The JSON is a focused execution view, not a full plan export. It does not include every TestCollab field, such as custom fields, linked requirements, defects, datasets, comments, or attachments.

Use the fetch, execute, report loop

1. Humans curate the plan, cases, steps, expected results, and assignments in TestCollab.
2. tc getTestPlan fetches the latest structured plan.
3. Your agent executes the cases against a defined test environment.
4. The agent writes one JUnit XML file with the TestCollab case ID in every result name.
5. tc report uploads the results to the same plan.

TestCollab plan
      |
      v
tc getTestPlan --output ./tmp/test-plan.json
      |
      v
your agent reads, executes, and writes agent-results.xml
      |
      v
tc report --test-plan-id 456 --result-file agent-results.xml

Require stable IDs in the agent's result file

Tell the agent to preserve each testCases[].id as an explicit marker. For example, case ID 42 should produce:

<testsuite name="Nightly Regression">
  <testcase
    classname="Permissions"
    name="[TC-42] Regular user cannot access admin settings"
  />
  <testcase
    classname="Permissions"
    name="[TC-43] Admin can edit user roles"
  >
    <failure message="Expected redirect to /admin but received 500" />
  </testcase>
</testsuite>

When reporting to an existing plan, a result without a supported case ID is warned about and skipped. It does not create a case. Case creation without IDs is available only in --auto-create mode, which is not appropriate when the goal is to update the curated plan you fetched.

Sample instructions for an agent

Read ./tmp/test-plan.json. For every object in testCases:
1. Perform its steps in order against https://staging.example.com.
2. Compare observable behavior with each expectedResult.
3. Mark the case passed only when all required expectations are satisfied.
4. Mark it failed with a concise reason when an expectation is not satisfied.
5. Mark it skipped with a reason when setup prevents the case from being tested.
6. Write JUnit XML to ./agent-results.xml.
7. Set each testcase name to "[TC-<id>] <title>" using the id from the JSON.

Do not call tc report. The CI pipeline uploads the file after validating it.

Also provide the agent with a clear base URL, test credentials, fixture state, timeout policy, and rules for ambiguous outcomes. Treat the plan JSON as sensitive if descriptions or steps contain credentials or customer data.

Report the agent's result

tc report \
  --project 123 \
  --test-plan-id 456 \
  --format junit \
  --result-file ./agent-results.xml

The plan cases reported by tc report must be assigned to the API token owner. Review the report mapping summary because missing IDs and unmatched assignments are warnings rather than fatal upload errors.

An additional tc gate step is optional. Add one only if your team has explicitly chosen to let the complete TestCollab plan control a pipeline or release, rather than using the agent or test runner's verdict.

Execute a multi-configuration plan

When the plan has configurations, the top-level JSON includes configuration definitions and cases can include configResults:

{
  "configurations": [
    {
      "id": 7,
      "parameters": [
        { "field": "Browser", "value": "Chrome" },
        { "field": "OS", "value": "Windows" }
      ],
      "assignedTo": "Automation User"
    }
  ],
  "testCases": [
    {
      "id": 42,
      "title": "Checkout completes",
      "configResults": [
        {
          "configId": 7,
          "configLabel": "Browser: Chrome, OS: Windows",
          "status": "unexecuted"
        }
      ]
    }
  ]
}

Loop over each required configResults entry, set up the named environment, and include its ID in the JUnit test name or classname:

<testcase
  classname="Checkout config-id-7"
  name="[TC-42] Checkout completes"
/>

The top-level configurations key is omitted when the plan has no configuration records. A case can also omit configResults when the API returns no per-configuration result entries for it.

How this differs from the TestCollab MCP server

tc getTestPlan is a deterministic CLI export suited to CI jobs and any agent that can read a file. An MCP connection gives a compatible AI assistant interactive TestCollab tools during a conversation. You can use either approach or combine them. See Connect the TestCollab MCP Server to AI Coding Assistants.

Use the EU region

For an EU-hosted account, add the EU API URL to getTestPlan, report, and any other TestCollab commands your chosen workflow actually runs:

--api-url https://api-eu.testcollab.io

Troubleshooting

The plan returns zero test cases

The command warns and still writes a valid JSON document. Confirm cases were added to the target plan and that the token can view them.

The output file cannot be written

Create its parent directory first and confirm the CI user can write there. getTestPlan does not create missing parent directories.

Configurations are missing from the JSON

Confirm the plan has Test Plan configurations and the token can read them. The command omits the key when no configuration records are returned.

Agent results are not mapped back

Open the JUnit XML and confirm every result contains the correct [TC-42] marker. Then confirm the case is in plan 456 and assigned to the token owner.