ctrf

package
v0.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 21, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package ctrf provides Go types and utilities for the Common Test Report Format (CTRF). See https://ctrf.io/ and https://github.com/ctrf-io/ctrf/blob/main/schema/ctrf.schema.json

Index

Constants

View Source
const (
	// ReportFormatCTRF is the document format identifier.
	ReportFormatCTRF = "CTRF"

	// SpecVersion is the CTRF specification version implemented by this package.
	SpecVersion = "0.0.1"

	// StatusPassed indicates the test passed.
	StatusPassed = "passed"

	// StatusFailed indicates the test failed.
	StatusFailed = "failed"

	// StatusSkipped indicates the test was skipped.
	StatusSkipped = "skipped"

	// StatusPending indicates the test is pending execution.
	StatusPending = "pending"

	// StatusOther indicates an unexpected outcome (crash, OOM, timeout, etc.).
	StatusOther = "other"
)
View Source
const (
	// ConfigMapKeyReport is the key used to store the CTRF JSON in the ConfigMap.
	ConfigMapKeyReport = "report.json"
)

Variables

This section is empty.

Functions

func ConfigMapName

func ConfigMapName(runID, phase string) string

ConfigMapName returns the canonical ConfigMap name for a CTRF report.

func DeleteCTRFConfigMap

func DeleteCTRFConfigMap(
	ctx context.Context,
	clientset kubernetes.Interface,
	namespace, runID, phase string,
) error

DeleteCTRFConfigMap removes a CTRF ConfigMap. Ignores NotFound errors.

func ExitCodeToCTRFStatus

func ExitCodeToCTRFStatus(code int32) string

ExitCodeToCTRFStatus maps a container exit code to a CTRF status string.

func WriteCTRFConfigMap

func WriteCTRFConfigMap(
	ctx context.Context,
	clientset kubernetes.Interface,
	namespace, runID, phase string,
	report *Report,
) error

WriteCTRFConfigMap serializes a Report to JSON and writes it to a ConfigMap. Uses create-or-update semantics: creates the ConfigMap if it does not exist, updates it if it already exists from a previous run.

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder accumulates test results and produces a CTRF Report.

func NewBuilder

func NewBuilder(toolName, toolVersion, phase string) *Builder

NewBuilder creates a builder for a single phase's CTRF report.

func (*Builder) AddResult

func (b *Builder) AddResult(r *ValidatorResult)

AddResult converts a ValidatorResult to a CTRF TestResult and appends it.

func (*Builder) AddSkipped

func (b *Builder) AddSkipped(name, phase, reason string)

AddSkipped appends a skipped entry for a validator that was not executed.

func (*Builder) Build

func (b *Builder) Build() *Report

Build produces the final CTRF Report with computed summary.

func (*Builder) SetEnvironment

func (b *Builder) SetEnvironment(env *Environment)

SetEnvironment sets the optional environment metadata for the report.

type Environment

type Environment struct {
	// AppName is the name of the application under test.
	AppName string `json:"appName,omitempty"`

	// AppVersion is the version of the application under test.
	AppVersion string `json:"appVersion,omitempty"`

	// TestEnvironment is the logical test environment (e.g., "eks-h100-training").
	TestEnvironment string `json:"testEnvironment,omitempty"`
}

Environment describes the execution environment and build context.

type Report

type Report struct {
	// ReportFormat is the document format identifier. Always "CTRF".
	ReportFormat string `json:"reportFormat"`

	// SpecVersion is the CTRF specification version in SemVer format.
	SpecVersion string `json:"specVersion"`

	// Timestamp is the report generation time in RFC 3339 format.
	Timestamp string `json:"timestamp"`

	// GeneratedBy is the tool or system that produced this document.
	GeneratedBy string `json:"generatedBy"`

	// Results contains the test execution results.
	Results Results `json:"results"`
}

Report is the top-level CTRF document.

func MergeReports

func MergeReports(toolName, toolVersion string, reports []*Report) *Report

MergeReports combines multiple CTRF reports into a single report. It aggregates test results, summaries, and picks the earliest timestamp.

func ReadCTRFConfigMap

func ReadCTRFConfigMap(
	ctx context.Context,
	clientset kubernetes.Interface,
	namespace, runID, phase string,
) (*Report, error)

ReadCTRFConfigMap reads a CTRF Report from a ConfigMap.

type Results

type Results struct {
	// Tool identifies the testing tool or framework.
	Tool Tool `json:"tool"`

	// Summary provides aggregated statistics for the test run.
	Summary Summary `json:"summary"`

	// Tests is the list of individual test case results.
	Tests []TestResult `json:"tests"`

	// Environment describes the execution environment.
	Environment *Environment `json:"environment,omitempty"`
}

Results holds the tool metadata, summary, test entries, and environment.

type Summary

type Summary struct {
	// Tests is the total number of tests executed.
	Tests int `json:"tests"`

	// Passed is the count of tests with status "passed".
	Passed int `json:"passed"`

	// Failed is the count of tests with status "failed".
	Failed int `json:"failed"`

	// Skipped is the count of tests with status "skipped".
	Skipped int `json:"skipped"`

	// Pending is the count of tests with status "pending".
	Pending int `json:"pending"`

	// Other is the count of tests with status "other".
	Other int `json:"other"`

	// Start is the run start time in milliseconds since Unix epoch.
	Start int64 `json:"start"`

	// Stop is the run end time in milliseconds since Unix epoch.
	Stop int64 `json:"stop"`
}

Summary provides aggregated statistics and timing for a test run.

type TestResult

type TestResult struct {
	// Name is the name or title of the test case.
	Name string `json:"name"`

	// Status is the final outcome of the test case.
	// One of: "passed", "failed", "skipped", "pending", "other".
	Status string `json:"status"`

	// Duration is the test execution time in milliseconds.
	Duration int `json:"duration"`

	// Suite is the suite hierarchy from top-level to immediate parent.
	Suite []string `json:"suite,omitempty"`

	// Message is the error or failure message (e.g., from termination log).
	Message string `json:"message,omitempty"`

	// Stdout contains standard output lines from test execution.
	Stdout []string `json:"stdout,omitempty"`
}

TestResult represents an individual test case result.

type Tool

type Tool struct {
	// Name is the name of the testing tool.
	Name string `json:"name"`

	// Version is the version of the testing tool.
	Version string `json:"version,omitempty"`
}

Tool identifies the testing tool that produced the results.

type ValidatorResult

type ValidatorResult struct {
	// Name is the validator name from the catalog entry.
	Name string

	// Phase is the validation phase from the catalog entry.
	Phase string

	// ExitCode is the container exit code. -1 indicates the container never ran.
	ExitCode int32

	// TerminationMsg is the content of /dev/termination-log.
	TerminationMsg string

	// Stdout contains the standard output lines from the container.
	Stdout []string

	// Duration is the wall-clock execution time.
	Duration time.Duration

	// StartTime is when the container started.
	StartTime time.Time

	// CompletionTime is when the container finished.
	CompletionTime time.Time
}

ValidatorResult is the outcome of running a single validator container. Populated by the job package after extracting exit code, termination message, and stdout from the completed pod.

func (*ValidatorResult) CTRFStatus

func (r *ValidatorResult) CTRFStatus() string

CTRFStatus maps the exit code to a CTRF status string.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL