soltesting

type Assertion struct {
	// Expression is a CEL expression evaluating to bool.
	Expression celexp.Expression `json:"expression,omitempty" yaml:"expression,omitempty" doc:"CEL expression evaluating to bool"`

	// Regex is a regex pattern that must match somewhere in the target text.
	Regex string `json:"regex,omitempty" yaml:"regex,omitempty" doc:"Regex pattern that must match" maxLength:"1000"`

	// Contains is a substring that must appear in the target text.
	Contains string `json:"contains,omitempty" yaml:"contains,omitempty" doc:"Substring that must appear" maxLength:"5000"`

	// NotRegex is a regex pattern that must NOT match anywhere in the target text.
	NotRegex string `json:"notRegex,omitempty" yaml:"notRegex,omitempty" doc:"Regex pattern that must NOT match" maxLength:"1000"`

	// NotContains is a substring that must NOT appear in the target text.
	NotContains string `json:"notContains,omitempty" yaml:"notContains,omitempty" doc:"Substring that must NOT appear" maxLength:"5000"`

	// Target specifies which output stream to match against: stdout (default), stderr, or combined.
	// Only applies to regex, contains, notRegex, notContains.
	// CEL expressions access both via context variables.
	Target string `` /* 227-byte string literal not displayed */

	// Message is a custom failure message (optional).
	Message string `json:"message,omitempty" yaml:"message,omitempty" doc:"Custom failure message" maxLength:"1000"`
}

type AssertionResult struct {
	// Type is the assertion type (expression, regex, contains, notRegex, notContains).
	Type string `json:"type"`
	// Input is the assertion input (expression string, regex pattern, or substring).
	Input string `json:"input"`
	// Passed indicates whether the assertion passed.
	Passed bool `json:"passed"`
	// Message is the failure diagnostic message.
	Message string `json:"message,omitempty"`
	// Actual is the actual value encountered (for diagnostics).
	Actual any `json:"actual,omitempty"`
}

type CommandBuilder func(ioStreams *terminal.IOStreams, exitFunc func(code int)) *cobra.Command

type CommandOutput struct {
	// Stdout is the raw stdout text.
	Stdout string `json:"stdout"`
	// Stderr is the raw stderr text.
	Stderr string `json:"stderr"`
	// ExitCode is the process exit code.
	ExitCode int `json:"exitCode"`
	// Output is the parsed JSON output. nil when the command doesn't support -o json.
	Output map[string]any `json:"output,omitempty"`
	// Files contains files created or modified in the sandbox during command execution.
	Files map[string]FileInfo `json:"files"`
}

type FileInfo struct {
	// Exists is always true for entries in the map (present for consistency).
	Exists bool `json:"exists"`
	// Content is the full file content as a string.
	Content string `json:"content"`
}

type FilterOptions struct {
	// NamePatterns are glob patterns matched against test names.
	// If a pattern contains "/", it is split into solution-glob/test-glob.
	NamePatterns []string
	// Tags filters tests that have at least one matching tag (any-match).
	Tags []string
	// SolutionPatterns are glob patterns matched against solution names.
	SolutionPatterns []string
}

type GenerateInput struct {
	// Command is the scafctl subcommand path, e.g. ["render", "solution"].
	Command []string `json:"command" yaml:"command" doc:"scafctl subcommand path" maxItems:"10"`

	// Args are the command arguments excluding the -f/--file and -o test flags,
	// e.g. ["-r", "env=prod"]. The generator appends "-o", "json" automatically
	// when no -o flag is already present, so the generated test will use structured
	// output and populate __output for CEL assertions.
	Args []string `json:"args,omitempty" yaml:"args,omitempty" doc:"Command arguments (without -f and -o)" maxItems:"50"`

	// TestName is the desired test name. When empty, one is derived from Command
	// and Args via DeriveTestName. Must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$.
	TestName string `json:"testName,omitempty" yaml:"testName,omitempty" doc:"Test name override" maxLength:"100"`

	// SnapshotDir is the directory where testdata/<name>.json is written.
	// Defaults to "testdata" relative to the working directory.
	SnapshotDir string `json:"snapshotDir,omitempty" yaml:"snapshotDir,omitempty" doc:"Directory for snapshot files" maxLength:"500"`

	// Data is the command output as a parsed Go value used for assertion derivation.
	// Typically produced by json.Unmarshal on the command's JSON output.
	// When nil, no CEL assertions are derived.
	Data any `json:"-" yaml:"-"`

	// RawJSON is the raw JSON bytes written as the snapshot golden file.
	// When empty, no snapshot file is written and the test case omits a snapshot field.
	RawJSON []byte `json:"-" yaml:"-"`
}

