runner

package
v0.2.13 Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2026 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MaxServerRestartAttempts = 1
	RestartBackoffBase       = 2 * time.Second
)

Restart constants

View Source 
const (
	SandboxModeAuto   = "auto"
	SandboxModeStrict = "strict"
	SandboxModeOff    = "off"
)

Variables

This section is empty.

Functions

func BuildTraceTestResultsProto 

func BuildTraceTestResultsProto(e *Executor, results []TestResult, tests []Test) []*backend.TraceTestResult

func ConvertRunnerResultToTraceTestResult 

func ConvertRunnerResultToTraceTestResult(result TestResult, test Test) *backend.TraceTestResult

func ConvertRunnerResultsToTraceTestResults 

func ConvertRunnerResultsToTraceTestResults(results []TestResult, tests []Test) []*backend.TraceTestResult

ConvertRunnerResultsToTraceTestResults maps local results for upload to the backend

func DecodeValueBySchema 

func DecodeValueBySchema(value any, schema *core.JsonSchema) (decodedBytes []byte, parsedValue any, err error)

DecodeValueBySchema decodes any value using its JsonSchema. Handles encoding (e.g., BASE64) and parsing based on decoded type. Returns both decoded bytes (for raw use like HTTP requests) and parsed Go value (for comparison/display).

The function: - Decodes based on schema.Encoding (BASE64, UNSPECIFIED with fallback to base64 then raw) - Parses decoded bytes based on schema.DecodedType (JSON, text formats, binary formats) - Returns raw bytes for cases that need them (e.g., HTTP request bodies) - Returns parsed any for cases that need structured comparison (e.g., test assertions)

Single-level decoding only (no recursion through nested properties/items).

Parameters:

  • value: The value to decode (typically a string)
  • schema: The JsonSchema describing how to decode the value (nil schema is allowed)

Returns:

  • decodedBytes: The decoded raw bytes
  • parsedValue: The parsed Go value (JSON object/array, string, or base64 string for binary)
  • err: Any error encountered during decoding or parsing

func DedupeSpans 

func DedupeSpans(spans []*core.Span) []*core.Span

DedupeSpans deduplicates spans by (trace_id, span_id) while preserving order

func ExtractSuiteStatusFromFilter added in v0.2.7 

func ExtractSuiteStatusFromFilter(filter string) (string, bool)

ExtractSuiteStatusFromFilter extracts the suite_status value from a filter string. Returns the value and true if found, empty string and false otherwise.

func FetchGlobalSpansFromCloud 

func FetchGlobalSpansFromCloud(
	ctx context.Context,
	client *api.TuskClient,
	auth api.AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*core.Span, error)

FetchGlobalSpansFromCloud fetches only spans marked as global (is_global=true) from cloud

func FetchGlobalSpansFromCloudWithCache 

func FetchGlobalSpansFromCloudWithCache(
	ctx context.Context,
	client *api.TuskClient,
	auth api.AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*core.Span, error)

FetchGlobalSpansFromCloudWithCache fetches global spans using cache. It only fetches new spans and removes deleted ones from cache.

func FetchLocalPreAppStartSpans 

func FetchLocalPreAppStartSpans(interactive bool) ([]*core.Span, error)

FetchLocalPreAppStartSpans fetches pre-app-start spans from local trace files

func FetchPreAppStartSpansFromCloud 

func FetchPreAppStartSpansFromCloud(
	ctx context.Context,
	client *api.TuskClient,
	auth api.AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*core.Span, error)

FetchPreAppStartSpansFromCloud fetches pre-app-start spans from the cloud backend

func FetchPreAppStartSpansFromCloudWithCache 

func FetchPreAppStartSpansFromCloudWithCache(
	ctx context.Context,
	client *api.TuskClient,
	auth api.AuthOptions,
	serviceID string,
	interactive bool,
	quiet bool,
) ([]*core.Span, error)

FetchPreAppStartSpansFromCloudWithCache fetches pre-app-start spans using cache. It only fetches new spans and removes deleted ones from cache.

func GetFirstSpanTimestamp 

func GetFirstSpanTimestamp(spans []*core.Span) (float64, string)

GetFirstSpanTimestamp returns the timestamp to use for time travel. Priority: server/root span > earliest non-server span. Root span is preferred for inbound-level determinism (e.g., caching keys derived from time).

func OutputResultsSummary 

func OutputResultsSummary(results []TestResult, format string, quiet bool) error

func OutputSingleResult 

func OutputSingleResult(result TestResult, test Test, format string, quiet bool, verbose bool)

func ParseTraceTestStatusFilter added in v0.2.7 

func ParseTraceTestStatusFilter(val string) *backend.TraceTestStatus

ParseTraceTestStatusFilter converts a user-provided filter value to a proto TraceTestStatus. Returns nil if the value doesn't match a known status.

func PrepareAndSetSuiteSpans 

func PrepareAndSetSuiteSpans(
	ctx context.Context,
	exec *Executor,
	opts SuiteSpanOptions,
	currentTests []Test,
) error

PrepareAndSetSuiteSpans is a convenience function that builds suite spans and sets them on the executor

func PrepareReplayEnvironmentGroup 

func PrepareReplayEnvironmentGroup(executor *Executor, group *EnvironmentGroup) (cleanup func(), err error)

