Documentation
¶
Index ¶
- Constants
- Variables
- func BuildBatchServer(sandboxDir string, info *BatchServerInfo) error
- func BuildServiceServer(sandboxDir, serviceName string) (string, error)
- func CleanupSandbox() error
- func CollectSpecs(t *testing.T, specPaths []string) []string
- func CountServiceLOC(serviceName, sandboxDir string) int
- func CreateSandbox() (string, error)
- func FilterSpecsBySize(specs []string, maxBytes int64) ([]string, int)
- func IsServiceSetup(serviceName, sandboxDir string) bool
- func NormalizeSpecPath(specPath string) string
- func ReadSpecFileWithBaseDir(specPath, baseDir string) ([]byte, error)
- func ReportResults(t *testing.T, results []IntegrationResult, ...)
- func RunGoGenerate(sandboxDir, serviceName string, timeout time.Duration) error
- func RunPipeline(batches [][]string, cfg *PipelineConfig) ([]IntegrationResult, map[string]*ServiceStats, time.Duration, *BatchStats)
- func SetSpecsFS(fs embed.FS)
- func SetupSandbox(sandboxDir string) error
- func SetupService(specFile, sandboxDir string, opts *RuntimeOptions) (string, error)
- func ShouldCleanSandbox() bool
- func SplitIntoBatches(specs []string, targetBytes int64) [][]string
- func StopServiceServer(proc *ServerProcess)
- func WaitForServer(serverURL string, maxWait time.Duration, proc *ServerProcess, ...) error
- type BatchServerInfo
- type BatchStats
- type CacheEntry
- type FailedSpec
- type IntegrationResult
- type PipelineConfig
- type PreparedBatch
- type ResultCache
- func (c *ResultCache) Clear() error
- func (c *ResultCache) FilterUncached(specs []string) []string
- func (c *ResultCache) IsCached(specPath string) bool
- func (c *ResultCache) MarkFailed(specPath string)
- func (c *ResultCache) MarkPassed(specPath string)
- func (c *ResultCache) Save() error
- func (c *ResultCache) Size() int
- type RuntimeOptions
- type ServerProcess
- type ServiceStats
- type ServiceTestResult
Constants ¶
const ( ServerPort = 18123 ServerReadyTimeout = 90 * time.Second // 90s for large batches on slower machines // GenServiceBinaryPath is the relative path to the pre-built gen-service binary within sandbox GenServiceBinaryPath = ".build/bin/gen-service" )
const (
// CacheFileName is the name of the cache file
CacheFileName = ".integration-cache.json"
)
const (
// MaxErrorMessageLength is the maximum length of error messages in results
MaxErrorMessageLength = 2000
)
const (
// SandboxDir is the directory where all test artifacts are created
SandboxDir = ".sandbox"
)
const (
// ServiceGenerateFile is the name of the file that contains go:generate directive
ServiceGenerateFile = "generate.go"
)
Variables ¶
var ( // HTTPClient is shared client for all requests. // 10s timeout to handle complex schemas that take longer to generate. HTTPClient = &http.Client{ Timeout: 30 * time.Second, } HealthEndpoint = "/healthz" )
var ( // ServiceResourcesEndpoint is the endpoint to get service routes // Format: /.services/<service-name> ServiceResourcesEndpoint = "/.services/%s" )
Functions ¶
func BuildBatchServer ¶
func BuildBatchServer(sandboxDir string, info *BatchServerInfo) error
BuildBatchServer builds the batch server binary
func BuildServiceServer ¶
BuildServiceServer builds the server binary for a single service
func CollectSpecs ¶
CollectSpecs collects all spec files to process based on provided paths
func CountServiceLOC ¶
CountServiceLOC counts lines of code for a service's generated code (gen.go)
func CreateSandbox ¶
CreateSandbox creates the sandbox directory. Returns an absolute path to the sandbox directory.
func FilterSpecsBySize ¶
FilterSpecsBySize filters out specs larger than maxBytes. Returns filtered specs and count of excluded specs.
func IsServiceSetup ¶
IsServiceSetup checks if a service has been set up (has generate.go in service root)
func NormalizeSpecPath ¶
NormalizeSpecPath normalizes a spec path to a canonical absolute path. This ensures consistent cache keys regardless of how the spec path was provided (e.g., "3.0/aws/foo.yml" vs "testdata/specs/3.0/aws/foo.yml" vs absolute path).
func ReadSpecFileWithBaseDir ¶
ReadSpecFileWithBaseDir reads a spec file from various locations with a custom base directory Exported so it can be used from the root integration test
func ReportResults ¶
func ReportResults(t *testing.T, results []IntegrationResult, serviceStatsMap map[string]*ServiceStats, totalBuildTime time.Duration, batchStats ...*BatchStats)
ReportResults prints a summary of test results
func RunGoGenerate ¶ added in v2.1.0
RunGoGenerate runs go generate for a service with a timeout. This regenerates the service code including server/main.go.
func RunPipeline ¶
func RunPipeline(batches [][]string, cfg *PipelineConfig) ([]IntegrationResult, map[string]*ServiceStats, time.Duration, *BatchStats)
RunPipeline runs batches with parallel builds: Multiple batches can be built simultaneously, then tested as they complete Returns results, service stats, total build time, and batch stats
func SetSpecsFS ¶
SetSpecsFS sets the embedded filesystem (called from root test)
func SetupSandbox ¶
SetupSandbox copies necessary files to the sandbox directory
func SetupService ¶
func SetupService(specFile, sandboxDir string, opts *RuntimeOptions) (string, error)
SetupService runs gen-service for a single spec (creates setup dir and generates service) Returns the service name
func ShouldCleanSandbox ¶
func ShouldCleanSandbox() bool
ShouldCleanSandbox determines whether the sandbox should be cleaned. Returns true if: - CLEAN_SANDBOX env var is set (forced clean) - There are uncommitted git changes (source code modified) - Git command fails (assume dirty to be safe)
func SplitIntoBatches ¶
SplitIntoBatches splits specs into batches based on target size in bytes. Each batch will contain specs until either target size or max files is reached. Large files (>= 50% of target) get their own batch for isolation.
func StopServiceServer ¶
func StopServiceServer(proc *ServerProcess)
StopServiceServer stops a service's server
func WaitForServer ¶
func WaitForServer(serverURL string, maxWait time.Duration, proc *ServerProcess, isInterrupted ...func() bool) error
WaitForServer waits for the server to be ready. If proc is provided, it will fail fast if the process exits.
Types ¶
type BatchServerInfo ¶
BatchServerInfo holds info about a built batch server
func GenerateBatchServer ¶
func GenerateBatchServer(sandboxDir string, batchID int, serviceNames []string) (*BatchServerInfo, error)
GenerateBatchServer generates a main.go that imports all services in the batch
type BatchStats ¶
BatchStats holds timing statistics for batches
func (*BatchStats) AvgBuildTime ¶
func (b *BatchStats) AvgBuildTime() time.Duration
AvgBuildTime returns average batch build time
func (*BatchStats) AvgTestTime ¶
func (b *BatchStats) AvgTestTime() time.Duration
AvgTestTime returns average batch test time
type CacheEntry ¶
CacheEntry represents a cached test result
type FailedSpec ¶
FailedSpec represents a spec that failed during batch preparation
type IntegrationResult ¶
type IntegrationResult struct {
Spec string
Path string
OperationID string
Method string
Ok bool
StatusCode int
GenerateErr string
Validated bool
ValidationMethod string
BatchID int // Batch number (0 = individual mode)
}
IntegrationResult represents the result of testing a single endpoint
func TestService ¶
func TestService(specFile, serverURL string) ([]IntegrationResult, int, int)
TestService tests a single generated service against the running server Returns: results, total endpoint count, tested endpoint count
type PipelineConfig ¶
type PipelineConfig struct {
SandboxDir string
RuntimeOpts *RuntimeOptions
BasePort int
MaxFails int
TotalSpecs int
TotalBatches int
OnResult func(result IntegrationResult, stats *ServiceStats, completed, total int)
OnBatchStart func(batchID, totalBatches, servicesInBatch int, batchSizeBytes int64)
OnBatchDone func(batchID, totalBatches, servicesInBatch int, buildTime, testTime time.Duration)
// OnBatchPhase is called when a batch phase starts/ends (phase: "setup", "build")
OnBatchPhase func(batchID int, phase string, done bool, elapsed time.Duration)
// InterruptCh is an optional channel that signals when to abort and report partial results
InterruptCh <-chan struct{}
// Cache is an optional result cache to skip previously passing specs
Cache *ResultCache
// BatchPrepTimeout is the maximum time allowed for batch preparation (setup + build + server start)
// Default: 5 minutes
BatchPrepTimeout time.Duration
}
PipelineConfig holds configuration for the pipeline
type PreparedBatch ¶
type PreparedBatch struct {
Info *BatchServerInfo
ServerProc *ServerProcess
ServerURL string
Port int
Specs []string // Original spec paths for this batch
Error error // Error during preparation (only set if entire batch failed)
FailedSpecs []FailedSpec // Services that failed during setup/generate (batch continues with rest)
BuildTime time.Duration // Time spent building this batch
BatchID int
}
PreparedBatch represents a batch that's ready to test
type ResultCache ¶
type ResultCache struct {
Entries map[string]CacheEntry `json:"entries"` // key is spec path
// contains filtered or unexported fields
}
ResultCache manages cached test results
func NewResultCache ¶
func NewResultCache(cacheDir string) (*ResultCache, error)
NewResultCache creates or loads a cache from the given directory
func (*ResultCache) FilterUncached ¶
func (c *ResultCache) FilterUncached(specs []string) []string
FilterUncached returns only specs that are not cached as passing
func (*ResultCache) IsCached ¶
func (c *ResultCache) IsCached(specPath string) bool
IsCached checks if a spec has a valid cached passing result
func (*ResultCache) MarkFailed ¶
func (c *ResultCache) MarkFailed(specPath string)
MarkFailed removes a spec from the cache (so it will be retested)
func (*ResultCache) MarkPassed ¶
func (c *ResultCache) MarkPassed(specPath string)
MarkPassed marks a spec as passing
func (*ResultCache) Size ¶
func (c *ResultCache) Size() int
Size returns the number of cached entries
type RuntimeOptions ¶
type RuntimeOptions struct {
CodegenConfigPath string `env:"CODEGEN_CONFIG"`
ServiceConfigPath string `env:"SERVICE_CONFIG"`
SpecsBaseDir string `env:"SPECS_BASE_DIR"`
MaxConcurrency int `env:"MAX_CONCURRENCY" envDefault:"8"`
BatchSizeMB int `env:"BATCH_SIZE_MB" envDefault:"6"`
BatchConcurrency int `env:"BATCH_CONCURRENCY" envDefault:"2"`
MaxSpecSizeMB int `env:"MAX_SPEC_SIZE_MB" envDefault:"10"`
SimplifyThresholdMB int `env:"SIMPLIFY_THRESHOLD_MB" envDefault:"3"`
ServiceGenerateTimeout time.Duration `env:"SERVICE_GENERATE_TIMEOUT" envDefault:"5m"`
NoCache bool `env:"NO_CACHE" envDefault:"false"`
ClearCache bool `env:"CLEAR_CACHE" envDefault:"false"`
MaxFails int `env:"MAX_FAILS" envDefault:"500"`
RandomSpecs int `env:"RANDOM_SPECS" envDefault:"0"`
// Computed fields (not from env)
BatchSizeBytes int64
MaxSpecSizeBytes int64
SimplifyThresholdBytes int64
}
RuntimeOptions contains runtime configuration for integration tests. All fields contain final computed values with defaults applied. Use NewRuntimeOptionsFromEnv() to create with values from .env.dist, .env, and environment.
func NewRuntimeOptionsFromEnv ¶
func NewRuntimeOptionsFromEnv() *RuntimeOptions
NewRuntimeOptionsFromEnv creates RuntimeOptions populated from: 1. .env.dist (defaults) 2. .env (overrides .env.dist, if exists) 3. Environment variables (final overrides - command line takes precedence)
type ServerProcess ¶
type ServerProcess struct {
Cmd *exec.Cmd
Stdout *bytes.Buffer
Stderr *bytes.Buffer
// contains filtered or unexported fields
}
StartServiceServer starts a service's server on the given port ServerProcess wraps exec.Cmd with captured output
func StartServiceServer ¶
func StartServiceServer(serverBin, sandboxDir string, port int) (*ServerProcess, error)
func (*ServerProcess) GetStderr ¶
func (s *ServerProcess) GetStderr() string
GetStderr returns captured stderr (useful for debugging failed servers)
func (*ServerProcess) MarkWaited ¶
func (s *ServerProcess) MarkWaited()
MarkWaited marks the process as already waited on
func (*ServerProcess) WasWaited ¶
func (s *ServerProcess) WasWaited() bool
WasWaited returns true if Wait() was already called
type ServiceStats ¶
type ServiceStats struct {
Name string
Endpoints int
Tested int
Success int
Fails int
LOC int
TTE time.Duration // Time To Execute (test execution)
}
ServiceStats holds statistics for a single service
type ServiceTestResult ¶
type ServiceTestResult struct {
Spec string
Results []IntegrationResult
TotalEndpoints int
TestedEndpoints int
TestDuration float64 // Test execution time in seconds
}
ServiceTestResult represents the results of testing a single service