This guide walks you through setting up a GitHub Actions workflow that automatically creates a test plan in TestCollab, runs your tests, and uploads the results — all using the TestCollab CLI.

Prerequisites

A TestCollab API token (from Account Settings → API Tokens)
Your TestCollab project ID
A tag applied to the test cases you want to run in CI (note the tag ID)
The assignee user ID for pipeline executions
Test case IDs embedded in your test names (e.g., [TC-42] Login should succeed)

Step 1: Add Secrets to Your Repository

Go to your GitHub repository → Settings → Secrets and variables → Actions and add the following repository secrets:

Secret Name	Value
`TESTCOLLAB_TOKEN`	Your TestCollab API token
`TC_PROJECT_ID`	Your TestCollab project ID (number)
`TC_CI_TAG_ID`	Tag ID for CI test cases (number)
`TC_ASSIGNEE_ID`	Assignee user ID (number)

Step 2: Create the Workflow File

Create a file at .github/workflows/tests.yml in your repository. Below are complete examples for common test frameworks.

Example: Playwright (JUnit XML)

name: Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install dependencies
        run: npm ci
      - name: Install TestCollab CLI
        run: npm install -g @testcollab/cli
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
      - name: Create test plan
        run: |
          tc createTestPlan \
            --project ${{ secrets.TC_PROJECT_ID }} \
            --ci-tag-id ${{ secrets.TC_CI_TAG_ID }} \
            --assignee-id ${{ secrets.TC_ASSIGNEE_ID }}
      - name: Load test plan ID
        run: cat tmp/tc_test_plan >> $GITHUB_ENV
      - name: Run Playwright tests
        run: PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit
      - name: Upload results to TestCollab
        if: always()
        run: |
          tc report \
            --project ${{ secrets.TC_PROJECT_ID }} \
            --test-plan-id $TESTCOLLAB_TEST_PLAN_ID \
            --format junit \
            --result-file ./results.xml

Example: Cypress (Mochawesome JSON)

name: Tests
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install dependencies
        run: npm ci
      - name: Install TestCollab CLI
        run: npm install -g @testcollab/cli
      - name: Create test plan
        run: |
          tc createTestPlan \
            --project ${{ secrets.TC_PROJECT_ID }} \
            --ci-tag-id ${{ secrets.TC_CI_TAG_ID }} \
            --assignee-id ${{ secrets.TC_ASSIGNEE_ID }}
      - name: Load test plan ID
        run: cat tmp/tc_test_plan >> $GITHUB_ENV
      - name: Run Cypress tests
        run: npx cypress run --reporter mochawesome --reporter-options reportDir=results,overwrite=false,html=false,json=true
      - name: Upload results to TestCollab
        if: always()
        run: |
          tc report \
            --project ${{ secrets.TC_PROJECT_ID }} \
            --test-plan-id $TESTCOLLAB_TEST_PLAN_ID \
            --format mochawesome \
            --result-file ./results/mochawesome.json

Example: pytest (JUnit XML)

name: Tests
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Python dependencies
        run: pip install -r requirements.txt
      - name: Install TestCollab CLI
        run: npm install -g @testcollab/cli
      - name: Create test plan
        run: |
          tc createTestPlan \
            --project ${{ secrets.TC_PROJECT_ID }} \
            --ci-tag-id ${{ secrets.TC_CI_TAG_ID }} \
            --assignee-id ${{ secrets.TC_ASSIGNEE_ID }}
      - name: Load test plan ID
        run: cat tmp/tc_test_plan >> $GITHUB_ENV
      - name: Run pytest
        run: pytest --junitxml=results.xml
      - name: Upload results to TestCollab
        if: always()
        run: |
          tc report \
            --project ${{ secrets.TC_PROJECT_ID }} \
            --test-plan-id $TESTCOLLAB_TEST_PLAN_ID \
            --format junit \
            --result-file ./results.xml

How It Works

The workflow follows three steps:

Create test plan — tc createTestPlan creates a new test plan in TestCollab containing all test cases tagged with your CI tag. It writes the plan ID to tmp/tc_test_plan.
Load plan ID — The cat tmp/tc_test_plan >> $GITHUB_ENV step makes TESTCOLLAB_TEST_PLAN_ID available as an environment variable in all subsequent steps.
Upload results — tc report parses your test output and updates each test case execution in the plan. The if: always() condition ensures results are uploaded even when tests fail.

Test Case ID Mapping

The CLI matches results to TestCollab test cases by looking for ID patterns in your test names:

[TC-42] Login should succeed
TC-42 Login should succeed
Login should succeed id-42
Login should succeed testcase-42

All patterns are case-insensitive. See the main CLI documentation for full details on ID patterns and configuration support.

EU Region

If your TestCollab account is on the EU region, add --api-url https://api-eu.testcollab.io to both the tc createTestPlan and tc report commands.

Troubleshooting

Results not uploading

Check that TESTCOLLAB_TOKEN is set correctly in repository secrets
Verify the result file path matches what your test framework actually outputs
Make sure the --format flag matches your output format (junit or mochawesome)

Test cases not matched

Ensure your test names include a TestCollab ID pattern (e.g., [TC-42])
Verify the test cases are tagged with the CI tag and assigned to the correct user in the test plan