PrepareReplayEnvironmentGroup sets recorded env vars on the process and, if applicable, prepares a Docker Compose override file so env vars are injected into containers. The returned cleanup always clears executor replay env vars, clears executor override state, and removes the temporary override file when present.

func RedactSecrets added in v0.2.9 

func RedactSecrets(content string) string

redactSecrets scans content for secrets using gitleaks and replaces them with TUSK_REDACTED_{RULE_ID} placeholders. Returns the original content unchanged if detection fails (graceful fallback).

func ReportDriftRunSuccess 

func ReportDriftRunSuccess(
	ctx context.Context,
	client *api.TuskClient,
	driftRunID string,
	authOptions api.AuthOptions,
	results []TestResult,
	coverageBaseline CoverageSnapshot,
	coverageOriginalBaseline CoverageSnapshot,
	commitSha string,
	statusMessageOverride ...string,
) error

func SnapshotToCoverageDetail added in v0.2.12 

func SnapshotToCoverageDetail(snapshot CoverageSnapshot) map[string]CoverageFileDiff

SnapshotToCoverageDetail converts a CoverageSnapshot to per-file CoverageFileDiff format.

func UploadSingleTestResult 

func UploadSingleTestResult(
	ctx context.Context,
	client *api.TuskClient,
	driftRunID string,
	auth api.AuthOptions,
	e *Executor,
	res TestResult,
	test Test,
) error

func WriteCoverageJSON added in v0.2.12 

func WriteCoverageJSON(path string, aggregate CoverageSnapshot, perTest map[string]map[string]CoverageFileDiff, records []CoverageTestRecord) error

WriteCoverageJSON writes aggregate + per-test coverage as JSON.

func WriteCoverageLCOV added in v0.2.12 

func WriteCoverageLCOV(path string, aggregate CoverageSnapshot) error

WriteCoverageLCOV writes aggregate coverage data in LCOV format.

Types

type AgentWriter added in v0.2.8 

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

AgentWriter handles writing deviation files for agent consumption.

func NewAgentWriter added in v0.2.8 

func NewAgentWriter(outputDir string) (*AgentWriter, error)

NewAgentWriter creates a new AgentWriter that writes to the given directory. The directory must already exist (created by the caller).

func (*AgentWriter) OutputDir added in v0.2.8 

func (w *AgentWriter) OutputDir() string

OutputDir returns the full output directory path.

func (*AgentWriter) RecordPassedTest added in v0.2.8 

func (w *AgentWriter) RecordPassedTest(test Test)

RecordPassedTest records a passing test for the index.

func (*AgentWriter) SetBaseBranch added in v0.2.8 

func (w *AgentWriter) SetBaseBranch(branch string)

SetBaseBranch sets the base branch name to include in the index file.

func (*AgentWriter) WriteDeviation added in v0.2.8 

func (w *AgentWriter) WriteDeviation(test Test, result TestResult, server *Server) error

WriteDeviation writes a single deviation file for a failed test.

func (*AgentWriter) WriteIndex added in v0.2.8 

func (w *AgentWriter) WriteIndex(totalTests int, passedTests int) error

WriteIndex writes the index.md summary file.

type BranchInfo added in v0.2.12 

type BranchInfo struct {
	Total   int `json:"total"`
	Covered int `json:"covered"`
}

BranchInfo tracks branch coverage at a specific line.

type BuildSuiteSpansResult 

type BuildSuiteSpansResult struct {
	SuiteSpans       []*core.Span
	GlobalSpans      []*core.Span // Only populated in non-validation mode
	PreAppStartCount int
	UniqueTraceCount int
}

BuildSuiteSpansResult contains the result of building suite spans

func BuildSuiteSpansForRun 

func BuildSuiteSpansForRun(
	ctx context.Context,
	opts SuiteSpanOptions,
	currentTests []Test,
) (*BuildSuiteSpansResult, error)

BuildSuiteSpansForRun builds the suite spans for the run. Returns the suite spans, global spans (when not suite-wide matching), pre-app-start count, and unique trace count.

type CommunicationType 

type CommunicationType string
const (
	CommunicationUnix CommunicationType = "unix"
	CommunicationTCP  CommunicationType = "tcp"
)

type CoverageAggregate added in v0.2.12 

type CoverageAggregate struct {
	TotalCoverableLines int     `json:"total_coverable_lines"`
	TotalCoveredLines   int     `json:"total_covered_lines"`
	CoveragePct         float64 `json:"coverage_pct"`
	TotalFiles          int     `json:"total_files"`
	CoveredFiles        int     `json:"covered_files"`
	TotalBranches       int     `json:"total_branches"`
	CoveredBranches     int     `json:"covered_branches"`
	BranchCoveragePct   float64 `json:"branch_coverage_pct"`
}

type CoverageExport added in v0.2.12 

type CoverageExport struct {
	Summary   CoverageSummary                        `json:"summary"`
	Aggregate CoverageSnapshot                       `json:"aggregate"`
	PerTest   map[string]map[string]CoverageFileDiff `json:"per_test"`
}

CoverageExport is the top-level JSON export structure.

type CoverageFileDiff added in v0.2.12 