type GenerateResult struct {
	// TestName is the (possibly derived) name of the test.
	TestName string `json:"testName" yaml:"testName"`

	// TestCase is the generated test case, ready to paste into spec.testing.cases.
	TestCase *TestCase `json:"testCase" yaml:"testCase"`

	// SnapshotPath is the relative (or absolute) path where the snapshot file was
	// written. Empty when no snapshot was written.
	SnapshotPath string `json:"snapshotPath,omitempty" yaml:"snapshotPath,omitempty"`

	// SnapshotWritten is true when the snapshot file was created or updated on disk.
	SnapshotWritten bool `json:"snapshotWritten" yaml:"snapshotWritten"`
}

type InitStep struct {
	// Command is the command to execute. Supports POSIX shell syntax (pipes, redirections, variables).
	Command string `json:"command" yaml:"command" doc:"Command to execute" maxLength:"1000"`

	// Args contains additional arguments, automatically shell-quoted.
	Args []string `json:"args,omitempty" yaml:"args,omitempty" doc:"Additional arguments" maxItems:"50"`

	// Stdin provides standard input to the command.
	Stdin string `json:"stdin,omitempty" yaml:"stdin,omitempty" doc:"Standard input to provide to the command" maxLength:"10000"`

	// WorkingDir is the working directory relative to sandbox root.
	WorkingDir string `json:"workingDir,omitempty" yaml:"workingDir,omitempty" doc:"Working directory (relative to sandbox root)" maxLength:"500"`

	// Env contains environment variables merged with the parent process.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty" doc:"Environment variables merged with the parent process"`

	// Timeout is the timeout in seconds (default: 30).
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty" doc:"Timeout in seconds" maximum:"3600"`

	// Shell specifies the shell interpreter: auto (default), sh, bash, pwsh, cmd.
	Shell string `` /* 168-byte string literal not displayed */
}

type ResultSummary struct {
	Passed       int           `json:"passed"`
	Failed       int           `json:"failed"`
	Errors       int           `json:"errors"`
	Skipped      int           `json:"skipped"`
	Total        int           `json:"total"`
	Duration     time.Duration `json:"duration"`
	WallDuration time.Duration `json:"wallDuration,omitempty"`
}

type Runner struct {
	// BinaryPath is the absolute path to the scafctl binary for subprocess
	// execution. Each test's CLI command runs as an isolated child process,
	// giving true parallelism and process-level env/state isolation.
	// When empty, falls back to NewCommand (in-process, for unit tests only).
	BinaryPath string
	// Concurrency is the number of tests to run in parallel. 0 or 1 = sequential.
	Concurrency int
	// FailFast stops remaining tests for a solution on first failure.
	FailFast bool
	// UpdateSnapshots writes actual output to golden files instead of comparing.
	UpdateSnapshots bool
	// Verbose enables extra output (assertion counts, etc.).
	Verbose bool
	// KeepSandbox prevents cleanup of sandbox directories after tests.
	KeepSandbox bool
	// TestTimeout is the default timeout per test.
	TestTimeout time.Duration
	// GlobalTimeout is the overall timeout for all tests.
	GlobalTimeout time.Duration
	// DryRun validates tests without executing commands.
	DryRun bool
	// IOStreams provides input/output streams.
	IOStreams *terminal.IOStreams
	// Filter contains filter options to apply.
	Filter FilterOptions
	// NewCommand builds a root cobra.Command for in-process execution.
	// Used only as a fallback when BinaryPath is empty (unit tests).
	// Production code should always set BinaryPath instead.
	NewCommand CommandBuilder
	// BinaryName is the application name used for deriving env var prefixes
	// (e.g., mocked-resolver env var). When empty, falls back to paths.AppName().
	// Must match the name used by settings.BinaryNameFromContext inside the
	// target binary so writer and reader agree on env var names.
	BinaryName string
	// Progress receives notifications as tests execute.
	// When nil, no progress output is emitted.
	Progress TestProgressCallback
}

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

type ScaffoldInput struct {
	// Resolvers is the map of resolver definitions from the solution spec.
	Resolvers map[string]*resolver.Resolver

	// Workflow is the action workflow from the solution spec (may be nil).
	Workflow *action.Workflow

	// FileDependencies is a list of file paths (relative to the solution dir)
	// discovered through static analysis of provider inputs.
	// These are automatically populated onto generated test cases.
	FileDependencies []string

	// SolutionSubdir is the subdirectory path of the solution file relative to
	// the project root (e.g., "myapp" when the solution is at myapp/solution.yaml).
	// When set, generated test cases include BaseDir so the test runner nests
	// solution files under this subdirectory within the sandbox.
	SolutionSubdir string
}

