runner

package
v1.2.23 Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2025 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Index

Constants

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

Restart constants

Variables

This section is empty.

Functions

func BuildSuiteSpansForRun added in v0.1.4 

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

BuildSuiteSpansForRun builds the suite spans for the run. If running a single cloud trace test, eager-fetch all suite spans to enable cross-suite matching. Returns the suite spans, the number of pre-app-start spans, and the number of unique traces.

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 added in v0.1.6 

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 added in v0.1.4 

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

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

func FetchLocalPreAppStartSpans added in v0.1.4 

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

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

func FetchPreAppStartSpansFromCloud added in v0.1.4 

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 OutputResultsSummary added in v0.1.13 

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

func OutputSingleResult added in v0.1.13 

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

func PrepareAndSetSuiteSpans added in v0.1.4 

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 SetEnvironmentVariables added in v0.1.22 

func SetEnvironmentVariables(envVars map[string]string) (cleanup func(), err error)

SetEnvironmentVariables applies env vars to current process Returns cleanup function to restore original values

func UpdateDriftRunCIStatusWrapper added in v0.1.20 

func UpdateDriftRunCIStatusWrapper(
	ctx context.Context,
	client *api.TuskClient,
	driftRunID string,
	authOptions api.AuthOptions,
	results []TestResult,
) error

func UploadSingleTestResult 

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

Types

type CommunicationType added in v0.1.6 

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

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 added in v0.1.22 

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 added in v0.1.22 

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 added in v0.1.22 

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) CancelTests added in v0.1.13 

func (e *Executor) CancelTests()

func (*Executor) CheckServerHealth added in v0.1.20 

func (e *Executor) CheckServerHealth() bool

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

func (*Executor) ForceStopEnvironment added in v0.1.20 

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) GetConcurrency 

func (e *Executor) GetConcurrency() int

GetConcurrency returns the current concurrency setting

func (*Executor) GetServer added in v0.1.1 

func (e *Executor) GetServer() *Server

GetServer returns the server instance

func (*Executor) GetServiceLogPath 

func (e *Executor) GetServiceLogPath() string

func (*Executor) GetStartupFailureHelpMessage added in v0.1.9 

func (e *Executor) GetStartupFailureHelpMessage() string

GetStartupFailureHelpMessage returns a user-friendly help message when the service fails to start. It explains how to use --enable-service-logs and shows where logs will be saved.

func (*Executor) GetSuiteSpans added in v0.1.22 

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

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

func (*Executor) IsServiceLogsEnabled added in v0.1.9 

func (e *Executor) IsServiceLogsEnabled() bool

func (*Executor) LoadSpansForTrace 

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

func (*Executor) LoadTestsFromFolder 

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

func (*Executor) LoadTestsFromTraceFile 

func (e *Executor) LoadTestsFromTraceFile(path string) ([]Test, error)

LoadTestsFromTraceFile loads all tests from a trace file

func (*Executor) RestartServerWithRetry added in v0.1.20 

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

RestartServerWithRetry attempts to restart the server with exponential backoff

func (*Executor) RunBatchSequentialWithCrashHandling added in v0.1.20 

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 added in v0.1.20 

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) SetConcurrency 

func (e *Executor) SetConcurrency(concurrency int)

SetConcurrency sets the maximum number of concurrent tests

func (*Executor) SetEnableServiceLogs 

func (e *Executor) SetEnableServiceLogs(enable bool)

SetDisableServiceLogs sets whether service logging should be disabled

func (*Executor) SetOnTestCompleted 

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

func (*Executor) SetResultsOutput 

func (e *Executor) SetResultsOutput(dir string)

func (*Executor) SetSuiteSpans 

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

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) 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 MatchEvent 

type MatchEvent struct {
	SpanID     string              `json:"spanId"`
	MatchLevel *backend.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, *backend.MatchLevel, error)

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

func (*MockMatcher) FindBestMatchInTrace 

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

FindBestMatch implements the priority matching algorithm for spans within a trace

type MockMatcherRequestData 

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

type MockNotFoundEvent added in v0.1.1 

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) CleanupTraceSpans added in v0.1.14 

func (ms *Server) CleanupTraceSpans(traceID string)

func (*Server) GetAnalyticsClient added in v0.1.23 

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

GetAnalyticsClient returns the analytics client, initializing it lazily if needed

func (*Server) GetCommunicationType added in v0.1.6 

func (ms *Server) GetCommunicationType() CommunicationType

func (*Server) GetConnectionInfo added in v0.1.6 

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

func (*Server) GetInboundReplaySpan 

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

func (*Server) GetMatchEvents 

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

func (*Server) GetMockNotFoundEvents added in v0.1.1 

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

func (*Server) GetRootSpanID 

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

func (*Server) GetSDKVersion 

func (ms *Server) GetSDKVersion() string

func (*Server) GetSocketPath 

func (ms *Server) GetSocketPath() string

func (*Server) GetSpansByPackageForTrace added in v0.1.14 

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

func (*Server) GetSpansByReducedValueHashForTrace added in v0.1.14 

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

func (*Server) GetSpansByValueHashForTrace added in v0.1.14 

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

func (*Server) GetSuiteSpans 

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

func (*Server) GetSuiteSpansByPackage added in v0.1.14 

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

func (*Server) GetSuiteSpansByReducedSchemaHash added in v0.1.21 

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

func (*Server) GetSuiteSpansByReducedValueHash added in v0.1.14 

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

func (*Server) GetSuiteSpansBySchemaHash added in v0.1.21 

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

func (*Server) GetSuiteSpansByValueHash added in v0.1.14 

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

func (*Server) HasMockNotFoundEvents added in v0.1.1 

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) SetCurrentTestID 

func (ms *Server) SetCurrentTestID(id string)

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 added in v0.1.4 

type SuiteSpanOptions struct {
	// Cloud options
	IsCloudMode bool
	Client      *api.TuskClient
	AuthOptions api.AuthOptions
	ServiceID   string
	TraceTestID string // If set, fetch all suite spans for cross-suite matching

	// Local options
	AllTests    []Test // All tests loaded (for extracting spans)
	Interactive bool   // Whether to log errors interactively
	Quiet       bool   // Whether to suppress progress messages (only works with --print)
}

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"`
	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 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 added in v0.1.22 

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

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

  1. Set environment variables
  2. Start environment (server + service)
  3. Run tests for that environment
  4. Stop environment
  5. Restore environment variables

type Trace 

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

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.