type CoverageFileDiff struct {
	CoveredLines    []int                 `json:"covered_lines"`
	CoverableLines  int                   `json:"coverable_lines"`
	CoveredCount    int                   `json:"covered_count"`
	TotalBranches   int                   `json:"total_branches"`
	CoveredBranches int                   `json:"covered_branches"`
	Branches        map[string]BranchInfo `json:"branches,omitempty"`
}

CoverageFileDiff represents per-test coverage for a single file.

type CoverageFileSummary added in v0.2.12 

type CoverageFileSummary struct {
	CoveredLines    int     `json:"covered_lines"`
	CoverableLines  int     `json:"coverable_lines"`
	CoveragePct     float64 `json:"coverage_pct"`
	TotalBranches   int     `json:"total_branches"`
	CoveredBranches int     `json:"covered_branches"`
}

type CoverageReportView added in v0.2.12 

type CoverageReportView struct {
	SuiteRecords []CoverageTestRecord
	Aggregate    CoverageSnapshot
	PerTest      map[string]map[string]CoverageFileDiff
	Summary      CoverageSummary
}

CoverageReportView is a pre-computed view of coverage data, built once and passed to all consumers (print, JSON export, TUI) for consistency.

type CoverageSnapshot added in v0.2.12 

type CoverageSnapshot map[string]FileCoverageData

CoverageSnapshot is the full coverage data for a snapshot.

type CoverageSummary added in v0.2.12 

type CoverageSummary struct {
	Timestamp string                         `json:"timestamp"`
	Aggregate CoverageAggregate              `json:"aggregate"`
	PerFile   map[string]CoverageFileSummary `json:"per_file"`
	PerTest   []CoverageTestSummary          `json:"per_test"`
}

func ComputeCoverageSummary added in v0.2.12 

func ComputeCoverageSummary(
	aggregate CoverageSnapshot,
	perTestDetail map[string]map[string]CoverageFileDiff,
	records []CoverageTestRecord,
) CoverageSummary

ComputeCoverageSummary builds a CoverageSummary from aggregate coverage data and per-test detail. This is a pure function (no side effects, no I/O).

type CoverageTestRecord added in v0.2.12 

type CoverageTestRecord struct {
	TestID      string
	TestName    string
	SuiteStatus string // "draft", "in_suite", or "" (local)
	Coverage    CoverageSnapshot
}

CoverageTestRecord holds per-test coverage data.

type CoverageTestSummary added in v0.2.12 

type CoverageTestSummary struct {
	TestID       string `json:"test_id"`
	TestName     string `json:"test_name"`
	CoveredLines int    `json:"covered_lines"`
	FilesTouched int    `json:"files_touched"`
}

type Deviation 

type Deviation struct {
	Field       string `json:"field"`
	Expected    any    `json:"expected"`
	Actual      any    `json:"actual"`
	Description string `json:"description"`
}

type DynamicFieldMatcher 

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

DynamicFieldMatcher defines patterns for identifying dynamic fields that should be ignored

func NewDynamicFieldMatcher 

func NewDynamicFieldMatcher() *DynamicFieldMatcher

NewDynamicFieldMatcher creates a new matcher with default patterns

func NewDynamicFieldMatcherWithConfig 

func NewDynamicFieldMatcherWithConfig(cfg *config.ComparisonConfig) *DynamicFieldMatcher

func (*DynamicFieldMatcher) ShouldIgnoreField 

func (m *DynamicFieldMatcher) ShouldIgnoreField(fieldName string, expectedValue, actualValue any, testID string) bool

ShouldIgnoreField determines if a field should be ignored during comparison

type EnvironmentExtractionResult 

type EnvironmentExtractionResult struct {
	Groups   []*EnvironmentGroup // Grouped tests by environment
	Warnings []string            // Non-fatal warnings (e.g., missing ENV_VARS)
}

EnvironmentExtractionResult contains the result of grouping tests by environment

func GroupTestsByEnvironment 

func GroupTestsByEnvironment(tests []Test, preAppStartSpans []*core.Span) (*EnvironmentExtractionResult, error)

GroupTestsByEnvironment analyzes tests and groups them by environment preAppStartSpans should contain all pre-app-start spans (including ENV_VARS spans) Returns grouped tests and any warnings encountered

type EnvironmentGroup 

type EnvironmentGroup struct {
	Name        string            // Environment name (e.g., "production", "staging", "default")
	Tests       []Test            // Tests for this environment
	EnvVars     map[string]string // Environment variables extracted from ENV_VARS span
	EnvVarsSpan *core.Span        // Source span for provenance/debugging (can be nil)
}

EnvironmentGroup represents tests grouped by environment

type Executor 

type Executor struct {
	ResultsFile     string // Will be set by the run command if --save-results is true
	OnTestCompleted func(TestResult, Test)
	// contains filtered or unexported fields
}

func NewExecutor 

func NewExecutor() *Executor

func (*Executor) AddCoverageRecord added in v0.2.12 

func (e *Executor) AddCoverageRecord(record CoverageTestRecord)

AddCoverageRecord stores a per-test coverage record.

func (*Executor) BuildCoverageReportView added in v0.2.12 

func (e *Executor) BuildCoverageReportView(records []CoverageTestRecord) *CoverageReportView

