Using the CLI

The Test Prism CLI is a high-performance command-line tool written in Rust. Its primary job is to read test reports generated by various testing frameworks and convert them into the standardized JSON format required by the Test Prism Dashboard.

Supported Formats

Format	Status	Notes
JUnit	✅ Supported	The standard XML format produced by most testing tools (Maven, Gradle, etc.).
Vitest	✅ Supported	Native JSON report output generated by Vitest JSON reporter.
Jest	✅ Supported	JSON report output generated by Jest using the JSON reporter.
Generic JSON	✅ Supported	Custom JSON reports parsed using a configurable JSON mapping file.
Generic XML	✅ Supported	Custom XML reports parsed using a configurable JSON mapping file.

Command Structure

The CLI is invoked using one of the following subcommands: parse or tag

test-prism-cli <COMMAND> [OPTIONS]

(Note: If you are running from source, replace test-prism-cli with cargo run --)

parse command

The parse command accepts the following arguments:

--report-type (Required)

Specifies the format of the input test report.

• Description: Use this flag to tell the cli which strategy to use for reading the input file.

Possible Values:

• junit
• vitest
• jest
• json (Generic JSON format using --mapping)
• xml (Generic XML format using --mapping)

--input (Required)

The path to the source test report file or folder

• Example: ./reports/junit.xml

--output (Optional)

The path where the resulting JSON file will be saved.

• Default: output.json
• Example: ./assets/test-results.json
• Description: If not provided, the cli will create a file named output.json in the current working directory.

--mapping (Required for generic report types json and xml)

The path to the JSON mapping file defining JSONPath selectors for generic report structures.

• Example: ./my-mapping.json

--tag (Optional)

A key-value pair to tag all the tests in the report. Can be specified multiple times.

• Example: --tag "owner:squad-a"
• Description: This is useful for adding metadata to the tests, such as the team that owns them.

Generic Report Mapping

When using --report-type json or --report-type xml, the CLI requires a JSON mapping configuration passed via --mapping. The mapping uses JSONPath expressions to map fields from arbitrary report formats into Test Prism models.

Mapping Schema

{
  "version": 1,
  "timeUnit": "s",
  "suitePath": "$.testResults[*]",
  "suiteName": "$.name",
  "suiteFile": "$.name",
  "suiteTimestamp": "$.timestamp",
  "suiteDuration": "$.time",
  "testPath": "$.assertionResults[*]",
  "testName": "$.title",
  "testStatus": "$.status",
  "testTime": "$.duration",
  "testMessage": "$.failureMessages[0]",
  "testAncestorTitles": "$.ancestorTitles[*]",
  "statusMap": {
    "passed": "passed",
    "failed": "failed",
    "skipped": "skipped"
  }
}

Mapping Fields

• version (Required): Mapping format version (currently 1).
• timeUnit (Optional): Duration unit, "s" (seconds) or "ms" (milliseconds). Default is "s".
• suitePath (Required): JSONPath expression to select test suites.
• suiteName (Optional): JSONPath expression relative to a suite for the suite name.
• suiteFile (Optional): JSONPath expression for the test source file path.
• suiteTimestamp (Optional): JSONPath expression for suite execution timestamp.
• suiteDuration (Optional): JSONPath expression for suite total duration.
• testPath (Required): JSONPath expression relative to a suite for individual test cases.
• testName (Required): JSONPath expression relative to a test for the test name.
• testStatus (Required): JSONPath expression relative to a test for raw status value.
• testTime (Optional): JSONPath expression relative to a test for test duration.
• testMessage (Optional): JSONPath expression for failure message or trace.
• testAncestorTitles (Optional): JSONPath expression for parent test group / describe block titles.
• statusMap (Required): Map of raw report status values to standard Test Prism statuses ("passed", "failed", "skipped", "error").

Examples

Basic Usage

Parse a JUnit XML file and save the result to the default output.json:

test-prism-cli parse --report-type junit --input ./build/test-results.xml

Custom Output Path

Parse a report and save it directly to the UI's assets folder (useful for local development):

test-prism-cli parse --report-type junit --input ./results.xml --output ./ui/src/assets/test-results.json

Jest JSON Report

Parse a Jest JSON report generated with the built-in JSON reporter:

test-prism-cli parse --report-type jest --input ./jest-results.json --output ./ui/src/assets/test-results.json

Generic JSON Report

Parse a custom JSON report with a mapping configuration:

test-prism-cli parse --report-type json --input ./custom-results.json --mapping ./mapping.json --output ./ui/src/assets/test-results.json

Tagging all tests

Parse a report and tag all tests with owner:squad-a:

test-prism-cli parse --report-type junit --input ./results.xml --tag "owner:squad-a"

tag command

The tag command allows you to add, remove, or update tags for tests in a JSON file.

--input (Required)

The path to the source JSON file.

• Example: ./assets/test-results.json

--output (Optional)

The path where the resulting JSON file will be saved.

• Default: The input file will be overwritten.
• Example: ./assets/test-results-tagged.json

--tag (Required)

A string that specifies the tag to add, remove, or update. The format is expression:operation:tag1,tag2.

• expression: A regular expression to match against the test name.

• operation: Can be add, remove, or update.

• tags: A comma-separated list of tags.

• Example: --tag ".*:add:smoke,regression"

Example

Tagging specific tests

Add the smoke and regression tags to all tests in a JSON file:

test-prism-cli tag --input ./assets/test-results.json --tag ".*:add:smoke,regression"