type ScaffoldResult struct {
	// Cases is a map of generated test cases keyed by name.
	Cases map[string]*TestCase `json:"cases" yaml:"cases"`
}

type ServiceConfig struct {
	// Name is a unique identifier for the service within this solution's tests.
	Name string `json:"name" yaml:"name" doc:"Unique service identifier" maxLength:"100" pattern:"^[a-zA-Z0-9][a-zA-Z0-9_-]*$"`

	// Type is the service type. Supported: "http" (mock HTTP server), "exec" (mock shell commands).
	Type string `json:"type" yaml:"type" doc:"Service type" pattern:"^(http|exec)$" patternDescription:"Must be: http or exec"`

	// PortEnv is the environment variable name where the assigned port is exposed.
	// Tests can reference this via testConfig.env or in resolver inputs (e.g., $MOCK_HTTP_PORT).
	// Only used when Type is "http".
	PortEnv string `` /* 142-byte string literal not displayed */

	// BaseURLEnv is the environment variable name where the base URL is exposed (e.g., http://127.0.0.1:PORT).
	// Optional — if empty, only PortEnv is set. Only used when Type is "http".
	BaseURLEnv string `json:"baseUrlEnv,omitempty" yaml:"baseUrlEnv,omitempty" doc:"Env var name for base URL (http only)" maxLength:"100"`

	// Routes defines the mock HTTP routes (only used when Type is "http").
	Routes []mockserver.Route `json:"routes,omitempty" yaml:"routes,omitempty" doc:"Mock HTTP routes" maxItems:"100"`

	// ExecRules defines mock command rules (only used when Type is "exec").
	// Rules are matched in order — the first matching rule wins.
	ExecRules []mockexec.Rule `json:"execRules,omitempty" yaml:"execRules,omitempty" doc:"Mock command rules" maxItems:"100"`

	// Passthrough allows unmatched exec commands to run normally (only used when Type is "exec").
	// When false (default), unmatched commands fail with an error.
	Passthrough bool `json:"passthrough,omitempty" yaml:"passthrough,omitempty" doc:"Allow unmatched exec commands to run (exec only)"`
}

type SkipBuiltinsValue struct {
	// All when true means skip all builtins.
	All bool `json:"-" yaml:"-"`
	// Names lists specific builtin names to skip.
	Names []string `json:"-" yaml:"-"`
}

type SkipValue struct {
	// Static when true means unconditionally skip.
	Static bool `json:"-" yaml:"-"`
	// Expression is a CEL expression for conditional skipping.
	Expression celexp.Expression `json:"-" yaml:"-"`
}

type SolutionInfo struct {
	// SolutionPath is the absolute path to the main solution file.
	SolutionPath string
	// ComposeFiles are the absolute paths of the compose files referenced by
	// the solution's compose field.
	ComposeFiles []string
}

type SolutionTests struct {
	// SolutionName is the metadata.name from the solution.
	SolutionName string `json:"solutionName"`
	// Cases contains the test definitions keyed by test name.
	Cases map[string]*TestCase `json:"cases"`
	// Config holds the solution-level test configuration.
	Config *TestConfig `json:"config,omitempty"`
	// FilePath is the absolute path to the solution file.
	FilePath string `json:"filePath"`
	// BundleIncludes contains the bundle.include patterns from the solution spec.
	// These are resolved and copied into every test sandbox.
	BundleIncludes []string `json:"bundleIncludes,omitempty"`
	// DetectedFiles contains file patterns auto-detected from resolver specs
	// (e.g., directory provider paths). Used to populate builtin test files.
	DetectedFiles []string `json:"detectedFiles,omitempty"`
}

type Status string

