CLI Reference

Complete reference for the @testkase/reporter CLI — all flags, supported formats, debugging, and usage examples.

Installation

Install the reporter as a dev dependency:

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

Flag	Required	Description
`--token`	Yes	Your TestKase Personal Access Token (PAT). Generate one from API Keys. Store as a CI/CD secret — never hardcode in pipeline files.
`--api-url`	No	TestKase API base URL. Defaults to `https://api.testkase.com`. Override for self-hosted or QA environments.
`--project-id`	Yes	TestKase project ID (e.g., `PRJ-1`). Found in your project settings or URL.
`--org-id`	Yes	TestKase organization ID. Found in your organization settings.
`--cycle-id`	No	Target test cycle ID (e.g., `TCYCLE-5`). Defaults to `TCYCLE-1` (the default test cycle for the project). Override to report into a specific cycle.
`--format`	Yes	Test output format. Must match the format of your results file. One of: `junit`, `playwright`, `cypress`, `testng`, `nunit`, `cucumber`.
`--results-file`	Yes	Path to the test results file (e.g., `test-results/junit.xml`). Supports absolute and relative paths.
`--build-id`	No	CI build identifier for traceability (e.g., `$GITHUB_RUN_NUMBER`, `$CI_PIPELINE_IID`). Links executions to specific CI builds.
`--dry-run`	No	Preview results without pushing to TestKase. Shows matched/unmatched tests, status mapping, and skipped handling.
`--verbose`	No	Enable detailed logging output. Shows API request/response details, file parsing progress, and matching decisions.
`--report-skipped-as`	No	How to map skipped tests. Options: `blocked` (default — environment issues), `not-executed`, `ignore` (skip entirely).
`--automation-id-format`	No	Regex pattern used to extract Automation IDs from test names. Default: `\[(\d{5})\]`. The first capture group is used as the ID.
`--missing-id-in-script`	No	How to handle test results with no `[XXXXX]` Automation ID in the test name. Options: `skip` (default — ignore untagged tests), `fail` (exit with error), `create` (create a new test case in TestKase).
`--unknown-id-in-testkase`	No	How to handle extracted Automation IDs that do not match any test case in TestKase. Options: `skip` (default — log and continue), `fail` (exit with error).
`--silent`	No	Suppress all output except errors. Useful for CI environments where you want minimal log noise.
`--timezone`	No	Timezone for execution timestamps (e.g., `America/New_York`, `UTC`). Uses the system timezone if not specified.

Supported Formats

junit playwright cypress testng nunit cucumber

The junit format works with most test frameworks that produce JUnit XML output (Jest, Mocha, pytest, Robot Framework, Selenium, etc.). Use framework-specific formats (playwright, cypress, testng, nunit, cucumber) only when the framework has a native reporter that provides richer data.

Format → Framework Mapping

Format	Frameworks	Output File
`junit`	Jest, Mocha, pytest, Selenium, WebdriverIO, Robot Framework, Detox, Espresso, XCUITest, Playwright (via `--reporter=junit`)	`.xml`
`playwright`	Playwright (via `--reporter=json`)	`.json`
`cypress`	Cypress (via mochawesome or mocha-junit-reporter)	`.xml` or `.json`
`testng`	TestNG, Appium (with TestNG)	`.xml`
`nunit`	NUnit	`.xml`
`cucumber`	Cucumber (JS/Java/Ruby)	`.json`

Format-Specific Guidance

JUnit XML

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

Jest: npx jest --reporters=jest-junit (install jest-junit package)
Mocha: npx mocha --reporter mocha-junit-reporter
pytest: pytest --junitxml=test-results/junit.xml
Java (Maven): Surefire plugin produces JUnit XML by default in target/surefire-reports/
.NET: dotnet test --logger "junit;LogFileName=junit.xml"
Robot Framework: robot --xunit test-results/robot-junit.xml
WebdriverIO: wdio-junit-reporter package

See the Test Frameworks section for detailed setup guides.

Playwright JSON

For Playwright tests, use the JSON reporter for the most accurate result parsing:

npx playwright test --reporter=json > test-results/playwright.json

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

Cypress

Cypress tests can use the cypress-mochawesome-reporter or produce JUnit XML via mocha-junit-reporter:

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

See the Cypress guide for full setup instructions.

TestNG

TestNG produces XML reports by default in the test-output/ directory. Point the reporter to testng-results.xml. See the TestNG guide for full setup instructions.

NUnit

NUnit produces XML reports with the --result flag:

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

See the NUnit guide for full setup instructions.

Cucumber

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

// cucumber.js:
module.exports = { default: '--format json: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 \
  --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

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

Run with --dry-run --verbose as part of your initial setup to verify everything is configured correctly before enabling real reporting. This is especially useful for validating Automation ID matching.

CLI Reference

On this page