Overview
Common Test Report Format (CTRF) is a standardized JSON-based interchange format for representing test execution results across tools, languages, and platforms. CTRF enables consistent reporting, aggregation, and analysis of test outcomes.
info
For the normative, formal specification including design principles, terminology, and complete field definitions, see the CTRF Specification on GitHub.
Core Components
The specification is organized into the following main components:
| Component | Description |
|---|---|
| Root Object | The top-level structure containing format identification, versioning, and all report data. |
| Results Object | The core component encapsulating data for a single test run. |
| Tool Object | Identifies the testing tool, framework, or system that produced the results. |
| Summary Object | Aggregated statistics and timing data for the test run. |
| Test Object | Detailed information about individual test case execution and outcomes. |
| Status Values | The allowed values indicating test outcomes. |
| Environment Object | Execution context including build, commit, and system information. |
Lifecycle, Extension & Analysis
| Component | Description |
|---|---|
| Report Immutability | Lifecycle rules for emitted reports and documents created through post-processing. |
| Insights Object | Derived metrics computed across multiple runs for trend analysis. |
| Metrics Reference | Definitions for standard metrics used in CTRF insights. |
| Baseline Object | Reference to a previous report for comparison analysis. |
| Extra Object | Extensibility mechanism for custom metadata. |
Identity at a Glance
CTRF uses separate identifiers because a document, logical run, test case, and individual execution are not the same thing.
| Field | Identifies | Expected stability |
|---|---|---|
reportId | One emitted CTRF document | Preserved only when retransmitting the same unchanged document |
runId | One logical test run | Shared by every document or shard in that run |
testId | One logical test case | Stable across runs within the producer's documented scope |
executionId | One execution of a test case within a run | Unique for that execution |
attemptId | One previous attempt within an execution | Unique within the execution |
attachmentId | One attachment reference | Unique within its containing test or attempt |
shardId | One partition of a distributed run | Unique among documents sharing a runId |
All identity fields are optional. Producers should add the identifiers needed for correlation in their workflow.
Examples
Practical examples demonstrating the CTRF specification:
- Minimal Report Example - A minimal report using only required properties.
- Comprehensive Report Example - A full report showcasing optional properties and metadata.
Key Design Principles
- Layered Identity - Documents, logical runs, tests, executions, attempts, attachments, and shards have distinct identity scopes
- Immutable Reports - Once emitted, reports are fixed snapshots; post-processing produces a new document
- Machine-First - Optimized for machine processing while remaining human-readable
- Flat Test Structure - Tests are a flat collection with metadata for grouping, not nested hierarchies
- Strict Core, Namespaced Extensibility - Unknown fields are prohibited outside
extra, and extension keys should be namespaced to avoid collisions - Tool Agnostic - Works with any language, framework, or CI/CD system