BuildCoverageReportView constructs a CoverageReportView by applying suite filtering, include/exclude patterns, and computing the summary — all exactly once.

func (*Executor) CancelTests 

func (e *Executor) CancelTests()

func (*Executor) CheckServerHealth 

func (e *Executor) CheckServerHealth() bool

CheckServerHealth performs a quick health check to see if the service is responsive

func (*Executor) DiscardStartupBuffer 

func (e *Executor) DiscardStartupBuffer()

DiscardStartupBuffer makes the in-memory startup log buffer discard future writes and frees its memory. This is called after the service starts successfully to avoid unbounded memory growth during the test run. Has no effect when --enable-service-logs is set (file-based logging persists for the full run).

Note: we can't swap cmd.Stdout after Start() because Go's exec package captures the writer by reference in an internal goroutine at Start() time. Instead, we set a flag on the buffer itself to make Write a no-op.

func (*Executor) ForceStopEnvironment 

func (e *Executor) ForceStopEnvironment() error

forceStopEnvironment aggressively stops the service and mock server Used when the server has crashed and we need to ensure clean slate

func (*Executor) FormatCoverageSummaryLines added in v0.2.12 

func (e *Executor) FormatCoverageSummaryLines(records []CoverageTestRecord) ([]string, CoverageSnapshot)

FormatCoverageSummaryLines builds a CoverageReportView and returns formatted summary lines for the TUI service log panel (aggregate + per-file, no per-test). Also returns the computed aggregate so callers can reuse it (avoiding redundant computation).

func (*Executor) GetConcurrency 

func (e *Executor) GetConcurrency() int

GetConcurrency returns the current concurrency setting

func (*Executor) GetCoverageBaselineForUpload added in v0.2.12 

func (e *Executor) GetCoverageBaselineForUpload() (merged CoverageSnapshot, originalBaseline CoverageSnapshot)

GetCoverageBaselineForUpload returns two snapshots:

  • merged: baseline + all per-test records (complete denominator for coverable lines)
  • originalBaseline: raw baseline only (for startup-covered lines attribution)

The merged snapshot ensures the denominator includes lines discovered during test execution that weren't in the initial baseline snapshot. The original baseline is kept separate so startup coverage is not conflated with test-driven coverage.

func (*Executor) GetCoverageOutputPath added in v0.2.12 

func (e *Executor) GetCoverageOutputPath() string

func (*Executor) GetCoveragePerTestSnapshot added in v0.2.12 

func (e *Executor) GetCoveragePerTestSnapshot() map[string]map[string]CoverageFileDiff

GetCoveragePerTestSnapshot returns a shallow copy of the entire per-test coverage map. The outer map is copied so callers can iterate without holding the mutex.

func (*Executor) GetCoverageRecords added in v0.2.12 

func (e *Executor) GetCoverageRecords() []CoverageTestRecord

GetCoverageRecords returns a copy of all coverage records.

func (*Executor) GetEffectiveSandboxMode 

func (e *Executor) GetEffectiveSandboxMode() string

GetEffectiveSandboxMode returns the runtime sandbox mode after applying the platform-aware default for unset configs/flags.

func (*Executor) GetSandboxMode 

func (e *Executor) GetSandboxMode() string

GetSandboxMode returns the configured replay sandbox mode. An empty string means the user did not explicitly configure a mode.

func (*Executor) GetServer 

func (e *Executor) GetServer() *Server

GetServer returns the server instance

func (*Executor) GetServiceLogPath 

func (e *Executor) GetServiceLogPath() string

func (*Executor) GetStartupFailureHelpMessage 

func (e *Executor) GetStartupFailureHelpMessage() string

GetStartupFailureHelpMessage returns a user-friendly help message when the service fails to start.

func (*Executor) GetStartupLogs 

func (e *Executor) GetStartupLogs() string

GetStartupLogs returns the captured service startup logs. When --enable-service-logs is set, it reads back from the log file. Otherwise, it returns the contents of the in-memory startup buffer.

func (*Executor) GetSuiteSpans 

func (e *Executor) GetSuiteSpans() []*core.Span

GetSuiteSpans returns the suite spans (includes pre-app-start spans)

func (*Executor) GetTestCoverageDetail added in v0.2.12 

func (e *Executor) GetTestCoverageDetail(testID string) map[string]CoverageFileDiff

GetTestCoverageDetail returns a copy of per-test coverage diff for a given test.

func (*Executor) IsCoverageEnabled added in v0.2.12 

func (e *Executor) IsCoverageEnabled() bool

func (*Executor) IsCoverageShowOutput added in v0.2.12 

func (e *Executor) IsCoverageShowOutput() bool

func (*Executor) IsServiceLogsEnabled 

func (e *Executor) IsServiceLogsEnabled() bool

func (*Executor) LoadSpansForTrace 

func (e *Executor) LoadSpansForTrace(traceID string, filename string) ([]*core.Span, error)

func (*Executor) LoadTestFromTraceFile 

func (e *Executor) LoadTestFromTraceFile(path string) (*Test, error)

LoadTestFromTraceFile loads a test from a trace file (one trace per file)

func (*Executor) LoadTestsFromFolder 

func (e *Executor) LoadTestsFromFolder(folder string) ([]Test, error)

