CLI Reference

Installation

Install the reporter as a dev dependency (npm):

npm install --save-dev @testkase/reporter

Or run it directly without installation:

npx @testkase/reporter report --help

Usage

npx @testkase/reporter report \
  --token <PAT> \
  --project-id <PROJECT_ID> \
  --org-id <ORG_ID> \
  --format <FORMAT> \
  --results-file <PATH> \
  [--cycle-id <CYCLE_ID>]        # optional, defaults to TCYCLE-1
  [--api-url <API_URL>]          # optional, defaults to https://api.testkase.com

Flag Reference

Per-Automation-ID Run Tracking

Each test result sent by the reporter is tagged with the automation ID that produced it. TestKase stores a separate run entry per (test case, automation ID) combination, which powers the Automation Runs card on the execute page.

How It Works

1. The reporter extracts [XXXXX] automation IDs from your test names.
2. Each result is sent with its automation_id to the execute-bulk API.
3. The backend creates (or updates) a run entry per test case, per automation ID.
4. When the same automation ID reports again, the existing entry is updated (UPSERT) — no duplicates.
5. The test case's overall status uses worst-status-wins precedence: fail > blocked > not_executed > pass.

When a Test Case Has Multiple Automation IDs

If a test case is linked to multiple automation IDs (e.g., one per CI pipeline or browser), the reporter sends one result per automation ID in the same bulk call. Each run is tracked independently:

• If 12345 passes and 67890 fails → overall status is Fail (worst wins)
• Both runs remain visible in the Automation Runs card with individual status, duration, and error details
• Re-running 67890 as Pass updates that specific entry and re-computes the overall status

See the automation guide for the full behavior.

Retry Details

When tests run with retries enabled, the reporter captures the full retry log — status, duration, and error for each attempt — and stores it in the Error Message field of the automation run. Flaky tests (failed then eventually passed) are detected automatically and labelled as such in Actual Result.

See Retry Details on the execution docs for how this appears on the execute page.

Retry support by format:

When a format does not support retries, the reporter only sees the final attempt — previous attempts are discarded by the test framework before the result file is written. This is a framework/format limitation, not a TestKase limitation.

Attachments

The reporter can upload screenshots, videos, logs, and other artifacts and attach them to the matched test cases on the execute page. Attachments come from two sources, and both run automatically on every report invocation:

1. Framework-parsed attachments

Some result formats embed artifact paths directly, and the reporter picks them up with no extra flags:

• Playwright JSON — attachments recorded on each test (screenshots, videos, traces). For retried tests, only the final attempt's artifacts are kept.
• JUnit XML — [[ATTACHMENT|path]] entries in a test's <system-out> (the convention Playwright's JUnit reporter and others use).
• NUnit XML — <attachment><filePath>…</filePath></attachment> elements on a test case.

Each parsed artifact is attached to the test case(s) mapped to that result's Automation ID. Relative paths are resolved against the results file's directory.

2. Generic --attachments-dir scan

Point --attachments-dir at a folder of artifacts and the reporter scans every file in it:

npx @testkase/reporter report \
  --token $TESTKASE_PAT \
  --project-id PRJ-1 \
  --org-id 1173 \
  --format junit \
  --results-file test-results/junit.xml \
  --attachments-dir test-results/screenshots

• If a file's name contains an Automation ID (matched with the same --automation-id-format regex, e.g. login-48271.png), it is attached to that specific test case.
• If a file has no Automation ID in its name, it is attached to every test case that was executed in this run.

Limits & upload flow

• Per-file cap: 50 MB. Files larger than 50 MB are skipped with a warning; the rest still upload.
• Uploads use presigned S3 URLs: the reporter requests a presigned URL from the backend, PUTs the file to storage, then finalizes the attachment. Uploaded files count toward your organization's storage quota.
• Run with --verbose to see per-file upload decisions, and check the Attachments: N uploaded, … summary line at the end of the run.

Supported Formats

Format-Specific Guidance

JUnit XML (--format junit)

The most universal format. Most test frameworks can produce JUnit XML output, making this the recommended default for cross-framework compatibility.

See the Test Frameworks section for detailed setup guides.

Playwright (--format playwright)

Use the JSON reporter for the richest data (attachments, retries, traces):

