devloretest

package
v0.1.0-dev.20260820193440 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package devloretest implements the devlore-test CLI commands.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewRootCmd 

func NewRootCmd() *cobra.Command

NewRootCmd creates the root devlore-test command with all subcommands.

Types

type BindingSources 

type BindingSources struct {
	Overrides map[string]any
	Flags     map[string]any
	EnvPrefix string
	Config    map[string]any
}

BindingSources captures the variable-resolver source maps threaded into the resolver at execute time.

The runner and the TestContext share a pointer to the same instance so .star-side setters (t.set_overrides, t.set_flags, t.set_env_prefix, t.set_config) and Go-side runner options write to the same place. EnvPrefix is treated as a program-name override for the resolver's env-prefix derivation; when non-empty it is passed in lieu of the spec's ProgramName so tests can simulate writ-style or lore-style env lookups under the devlore-test harness.

type Expectation 

type Expectation struct {
	Kind    string         // "file_exists", "no_file", "unit_count", "error", "equal", "variable", "variable_namespace"
	Path    string         // for file expectations
	Content string         // optional expected content
	Count   int            // for unit_count
	Pattern string         // for error expectations
	Got     starlark.Value // for equal expectations
	Want    starlark.Value // for equal expectations

	// Fields for "variable" and "variable_namespace" expectations.
	VarName       string          // the parameter name to look up in the resolved variable map
	VarValue      *starlark.Value // when non-nil, assert variables[VarName].Value equals the wrapped value
	VarSource     *string         // when non-nil, assert variables[VarName].Source.String() equals *VarSource
	VarSourceKind *string         // when non-nil, assert variables[VarName].Source.Kind.String() equals *VarSourceKind
}

Expectation represents a single test assertion queued during script execution.

type Failure 

type Failure struct {
	Expectation string `json:"expectation"`
	Message     string `json:"message"`
}

Failure records a failed expectation.

type Option 

type Option func(*Runner)

Option configures a Runner.

func WithConfig 

func WithConfig(m map[string]any) Option

WithConfig supplies a configuration map for the variable resolver.

Config values are recorded under op.VariableSourceKindConfig for the resolver to consume at execute time.

Parameters:

  • `m`: parameter-name keyed map of config values.

Returns:

  • `Option`: a runner option that records the config map.

func WithDryRun 

func WithDryRun() Option

WithDryRun enables dry-run mode (plan only, no side effects).

Returns:

  • `Option`: a runner option that sets dry-run mode.

func WithEnvPrefix 

func WithEnvPrefix(programPrefix string) Option

WithEnvPrefix overrides the program-name string the resolver uses to derive its env-var prefix.

The resolver always derives `strings.ToUpper(programName) + "_"` as its env prefix; supplying a different program name here lets a test simulate writ-style or lore-style env lookups while running under the devlore-test harness. When unset, the resolver derives the prefix from the spec's ProgramName.

Parameters:

  • `programPrefix`: the program-name override (e.g., "writ" for `WRIT_*` env lookups).

Returns:

  • `Option`: a runner option that records the env prefix.

func WithFlags 

func WithFlags(m map[string]any) Option

WithFlags supplies a command-line-argument flag map for the variable resolver.

Flag values are recorded under op.VariableSourceKindFlag for the resolver to consume at execute time.

Parameters:

  • `m`: parameter-name keyed map of flag-derived values.

Returns:

  • `Option`: a runner option that records the flag map.

func WithGraphBuilder 

func WithGraphBuilder() Option

WithGraphBuilder enables the plan.* graph namespace.

Returns:

  • `Option`: a runner option that enables the graph builder.

func WithOverrides 

func WithOverrides(m map[string]any) Option

WithOverrides supplies an explicit-runtime-force override map for the variable resolver.

Override values are recorded under op.VariableSourceKindOverride for the resolver to consume at execute time.

Parameters:

  • `m`: parameter-name keyed map of override values.

Returns:

  • `Option`: a runner option that records the override map.

func WithProvider 

func WithProvider(name string) Option

WithProvider restricts execution to a specific provider.

Parameters:

  • `name`: the provider name to restrict to.

Returns:

  • `Option`: a runner option that sets the provider filter.

func WithReceivers 

func WithReceivers(receivers ...op.ReceiverType) Option

WithReceivers sets the receiver factories to expose as Starlark globals.

Parameters:

  • `receivers`: the receiver factories to include.

Returns:

  • `Option`: a runner option that sets the receiver list.

func WithTrace 

func WithTrace() Option

WithTrace enables Starlark step-by-step trace logging.

Returns:

  • `Option`: a runner option that enables tracing.

func WithWriter 

func WithWriter(w io.Writer) Option

WithWriter sets the output writer for executor messages.

Parameters:

  • `w`: the output writer.

Returns:

  • `Option`: a runner option that sets the writer.

type Result 