type TestCase struct {
	// Name is the test name (auto-set from map key).
	Name string `` /* 245-byte string literal not displayed */

	// Description is a human-readable test description.
	Description string `json:"description" yaml:"description" doc:"Human-readable test description" maxLength:"500"`

	// Command is the scafctl subcommand as an array (e.g., [render, solution]).
	Command []string `json:"command,omitempty" yaml:"command,omitempty" doc:"scafctl subcommand as an array" maxItems:"10"`

	// Args contains additional CLI flags appended after the command.
	Args []string `json:"args,omitempty" yaml:"args,omitempty" doc:"Additional CLI flags appended after the command" maxItems:"50"`

	// Extends lists names of test templates to inherit from. Applied left-to-right.
	Extends []string `json:"extends,omitempty" yaml:"extends,omitempty" doc:"Names of test templates to inherit from" maxItems:"10"`

	// Tags are labels for categorization and filtering.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty" doc:"Tags for categorization and filtering" maxItems:"20"`

	// Env contains per-test environment variables.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty" doc:"Per-test environment variables"`

	// Files lists relative paths, glob patterns, or directory paths for files required by this test.
	// Globs (e.g., 'templates/**/*.yaml') are expanded using doublestar matching.
	// Directories (e.g., 'templates/') are recursively expanded to include all files.
	Files []string `` /* 207-byte string literal not displayed */

	// Init contains setup steps executed sequentially before the command.
	Init []InitStep `json:"init,omitempty" yaml:"init,omitempty" doc:"Setup steps executed sequentially before the command" maxItems:"50"`

	// Cleanup contains teardown steps executed after the command, even on failure.
	Cleanup []InitStep `` /* 128-byte string literal not displayed */

	// Assertions validates command output. Required unless snapshot is set.
	Assertions []Assertion `json:"assertions,omitempty" yaml:"assertions,omitempty" doc:"Output assertions" maxItems:"100"`

	// Snapshot is a relative path to a golden file for normalized comparison.
	Snapshot string `` /* 130-byte string literal not displayed */

	// InjectFile controls whether the runner auto-injects -f <sandbox-solution-path>.
	// Default is true. Set to false for commands that don't accept -f.
	InjectFile *bool `json:"injectFile,omitempty" yaml:"injectFile,omitempty" doc:"When true, auto-inject -f <sandbox-solution-path>"`

	// ExpectFailure when true, the test passes if the command exits non-zero.
	ExpectFailure bool `json:"expectFailure,omitempty" yaml:"expectFailure,omitempty" doc:"When true, test passes if command exits non-zero"`

	// ExitCode is the exact expected exit code. Mutually exclusive with ExpectFailure.
	ExitCode *int `json:"exitCode,omitempty" yaml:"exitCode,omitempty" doc:"Exact expected exit code"`

	// Timeout is the per-test timeout as a Go duration string.
	Timeout *duration.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty" doc:"Per-test timeout as a Go duration string"`

	// Skip controls test skipping. Accepts true (unconditional) or a CEL expression string (conditional).
	Skip SkipValue `` /* 137-byte string literal not displayed */

	// SkipReason is a human-readable reason for skipping.
	SkipReason string `json:"skipReason,omitempty" yaml:"skipReason,omitempty" doc:"Human-readable reason for skipping" maxLength:"500"`

	// Retries is the number of retry attempts for a failing test.
	Retries int `json:"retries,omitempty" yaml:"retries,omitempty" doc:"Number of retry attempts for failing tests" maximum:"10"`

	// BaseDir is an optional subdirectory path (relative to the sandbox root)
	// that controls where the solution and its files are placed within the sandbox.
	// When set, the sandbox nests all files under this subdirectory, preserving
	// the directory structure so that repo-root-relative paths in resolvers
	// resolve correctly.
	//
	// Example: if baseDir is "cldctl" and the solution references
	// "./cldctl/output/data.json", the sandbox places the file at
	// sandbox/cldctl/output/data.json and the solution at
	// sandbox/cldctl/solution.yaml.
	BaseDir string `` /* 126-byte string literal not displayed */

	// Inputs maps parameter names to values. Each entry is translated to a
	// -r key=value CLI argument appended after Args. This is a convenience
	// shorthand so tests don't have to manually construct -r flags.
	//
	// Example:
	//   inputs:
	//     environment: prod
	//     region: us-east-1
	// is equivalent to: args: ["-r", "environment=prod", "-r", "region=us-east-1"]
	Inputs map[string]string `json:"inputs,omitempty" yaml:"inputs,omitempty" doc:"Parameter name to value map; translated to -r key=value args"`

	// Mocks maps resolver names to canned values. Mocked resolvers skip
	// execution entirely and return the specified value. This enables testing
	// downstream resolvers and CEL expressions without hitting external APIs.
	Mocks map[string]any `json:"mocks,omitempty" yaml:"mocks,omitempty" doc:"Resolver name to canned value map; mocked resolvers skip execution"`

	// Services defines per-test background services that are started before
	// and stopped after this specific test. These supplement (not replace)
	// suite-level services defined in config.services.
	Services []ServiceConfig `json:"services,omitempty" yaml:"services,omitempty" doc:"Per-test background services" maxItems:"10"`
}