func (*Executor) ProcessCoverage added in v0.2.12 

func (e *Executor) ProcessCoverage(records []CoverageTestRecord) error

ProcessCoverage computes aggregate coverage, optionally prints summary, writes file, and prepares for upload. During validation runs, the aggregate and output files only include IN_SUITE tests (not drafts). All per-test data (including drafts) is retained for backend upload — the backend needs draft coverage for promotion decisions ("does this draft add unique coverage?").

func (*Executor) ProcessCoverageWithAggregate added in v0.2.12 

func (e *Executor) ProcessCoverageWithAggregate(records []CoverageTestRecord, precomputed CoverageSnapshot) error

ProcessCoverageWithAggregate processes coverage with an optional pre-computed view. If precomputed is nil, it will be computed from the records and baseline.

func (*Executor) RestartServerWithRetry 

func (e *Executor) RestartServerWithRetry(attempt int) error

RestartServerWithRetry attempts to restart the server with exponential backoff

func (*Executor) RunBatchSequentialWithCrashHandling 

func (e *Executor) RunBatchSequentialWithCrashHandling(batch []Test, hasMoreTestsAfterBatch bool) []TestResult

RunBatchSequentialWithCrashHandling runs a batch of tests sequentially, restarting after each crash hasMoreTestsAfterBatch indicates if there are more tests to run after this batch completes

func (*Executor) RunBatchWithCrashDetection 

func (e *Executor) RunBatchWithCrashDetection(batch []Test, concurrency int) ([]TestResult, bool)

RunBatchWithCrashDetection runs a batch of tests and detects if the server crashed

func (*Executor) RunSingleTest 

func (e *Executor) RunSingleTest(test Test) (TestResult, error)

RunSingleTest replays a single trace on the service under test. NOTE: this does not invoke the OnTestCompleted callback. It is the responsibility of the caller to invoke it.

func (*Executor) RunTests 

func (e *Executor) RunTests(tests []Test) ([]TestResult, error)

func (*Executor) RunTestsConcurrently 

func (e *Executor) RunTestsConcurrently(tests []Test, maxConcurrency int) ([]TestResult, error)

RunTestsConcurrently executes tests in parallel with the specified concurrency limit This is now used internally by the resilience logic

func (*Executor) SetAllowSuiteWideMatching 

func (e *Executor) SetAllowSuiteWideMatching(enabled bool)

func (*Executor) SetConcurrency 

func (e *Executor) SetConcurrency(concurrency int)

SetConcurrency sets the maximum number of concurrent tests

func (*Executor) SetCoverageBaseline added in v0.2.12 

func (e *Executor) SetCoverageBaseline(baseline CoverageSnapshot)

SetCoverageBaseline merges new baseline data into the existing baseline. Called per environment group - accumulates across service restarts.

func (*Executor) SetCoverageEnabled added in v0.2.12 

func (e *Executor) SetCoverageEnabled(enabled bool)

func (*Executor) SetCoverageExcludePatterns added in v0.2.12 

func (e *Executor) SetCoverageExcludePatterns(patterns []string)

func (*Executor) SetCoverageIncludePatterns added in v0.2.12 

func (e *Executor) SetCoverageIncludePatterns(patterns []string)

func (*Executor) SetCoverageOutputPath added in v0.2.12 

func (e *Executor) SetCoverageOutputPath(path string)

func (*Executor) SetCoverageStripPrefix added in v0.2.12 

func (e *Executor) SetCoverageStripPrefix(prefix string)

func (*Executor) SetDebug 

func (e *Executor) SetDebug(debug bool)

SetDebug enables debug mode for fence sandbox

func (*Executor) SetEnableServiceLogs 

func (e *Executor) SetEnableServiceLogs(enable bool)

SetDisableServiceLogs sets whether service logging should be disabled

func (*Executor) SetGlobalSpans 

func (e *Executor) SetGlobalSpans(spans []*core.Span)

func (*Executor) SetOnTestCompleted 

func (e *Executor) SetOnTestCompleted(callback func(TestResult, Test))

func (*Executor) SetReplayEnvVars 

func (e *Executor) SetReplayEnvVars(envVars map[string]string)

SetReplayEnvVars configures environment variables to inject into the replay service subprocess. This does not mutate the CLI process environment.

func (*Executor) SetReplaySandboxConfigPath 

func (e *Executor) SetReplaySandboxConfigPath(path string)

SetReplaySandboxConfigPath configures an optional user-provided sandbox config to merge with the built-in replay sandbox policy.

func (*Executor) SetResultsOutput 

func (e *Executor) SetResultsOutput(dir string)

func (*Executor) SetSandboxMode 

func (e *Executor) SetSandboxMode(mode string) error

SetSandboxMode configures replay sandbox behavior. Supported values: auto, strict, off.

func (*Executor) SetShowCoverage added in v0.2.12 

func (e *Executor) SetShowCoverage(show bool)

func (*Executor) SetSuiteSpans 

func (e *Executor) SetSuiteSpans(spans []*core.Span)

func (*Executor) SetTestCoverageDetail added in v0.2.12 

func (e *Executor) SetTestCoverageDetail(testID string, detail map[string]CoverageFileDiff)