// playwright.config.ts
reporter: [['json', { outputFile: 'test-results/playwright.json' }]],

# 1. Run tests (generates test-results/playwright.json)
npx playwright test

# 2. Report to TestKase
npx @testkase/reporter report --format playwright \
  --results-file test-results/playwright.json ...

Alternatively, use --format junit with Playwright's JUnit reporter for cross-framework compatibility:

// playwright.config.ts
reporter: [['junit', { outputFile: 'test-results/playwright-junit.xml' }]],

# 1. Run tests (generates test-results/playwright-junit.xml)
npx playwright test

# 2. Report to TestKase
npx @testkase/reporter report --format junit \
  --results-file test-results/playwright-junit.xml ...

The reporter extracts 5-digit Automation IDs from test titles using the [XXXXX] bracket pattern. See the Playwright guide for full setup instructions.

Cypress (--format cypress)

Use cypress-mochawesome-reporter for native Cypress JSON output:

// cypress.config.js
reporter: 'cypress-mochawesome-reporter',
reporterOptions: { reportDir: 'test-results', overwrite: false, json: true }

# Report to TestKase
npx @testkase/reporter report --format cypress \
  --results-file test-results/mochawesome.json ...

Alternatively, use --format junit with mocha-junit-reporter for cross-framework compatibility:

// cypress.config.js
reporter: 'mocha-junit-reporter',
reporterOptions: { mochaFile: 'test-results/junit-[hash].xml' }

# Report to TestKase
npx @testkase/reporter report --format junit \
  --results-file test-results/junit-*.xml ...

See the Cypress guide for full setup instructions.

TestNG (--format testng)

TestNG produces XML reports by default in the test-output/ directory:

# 1. Run tests (TestNG generates test-output/testng-results.xml automatically)
mvn test

# 2. Report to TestKase
npx @testkase/reporter report --format testng \
  --results-file test-output/testng-results.xml ...

See the TestNG guide for full setup instructions.

NUnit (--format nunit)

Generate NUnit XML reports with the --logger flag:

# 1. Generate results
dotnet test --logger "nunit;LogFileName=nunit-results.xml"

# 2. Report to TestKase
npx @testkase/reporter report --format nunit \
  --results-file nunit-results.xml ...

See the NUnit guide for full setup instructions.

Cucumber (--format cucumber)

Cucumber tests produce JSON reports. Configure the JSON formatter in your runner:

// cucumber.js
module.exports = { default: '--format json:test-results/cucumber.json' }

# Report to TestKase
npx @testkase/reporter report --format cucumber \
  --results-file test-results/cucumber.json ...

See the Cucumber guide for full setup instructions.

Additional Commands

create-run

Create a new test cycle run in TestKase before reporting results. Useful when you want each CI build to report into a fresh run:

npx @testkase/reporter create-run \
  --token $TESTKASE_PAT \
  --project-id PRJ-1 \
  --org-id 1173 \
  --api-url https://api.testkase.com \
  --title "CI Build #$GITHUB_RUN_NUMBER"

Returns the cycle ID on success.

list-projects

List all projects accessible with your PAT. Useful for verifying your token and finding project IDs:

npx @testkase/reporter list-projects \
  --token $TESTKASE_PAT \
  --org-id 1173 \
  --api-url https://api.testkase.com

Dry Run & Debugging

Before pushing results to TestKase for the first time, use the --dry-run flag to preview the matching without actually updating any data:

npx @testkase/reporter report \
  --token $TESTKASE_PAT \
  --project-id PRJ-1 \
  --org-id 1173 \
  --format junit \
  --results-file test-results/junit.xml \
  --dry-run \
  --verbose

What Dry Run Shows

• Matched tests — Tests that were successfully matched to a TestKase test case via Automation ID.
• Unmatched tests — Tests in the results file that have no corresponding Automation ID in TestKase.
• Status mapping — What status each test would be reported as (Pass, Fail, Blocked, Not Executed).
• Skipped handling — How skipped tests are being mapped based on your --report-skipped-as setting.

Verbose Logging

Add --verbose for detailed output during troubleshooting. This shows:

• API request/response details
• File parsing progress
• Individual test case matching decisions
• Error details with stack traces