TestCollab CLI: Install and First Run

The @testcollab/cli package uploads automated test results from a CI/CD job to TestCollab. This guide covers the standard first run: install the CLI, create a test plan, run a test suite, and report the results.

You do not need to create a build or add a quality gate to report results. tc createBuild is optional build and release traceability, while tc gate is optional deployment control. Add either feature independently only when your workflow needs it.

Before you start

You need Node.js 18 or later and these values from TestCollab:

• An API token
• A project ID
• The ID of a tag applied to the test cases included in the run
• The user ID that should be assigned the test executions

Store the API token in your CI provider's encrypted secret store. Do not commit it to your repository.

1. Install the CLI

Install the current TestCollab CLI as a development dependency:

npm install --save-dev @testcollab/cli

Run locally installed commands with npx tc. If you prefer a global installation, use npm install --global @testcollab/cli and run tc directly.

2. Configure authentication

Expose the API token to the job as TESTCOLLAB_TOKEN:

export TESTCOLLAB_TOKEN="your-api-token"

The CLI connects to the US API by default. For an EU-hosted account, add this option to each TestCollab command:

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

3. Create a test plan

Create a plan from the test cases carrying your CI tag:

npx tc createTestPlan \
  --project 42 \
  --ci-tag-id 10 \
  --assignee-id 5

Replace the example IDs with values from your account. The command writes the created plan ID to tmp/tc_test_plan. Load it into the current shell before reporting results:

source tmp/tc_test_plan

4. Generate a supported report

The CLI accepts JUnit XML and Mochawesome JSON. Test names must contain the matching TestCollab case ID. The bracket form is the clearest:

test('[TC-42] a customer can sign in', async ({ page }) => {
  // Test steps
});

For example, Playwright can write JUnit XML to a known path like this:

PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit

Use your framework's reporter configuration if it produces the file another way.

5. Upload the results

npx tc report \
  --project 42 \
  --test-plan-id "$TESTCOLLAB_TEST_PLAN_ID" \
  --format junit \
  --result-file ./results.xml

For a Mochawesome report, use --format mochawesome and point --result-file to the JSON file. Add --skip-missing if test cases assigned to the API-token user but absent from the report should be marked skipped.

Confirm the first run

Open the created test plan in TestCollab and confirm that the result for [TC-42] appears under the assigned user. If it does not:

• Check that the report file exists before tc report runs.
• Check that the test name contains the correct TestCollab case ID.
• Check that the tagged case is included in the created plan and assigned to the expected user.
• Check that the token can access the selected project.

Next steps

Choose a complete pipeline file in Your CI provider, or see the TestCollab CLI command reference for every supported command and option.