SetTestCoverageDetail stores per-test coverage diff for display in TUI/print.

func (*Executor) SetTestTimeout 

func (e *Executor) SetTestTimeout(timeout time.Duration)

func (*Executor) StartEnvironment 

func (e *Executor) StartEnvironment() error

StartEnvironment starts the mock server and service, then waits for the SDK ack. It performs best-effort cleanup on failure.

func (*Executor) StartServer 

func (e *Executor) StartServer() error

StartServer initializes and starts the mock server

func (*Executor) StartService 

func (e *Executor) StartService() error

func (*Executor) StopEnvironment 

func (e *Executor) StopEnvironment() error

StopEnvironment stops the service and mock server (best effort).

func (*Executor) StopServer 

func (e *Executor) StopServer() error

func (*Executor) StopService 

func (e *Executor) StopService() error

func (*Executor) TakeCoverageBaseline added in v0.2.12 

func (e *Executor) TakeCoverageBaseline() (CoverageSnapshot, error)

TakeCoverageBaseline calls the SDK's coverage snapshot endpoint with ?baseline=true. Returns ALL coverable lines (including uncovered at count=0) for the aggregate denominator. Retries briefly since the coverage server may not be ready immediately after service start. In practice, the SDK initializes coverage before the HTTP server starts, so the baseline should succeed on the first attempt.

func (*Executor) TakeCoverageSnapshot added in v0.2.12 

func (e *Executor) TakeCoverageSnapshot() (CoverageSnapshot, error)

TakeCoverageSnapshot calls the SDK's coverage snapshot endpoint. Returns per-file coverage data for this test only (counters auto-reset).

func (*Executor) WaitForSDKAcknowledgement 

func (e *Executor) WaitForSDKAcknowledgement() error

WaitForSDKAcknowledgement waits for the SDK to acknowledge the connection.

func (*Executor) WaitForSpanData 

func (e *Executor) WaitForSpanData(traceID string, timeout time.Duration)

WaitForSpanData blocks briefly until inbound or match events are recorded for a test

func (*Executor) WriteRunResultsToFile 

func (e *Executor) WriteRunResultsToFile(tests []Test, results []TestResult) (string, error)

type FileCoverageData added in v0.2.12 

type FileCoverageData struct {
	Lines           map[string]int        `json:"lines"`
	TotalBranches   int                   `json:"total_branches"`
	CoveredBranches int                   `json:"covered_branches"`
	Branches        map[string]BranchInfo `json:"branches,omitempty"`
}

FileCoverageData is the internal representation of per-file coverage.

type MatchEvent 

type MatchEvent struct {
	SpanID     string           `json:"spanId"`
	MatchLevel *core.MatchLevel `json:"matchLevel"`
	StackTrace string           `json:"stackTrace"`
	InputData  map[string]any   `json:"inputData,omitempty"`
	Timestamp  time.Time        `json:"timestamp"`
	ReplaySpan *core.Span       `json:"replaySpan,omitempty"`
}

type MessageType 

type MessageType string

MessageType represents the type of message sent by the SDK 

const (
	MessageTypeSDKConnect  MessageType = "sdk_connect"
	MessageTypeMockRequest MessageType = "mock_request"
)

type MockMatcher 

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

func NewMockMatcher 

func NewMockMatcher(server *Server) *MockMatcher

func (*MockMatcher) FindBestMatchAcrossTraces 

func (mm *MockMatcher) FindBestMatchAcrossTraces(req *core.GetMockRequest, traceID string, spans []*core.Span) (*core.Span, *core.MatchLevel, error)

FindBestMatchInSpans implements the priority matching algorithm for spans across a test suite

func (*MockMatcher) FindBestMatchWithTracePriority 

func (mm *MockMatcher) FindBestMatchWithTracePriority(req *core.GetMockRequest, traceID string) (*core.Span, *core.MatchLevel, error)

FindBestMatchWithTracePriority implements the priority matching algorithm. It first searches the current trace (Priorities 1-4), then checks suite-wide by value hash (Priorities 5-6), then falls back to schema-based matching in the current trace (Priorities 7-10).

type MockMatcherRequestData 

type MockMatcherRequestData struct {
	InputValue      any
	InputValueHash  string
	InputSchema     *core.JsonSchema
	InputSchemaHash string
}

type MockNotFoundEvent 

type MockNotFoundEvent struct {
	PackageName string     `json:"packageName"`
	SpanName    string     `json:"spanName"`   // e.g., "GET /api/users" or "pg.query"
	Operation   string     `json:"operation"`  // "GET", "POST", "query", etc.
	StackTrace  string     `json:"stackTrace"` // Code location that made the call
	Timestamp   time.Time  `json:"timestamp"`
	Error       string     `json:"error"`      // Full error message
	ReplaySpan  *core.Span `json:"replaySpan"` // The outbound span that failed to find a mock
}

type Request 

type Request struct {
	Method  string            `json:"method"`
	Path    string            `json:"path"`
	Headers map[string]string `json:"headers"`
	Body    any               `json:"body,omitempty"`
}

type Response 

type Response struct {
	Status  int               `json:"status"`
	Headers map[string]string `json:"headers"`
	Body    any               `json:"body,omitempty"`
}

type SemVer 

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

type Server 

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