type Result struct {
	Passed           bool      `json:"passed"`
	UnitCount        int       `json:"unit_count"`
	ExpectationCount int       `json:"expectation_count"`
	Failures         []Failure `json:"failures"`
	Trace            []string  `json:"trace,omitempty"`
}

Result is the structured output of a test run.

type Runner 

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

Runner orchestrates a single test script execution.

func NewRunner 

func NewRunner(script string, opts ...Option) *Runner

NewRunner creates a Runner for the given script path.

Parameters:

  • `script`: the path to the .star test script.
  • `opts`: functional options to configure the runner.

Returns:

  • *Runner: the configured test runner.

func (*Runner) Graph 

func (r *Runner) Graph() *op.Graph

Graph returns the execution graph after Start completes. Returns nil before Start is called.

Returns:

  • *op.Graph: the execution graph, or nil if Start has not been called.

func (*Runner) Sources 

func (r *Runner) Sources() *BindingSources

Sources returns the runner's BindingSources pointer.

Used by TestContext to share the same source maps for inline .star-side setters (t.set_overrides etc.).

Returns:

  • *BindingSources: the shared sources pointer.

func (*Runner) Start 

func (r *Runner) Start(ctx context.Context) (_ *Result, err error)

Start executes the test script and returns structured results.

Parameters:

  • `ctx`: the execution context (used for cancellation).

Returns:

  • *Result: the test outcome with pass/fail status and failures.
  • `error`: non-nil if script loading or graph execution fails unexpectedly.

type TestContext 

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

TestContext is the `t` namespace injected into Starlark test scripts.

Provides a temp directory and queues expectations that are checked after graph execution completes. File checks are scoped through fsroot.Dir when available.

func NewTestContext 

func NewTestContext(tmpDir string, root fsroot.Dir, sources *BindingSources) *TestContext

NewTestContext creates a TestContext rooted at `tmpDir`.

When `fsroot` is non-nil, file checks (checkFileExists, checkNoFile) are scoped through fsroot.Dir.

Parameters:

  • `tmpDir`: the temp directory the test owns; used as the fsroot for t.tmp paths.
  • `fsroot`: optional fsroot.Dir that scopes file-check I/O; nil falls back to plain os calls.
  • `sources`: shared pointer to the Runner's BindingSources; t.set_* builtins write through this pointer so the Runner sees what the .star configured.

Returns:

  • *TestContext: the constructed context.

func (*TestContext) Check 

func (tc *TestContext) Check(graph *op.Graph, execErr error) []Failure

Check evaluates all queued expectations against the executed graph and filesystem.

Returns failures for any expectations that did not hold.

Parameters:

  • `graph`: the executed graph (may be nil when no script assembly succeeded).
  • `execErr`: the execution error (nil on success); used for `error`-kind expectations.

Returns:

  • []Failure: failures for expectations that did not hold; never nil (empty when all pass).

func (*TestContext) EnvSet 

func (tc *TestContext) EnvSet() map[string]string

EnvSet returns the env vars set via t.set_env during script execution.

The runner reads this map at teardown to issue os.Unsetenv for each key — keeps process-env mutations from leaking between tests.

Returns:

  • map[string]string: the set env vars; never nil, possibly empty.

func (*TestContext) Expectations 

func (tc *TestContext) Expectations() []Expectation

Expectations returns the queued expectations.

Returns:

  • []Expectation: the queued expectation list; may be empty.

func (*TestContext) SetResolvedVariables 

func (tc *TestContext) SetResolvedVariables(v map[string]op.Variable)

SetResolvedVariables records the resolver's variable map so variable expectations can be checked.

Parameters:

func (*TestContext) StarlarkValue 

func (tc *TestContext) StarlarkValue() starlark.Value

StarlarkValue returns the `t` namespace as a Starlark struct.

Returns:

  • starlark.Value: a starlark struct binding the t.* builtins.

func (*TestContext) TmpDir 

func (tc *TestContext) TmpDir() string

TmpDir returns the temp directory path.

Returns:

  • `string`: the temp directory the test owns.

type Tracer 

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

Tracer collects trace entries during Starlark script execution. When enabled, it records position and expression info via the thread's Print handler and captures plan.* invocations.

func NewTracer 

func NewTracer(enabled bool) *Tracer

NewTracer creates a Tracer. If enabled is false, all operations are no-ops.

func (*Tracer) Enabled 

func (tr *Tracer) Enabled() bool

Enabled returns whether tracing is active.

func (*Tracer) Entries 

func (tr *Tracer) Entries() []string

Entries returns a copy of all recorded trace entries.

func (*Tracer) PrintHandler 

func (tr *Tracer) PrintHandler() func(*starlark.Thread, string)

PrintHandler returns a starlark.Thread.Print function that captures print() output as trace entries and logs them.

func (*Tracer) Record 

func (tr *Tracer) Record(format string, args ...any)

Record adds a trace entry.

func (*Tracer) RecordThread 

func (tr *Tracer) RecordThread(thread *starlark.Thread, msg string)

RecordThread logs the current thread position.

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.