type TestConfig struct {
	// SkipBuiltins disables builtin tests. true for all, or list of specific names.
	SkipBuiltins SkipBuiltinsValue `json:"skipBuiltins,omitempty" yaml:"skipBuiltins,omitempty" doc:"Disable builtins: true for all, or list of specific names"`

	// Env provides suite-level environment variables applied to all tests.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty" doc:"Suite-level environment variables applied to all tests"`

	// Setup contains suite-level setup steps run once, then the resulting sandbox is copied per-test.
	Setup []InitStep `` /* 129-byte string literal not displayed */

	// Cleanup contains suite-level teardown steps run once after all tests complete, even on failure.
	Cleanup []InitStep `` /* 148-byte string literal not displayed */

	// Files lists shared file paths, globs, or directories copied into every test sandbox.
	// These are merged with per-test files; per-test entries are appended after config files.
	// Duplicates are deduplicated during sandbox creation (first-seen-wins).
	Files []string `json:"files,omitempty" yaml:"files,omitempty" doc:"Shared files copied into every test sandbox" maxItems:"50"`

	// Services defines background services started before tests and stopped after.
	// Currently supports "http" type which starts a mock HTTP server.
	Services []ServiceConfig `json:"services,omitempty" yaml:"services,omitempty" doc:"Background services started before tests" maxItems:"10"`
}

type TestProgressCallback interface {
	// OnTestStart is called when an individual test begins execution.
	// It is not called for tests that fail before execution (validation errors,
	// dry runs, setup failures, etc.) — those only receive OnTestComplete.
	OnTestStart(solution, test string)

	// OnTestComplete is called when a test finishes with its result.
	// This is called for every test, including those that were skipped or
	// errored before execution began.
	OnTestComplete(result TestResult)

	// Wait blocks until all progress output has been flushed.
	// Must be called after the last OnTestComplete before reading stdout output.
	Wait()
}

type TestResult struct {
	// Solution is the solution name.
	Solution string `json:"solution"`
	// Test is the test name.
	Test string `json:"test"`
	// Status is the test outcome.
	Status Status `json:"status"`
	// Duration is how long the test took.
	Duration time.Duration `json:"duration"`
	// Message provides details about skip, error, or failure.
	Message string `json:"message,omitempty"`
	// Assertions contains the results of each assertion evaluation.
	Assertions []AssertionResult `json:"assertions,omitempty"`
	// RetryAttempt indicates which retry attempt passed (0 = first attempt).
	RetryAttempt int `json:"retryAttempt,omitempty"`
	// SandboxPath is the sandbox directory path (when --keep-sandbox is set).
	SandboxPath string `json:"sandboxPath,omitempty"`
	// Stdout is the captured stdout from the test command (included on failure).
	Stdout string `json:"stdout,omitempty"`
	// Stderr is the captured stderr from the test command (included on failure).
	Stderr string `json:"stderr,omitempty"`
}

type TestSuite struct {
	// Config holds solution-level test configuration.
	Config *TestConfig `json:"config,omitempty" yaml:"config,omitempty" doc:"Test configuration"`

	// Cases is a map of functional test definitions keyed by test name.
	// Test names must be unique and must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$.
	// Names starting with _ are templates that are not executed directly.
	Cases map[string]*TestCase `json:"cases,omitempty" yaml:"cases,omitempty" doc:"Test case definitions keyed by name"`
}

type WatchOptions struct {
	// DebounceDuration controls how long to wait after the last file change
	// before triggering a re-run. Defaults to DefaultDebounceDuration.
	DebounceDuration time.Duration

	// OnRunStart is called just before each test re-run.
	// The string argument identifies the triggering file (relative path when possible).
	OnRunStart func(triggerFile string)

	// OnRunComplete is called after each test re-run with the results.
	OnRunComplete func(results []TestResult, elapsed time.Duration, err error)
}

type WatchResult struct {
	// TriggerFile is the file change that caused the re-run.
	TriggerFile string
	// Results contains the test outcomes.
	Results []TestResult
	// Elapsed is the wall-clock duration of the run.
	Elapsed time.Duration
	// Err is set when the run fails for infrastructure reasons.
	Err error
}

type Watcher struct {
	// Runner is the test runner to use for re-runs.
	Runner *Runner

	// TestsPath is the path to the solution file or directory being tested.
	TestsPath string

	// Options configures watch behaviour.
	Options WatchOptions
	// contains filtered or unexported fields
}