CTRF
February 7, 2026 ยท View on GitHub
CTRF
CTRF TypeScript SDK - Reference Implementation
A complete TypeScript implementation for working with CTRF (Common Test Report Format) reports.
Core Operations
Core Types
Insights
Core Options
Builder Options
Query & Filter Options
Insights Options
Merge Options
Validation Options
Builders
Fluent builder for constructing CTRF reports.
Builders
Fluent builder for constructing Test objects.
Core Operations
Calculate summary statistics from an array of tests.
Core Operations
Check if a report is valid (type guard).
Core Operations
Parse a JSON string into a CTRFReport.
Core Operations
Serialize a CTRFReport to a JSON string.
Core Operations
Validate a report and throw if invalid (assertion).
Errors
Base error class for all CTRF errors. All CTRF-specific errors extend this class.
Errors
Error thrown when JSON parsing fails.
Errors
Error thrown when a file read or write operation fails.
Errors
Error thrown when an unsupported CTRF specification version is encountered.
Errors
Error thrown when building a report or test fails due to missing required fields.
Errors
Error thrown when schema validation fails. Contains detailed error information for each validation issue.
ID Generation
Generate a deterministic UUID v5 for a test based on its properties. The same inputs will always produce the same UUID, enabling cross-run analysis and test identification.
ID Generation
Generate a random UUID v4 for report identification.
Insights
Add insights to a CTRF report using historical data.
Computes run-level and test-level insights according to the CTRF specification, including pass rate, fail rate, flaky rate, and duration metrics.
Insights
Determines if a test is flaky based on the CTRF specification.
A test is considered flaky if:
-
The
flakyfield is explicitly set totrue, OR -
The test has retries > 0 AND final status is 'passed'
Merge
Merge multiple CTRF reports into a single report. Useful for combining results from parallel or sharded test runs.
Query & Filter
Filter tests in a report by criteria.
Query & Filter
Find a single test in a report.
Schema & Versioning
Get all supported spec versions.
Schema & Versioning
Get the JSON Schema for a specific CTRF spec version.
Schema & Versioning
Get the current spec version.
Schema & Versioning
The current version CTRF JSON Schema object.
Type Guards
Check if a report has insights.
Type Guards
Checks if an object has the basic structure of a CTRF report. This is a quick, lightweight check that doesn't validate against the full schema.
Type Guards
Type guard for RetryAttempt objects.
Type Guards
Type guard for Test objects.
Type Guards
Type guard for TestStatus values.