Server handles Unix socket communication with the SDK

func NewServer 

func NewServer(serviceID string, cfg *config.ServiceConfig) (*Server, error)

NewServer creates a new server instance

func (*Server) AllowSuiteWideMatching 

func (ms *Server) AllowSuiteWideMatching() bool

func (*Server) CleanupTraceSpans 

func (ms *Server) CleanupTraceSpans(traceID string)

func (*Server) GetAnalyticsClient 

func (ms *Server) GetAnalyticsClient() *analytics.Client

GetAnalyticsClient returns the analytics client, initializing it lazily if needed

func (*Server) GetCommunicationType 

func (ms *Server) GetCommunicationType() CommunicationType

func (*Server) GetConnectionInfo 

func (ms *Server) GetConnectionInfo() (string, int)

func (*Server) GetGlobalSpansByReducedValueHash 

func (ms *Server) GetGlobalSpansByReducedValueHash(reducedHash string) []*core.Span

func (*Server) GetGlobalSpansByValueHash 

func (ms *Server) GetGlobalSpansByValueHash(valueHash string) []*core.Span

func (*Server) GetInboundReplaySpan 

func (ms *Server) GetInboundReplaySpan(traceID string) *core.Span

func (*Server) GetMatchEvents 

func (ms *Server) GetMatchEvents(traceID string) []MatchEvent

func (*Server) GetMockNotFoundEvents 

func (ms *Server) GetMockNotFoundEvents(traceID string) []MockNotFoundEvent

func (*Server) GetRootSpanID 

func (ms *Server) GetRootSpanID(traceID string) string

func (*Server) GetSDKRuntime 

func (ms *Server) GetSDKRuntime() core.Runtime

GetSDKRuntime returns the runtime of the connected SDK

func (*Server) GetSDKVersion 

func (ms *Server) GetSDKVersion() string

func (*Server) GetSocketPath 

func (ms *Server) GetSocketPath() string

func (*Server) GetSpansByPackageForTrace 

func (ms *Server) GetSpansByPackageForTrace(traceID string, packageName string) []*core.Span

func (*Server) GetSpansByReducedValueHashForTrace 

func (ms *Server) GetSpansByReducedValueHashForTrace(traceID string, reducedHash string) []*core.Span

func (*Server) GetSpansByValueHashForTrace 

func (ms *Server) GetSpansByValueHashForTrace(traceID string, valueHash string) []*core.Span

func (*Server) GetSuiteSpans 

func (ms *Server) GetSuiteSpans() []*core.Span

func (*Server) GetSuiteSpansByPackage 

func (ms *Server) GetSuiteSpansByPackage(packageName string) []*core.Span

func (*Server) GetSuiteSpansByReducedSchemaHash 

func (ms *Server) GetSuiteSpansByReducedSchemaHash(reducedSchemaHash string) []*core.Span

func (*Server) GetSuiteSpansByReducedValueHash 

func (ms *Server) GetSuiteSpansByReducedValueHash(reducedHash string) []*core.Span

func (*Server) GetSuiteSpansBySchemaHash 

func (ms *Server) GetSuiteSpansBySchemaHash(schemaHash string) []*core.Span

func (*Server) GetSuiteSpansByValueHash 

func (ms *Server) GetSuiteSpansByValueHash(valueHash string) []*core.Span

func (*Server) HasMockNotFoundEvents 

func (ms *Server) HasMockNotFoundEvents(traceID string) bool

func (*Server) LoadSpansForTrace 

func (ms *Server) LoadSpansForTrace(traceID string, spans []*core.Span)

LoadSpansForTrace loads all spans for matching

func (*Server) SendCoverageSnapshot added in v0.2.12 

func (ms *Server) SendCoverageSnapshot(baseline bool) (*core.CoverageSnapshotResponse, error)

SendCoverageSnapshot sends a coverage snapshot request to the SDK and waits for the response. Returns per-file coverage data. If baseline=true, includes all coverable lines (count=0 for uncovered).

func (*Server) SendSetTimeTravel 

func (ms *Server) SendSetTimeTravel(timestampSeconds float64, traceID string, timestampSource string) error

SendSetTimeTravel sends a time travel request to the SDK and waits for acknowledgement

func (*Server) SetAllowSuiteWideMatching 

func (ms *Server) SetAllowSuiteWideMatching(enabled bool)

func (*Server) SetCurrentTestID 

func (ms *Server) SetCurrentTestID(id string)

func (*Server) SetGlobalSpans 

func (ms *Server) SetGlobalSpans(spans []*core.Span)

SetGlobalSpans sets the global spans (explicitly marked is_global=true) and builds indexes

func (*Server) SetSuiteSpans 

func (ms *Server) SetSuiteSpans(spans []*core.Span)

func (*Server) Start 

func (ms *Server) Start() error

Start begins listening (Unix socket or TCP)

func (*Server) Stop 

func (ms *Server) Stop() error

Stop shuts down the mock server

func (*Server) WaitForInboundSpan 

func (ms *Server) WaitForInboundSpan(traceID string, timeout time.Duration)

func (*Server) WaitForSDKConnection 

func (ms *Server) WaitForSDKConnection(timeout time.Duration) error

func (*Server) WaitForSpanData 

