Zero-Setup CI Reporting with tc report --auto-create

On this page

tc report --auto-create turns a JUnit XML or Mochawesome JSON file into a TestCollab test plan without requiring you to prepare a tag, suites, cases, plan, or assignments first. It is a fast way to prove an integration and begin collecting automated results.

This is an optional shortcut, not the standard reporting path. The standard path is tc createTestPlan, then your test runner, then tc report --test-plan-id. Auto-create replaces the first step when you deliberately want the result file to create project records.

Auto-create changes project data. Use an API token whose user is allowed to create and edit the resources described below. The examples use @testcollab/cli 1.17.0.

Use the zero-setup shortcut

Generate one supported result file, set the token, and report with --auto-create instead of --test-plan-id:

export TESTCOLLAB_TOKEN="your-token"

# Your framework creates this file first
pytest --junitxml=results.xml

tc report \
  --project 123 \
  --auto-create \
  --format junit \
  --result-file ./results.xml

The command parses the file, creates or reuses the required records, creates a new plan, assigns its cases to the token owner, and uploads pass, fail, and skip statuses.

Do not run createTestPlan before this command. --auto-create and --test-plan-id are alternative plan paths and cannot be used together.

What auto-create adds to TestCollab

Resource	Name or source	Creation behavior
Tag	CI Imported	Created once per project, then reused
Suites	Humanized from the result's nested suite path	Missing parent and child suites are created; matching suites are reused
Test cases	Result test titles	Created only when an ID or exact title match is not found
Test Plan folder	CI	Created once per project, then reused
Test plan	CI Run: DD-MM-YYYY HH:MM	A new ready plan is created for every invocation
Build	The value passed to --build	Created only when the build ID or version cannot be resolved to an existing build

Existing cases matched by ID or title are edited to include the CI Imported tag when they do not already have it.

Understand the CI Imported tag scope

Each auto-created plan is populated by selecting every case in the project with the CI Imported tag. It is not limited to cases found in the current result file. Because the tag is reused across runs, the plan can grow to include cases imported by earlier pipelines or suites.

This has two consequences:

• Cases not present in the current result remain unexecuted unless you use --skip-missing.
• If your team separately opts into a gate with --require-complete, it can fail because of those additional cases. If you use --skip-missing, those additional cases become skipped, and skipped cases count as complete.

Use separate curated tags and tc createTestPlan when different pipelines need strictly isolated case sets.

How cases are matched

ID-assisted auto-create

When a test title contains [TC-42], TC-42, id-42, or testcase-42, the CLI first looks up that case ID. A found case is reused and tagged.

<testcase name="[TC-42] customer can sign in" classname="Authentication" />

If the stated ID does not exist, auto-create falls back to title matching and then creation. For stable long-term mapping, correct stale IDs rather than relying on the fallback.

Full auto without case IDs

If no ID is present, the CLI compares the result title with existing cases in the same leaf suite. Matching is exact after lowercasing, trimming, and collapsing whitespace. It is not fuzzy.

Should login with valid credentials
should   login with valid credentials

These titles match in the same suite. Login test and Login tests do not, so the second title creates another case.

Mixed files

A single result file can contain both forms. Tests with IDs are matched by ID; tests without IDs are matched by title in their leaf suite or created. Add explicit [TC-42] markers over time to make renames and suite moves predictable.

How suite names and nesting are created

The CLI preserves the parent and child suite path from nested JUnit suites or Mochawesome suites. Each raw segment is humanized before it becomes a TestCollab suite title:

Raw suite name	TestCollab suite title
com.foo.bar.LoginTests	Login
tests/auth/login.spec.ts	Login
UserProfileTests	User Profile
user_profile_spec	User Profile
my-component-test	My Component
An empty suite name	Uncategorized

Path prefixes, common test file extensions, Java package prefixes, and suffixes such as Tests, Test, Spec, and Suite are removed. Camel case, underscores, and hyphens are split into title-cased words.

Optionally link the new plan to a build

Build traceability is not required for reporting. When you want it, add a build ID or version. A missing version is created as a build before the plan is created:

tc report \
  --project 123 \
  --auto-create \
  --format junit \
  --result-file ./results.xml \
  --build "2.14.0" \
  --environment "Staging"

--environment is stored only when this command creates the build. It does not update an existing build. The CLI never creates a release; an existing TestCollab release can be linked server-side when its version pattern matches the build. See Link CI Test Results to a Build or Release.

Use the created plan in a later CI step

The command writes the new plan ID to tmp/tc_test_plan:

source tmp/tc_test_plan
echo "$TESTCOLLAB_TEST_PLAN_ID"

You only need this value when another step must open, inspect, or otherwise act on the new plan. The report upload itself is already complete.

Optional: evaluate a separate TestCollab policy

tc gate is not required after reporting. Use it only when your team has chosen to let the complete TestCollab plan, rather than only the test runner, control a pipeline or release:

tc gate \
  --project 123 \
  --test-plan-id "$TESTCOLLAB_TEST_PLAN_ID" \
  --fail-on failed,blocked \
  --require-complete

Review the plan scope before opting in. Because all CI Imported cases are selected, older cases can be unexecuted and affect the policy result.

Required permissions

The token owner needs project access and permission to perform the resources used by the specific run:

• Create tags, suites, test cases, a test-plan folder, and a test plan
• Edit existing test cases to add the CI Imported tag
• Add and assign cases in the test plan
• View builds, and create a build when --build names a missing version

If a permission is missing, the API can stop the command after some earlier resources have already been created. Review the log before retrying.

Limitations and when to graduate

• --auto-create and --test-plan-id are mutually exclusive.
• --build on tc report requires --auto-create; --environment requires --build.
• Every invocation creates a new plan. There is no reuse-last-plan mode.
• Auto-created plans do not support Test Plan configurations. Use an existing configured plan for browser, OS, or data matrices.
• The CLI reads one result file. Merge framework shards first, or plan multiple uploads carefully.
• Exact title matching means small title changes can create duplicate test cases.
• Auto-create does not create a release or custom TestCollab statuses.

Prefer the standard curated workflow for ongoing production reporting, especially when ownership, review, manual cases, configurations, or strict plan membership matter. Apply a dedicated CI tag in TestCollab, create the plan with tc createTestPlan, run the tests, and report results with explicit [TC-42] markers. See Automated Testing in a CI/CD Pipeline with TestCollab.

Use the EU region

For an EU-hosted account, add this option to report and to any optional follow-up CLI commands you choose to run:

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

Troubleshooting

Similar test cases keep being created

Title matching allows differences in case and whitespace only. Add the correct [TC-42] marker to the test name, or keep its title and leaf suite stable.

The new plan contains tests that were not in this file

This is expected when those cases already have the project-wide CI Imported tag. Use --skip-missing only if they should be recorded as skipped, or adopt a curated tag and plan workflow for an isolated set.

Configuration results are not routed correctly

Auto-create does not build a multi-configuration plan. Prepare the configured plan in TestCollab, then upload to it with --test-plan-id and configuration markers.

A later step cannot find the plan ID

Run the later step in the same workspace and source tmp/tc_test_plan. If your CI isolates steps in different containers, persist that file or pass TESTCOLLAB_TEST_PLAN_ID through the provider's output mechanism.