func (ms *Server) WaitForSpanData(traceID string, timeout time.Duration)

type SuiteSpanOptions 

type SuiteSpanOptions struct {
	// Cloud options
	IsCloudMode bool
	Client      *api.TuskClient
	AuthOptions api.AuthOptions
	ServiceID   string
	TraceTestID string

	// Local options
	Interactive bool // Whether to log errors interactively
	Quiet       bool // Whether to suppress progress messages (only works with --print)

	// AllowSuiteWideMatching allows matching against all suite spans (for main branch validation or local runs)
	// When false (normal cloud replay), only global spans are loaded for cross-trace matching
	AllowSuiteWideMatching bool

	// PreloadedPreAppStartSpans allows passing pre-fetched pre-app-start spans to avoid fetching again
	PreloadedPreAppStartSpans []*core.Span

	// PreloadedGlobalSpans allows passing pre-fetched global spans to avoid fetching again
	PreloadedGlobalSpans []*core.Span
}

SuiteSpanOptions contains options for building suite spans

type Test 

type Test struct {
	FileName    string         `json:"file_name"`
	TraceID     string         `json:"trace_id"`
	TraceTestID string         `json:"trace_test_id,omitempty"`
	Spans       []*core.Span   `json:"-"`
	Environment string         `json:"environment,omitempty"` // Environment extracted from span
	Type        string         `json:"type"`                  // Used for test execution
	DisplayType string         `json:"display_type"`          // Used for CLI display
	Timestamp   string         `json:"timestamp"`
	Method      string         `json:"method"`
	Path        string         `json:"path"`         // Used for test execution
	DisplayName string         `json:"display_name"` // Used for CLI display
	Status      string         `json:"status"`
	SuiteStatus string         `json:"suite_status,omitempty"` // Cloud only: "draft", "in_suite"
	Duration    int            `json:"duration"`
	Metadata    map[string]any `json:"metadata"`
	Request     Request        `json:"request"`
	Response    Response       `json:"response"`
}

func ConvertTraceTestToRunnerTest 

func ConvertTraceTestToRunnerTest(tt *backend.TraceTest) Test

ConvertTraceTestToRunnerTest converts a single protobuf TraceTest to runner.Test

func ConvertTraceTestsToRunnerTests 

func ConvertTraceTestsToRunnerTests(traceTests []*backend.TraceTest) []Test

ConvertTraceTestsToRunnerTests converts protobuf TraceTests to runner.Tests

func FilterLocalTestsForExecution 

func FilterLocalTestsForExecution(tests []Test) (testsToExecute []Test, excludedCount int)

FilterLocalTestsForExecution filters out local tests with HTTP status >= 300. These tests are skipped for replay but their spans remain available for mock matching. Returns (testsToExecute, excludedCount).

func FilterTests 

func FilterTests(tests []Test, pattern string) ([]Test, error)

type TestResult 

type TestResult struct {
	TestID            string      `json:"test_id"`
	Passed            bool        `json:"passed"`
	Cancelled         bool        `json:"cancelled"`
	CrashedServer     bool        `json:"crashed_server,omitempty"`      // Test caused server to crash
	RetriedAfterCrash bool        `json:"retried_after_crash,omitempty"` // Test was retried after batch crash
	Duration          int         `json:"duration"`                      // In milliseconds
	Deviations        []Deviation `json:"deviations,omitempty"`
	Error             string      `json:"error,omitempty"`
}

func ReplayTestsByEnvironment 

func ReplayTestsByEnvironment(
	ctx context.Context,
	executor *Executor,
	groups []*EnvironmentGroup,
) ([]TestResult, error)

ReplayTestsByEnvironment orchestrates environment-based test replay For each environment group:

  1. Configure replay environment variables for the service subprocess
  2. Start environment (server + service)
  3. Run tests for that environment
  4. Stop environment
  5. Clear replay environment variable configuration

type Trace 

type Trace struct {
	ID        string       `json:"id"`
	Filename  string       `json:"filename"`
	Timestamp string       `json:"timestamp"`
	Spans     []*core.Span `json:"spans"`
}

type ValidateExecutor 

type ValidateExecutor struct {
	*Executor
}

ValidateExecutor wraps Executor with validation-specific behavior Note: With the new validation flow, most logic is handled by the regular Executor and the backend processes results to curate the test suite

func NewValidateExecutor 

func NewValidateExecutor(base *Executor) *ValidateExecutor

NewValidateExecutor creates a new ValidateExecutor wrapping the given Executor

func (*ValidateExecutor) ValidateDraftTraces 

func (ve *ValidateExecutor) ValidateDraftTraces(ctx context.Context, tests []Test) ([]ValidationResult, error)

ValidateDraftTraces runs validation for all draft traces Returns partial results if context is cancelled (workflow timeout) Note: This is retained for backwards compatibility but the new validation flow uses executor.RunTests directly with result uploads

type ValidationResult 

type ValidationResult struct {
	TraceID       string
	TraceTestID   string
	Passed        bool
	FailureReason string
	Duration      time.Duration
}

ValidationResult represents the result of validating a trace on main Note: GlobalSpanIDs is no longer tracked here - backend handles global span detection via TraceTestSpanResult.matchedDbSpanRecordingId

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.