package tester

import "github.com/open-policy-agent/opa/v1/tester"

Package tester contains utilities for executing Rego tests.

Index ¶

• Constants
• func Load(args []string, filter loader.Filter) (map[string]*ast.Module, storage.Store, error)
• func LoadBundles(args []string, filter loader.Filter) (map[string]*bundle.Bundle, error)
• func LoadBundlesWithParserOptions(args []string, filter loader.Filter, popts ast.ParserOptions) (map[string]*bundle.Bundle, error)
• func LoadBundlesWithRegoVersion(args []string, filter loader.Filter, regoVersion ast.RegoVersion) (map[string]*bundle.Bundle, error)
• func LoadWithParserOptions(args []string, filter loader.Filter, popts ast.ParserOptions) (map[string]*ast.Module, storage.Store, error)
• func LoadWithRegoVersion(args []string, filter loader.Filter, regoVersion ast.RegoVersion) (map[string]*ast.Module, storage.Store, error)
• type BenchmarkOptions
• type Builtin
• type JSONCoverageReporter
• func (r JSONCoverageReporter) Report(ch chan *Result) error
• type JSONReporter
• func (r JSONReporter) Report(ch chan *Result) error
• type PrettyReporter
• func (r PrettyReporter) Report(ch chan *Result) error
• type Reporter
• type Result
• func Run(ctx context.Context, paths ...string) ([]*Result, error)
• func RunWithFilter(ctx context.Context, _ loader.Filter, paths ...string) ([]*Result, error)
• func (r *Result) Pass() bool
• func (r *Result) String() string
• type Runner
• func NewRunner() *Runner
• func (r *Runner) AddCustomBuiltins(builtinsList []*Builtin) *Runner
• func (r *Runner) CapturePrintOutput(yes bool) *Runner
• func (r *Runner) EnableTracing(yes bool) *Runner
• func (r *Runner) Filter(regex string) *Runner
• func (r *Runner) RaiseBuiltinErrors(enabled bool) *Runner
• func (r *Runner) Run(ctx context.Context, modules map[string]*ast.Module) (chan *Result, error)
• func (r *Runner) RunBenchmarks(ctx context.Context, txn storage.Transaction, options BenchmarkOptions) (chan *Result, error)
• func (r *Runner) RunTests(ctx context.Context, txn storage.Transaction) (chan *Result, error)
• func (r *Runner) SetBundles(bundles map[string]*bundle.Bundle) *Runner
• func (r *Runner) SetCompiler(compiler *ast.Compiler) *Runner
• func (r *Runner) SetCoverageQueryTracer(tracer topdown.QueryTracer) *Runner
• func (r *Runner) SetCoverageTracer(tracer topdown.Tracer) *Runner
• func (r *Runner) SetDefaultRegoVersion(v ast.RegoVersion) *Runner
• func (r *Runner) SetModules(modules map[string]*ast.Module) *Runner
• func (r *Runner) SetRuntime(term *ast.Term) *Runner
• func (r *Runner) SetStore(store storage.Store) *Runner
• func (r *Runner) SetTimeout(timout time.Duration) *Runner
• func (r *Runner) Target(target string) *Runner
• type SubResult
• func (sr *SubResult) String() string
• type SubResultMap
• func (srm SubResultMap) Iter(yield func([]string, *SubResult) bool)
• func (srm SubResultMap) String() string
• func (srm SubResultMap) Update(path ast.Array, trace []*topdown.Event) bool
• type TestQueryTracer
• func NewTestQueryTracer() *TestQueryTracer
• func (t *TestQueryTracer) Events() []*topdown.Event
• func (t *TestQueryTracer) TraceEvent(e topdown.Event)

Constants ¶

const SkipTestPrefix = "todo_test_"

SkipTestPrefix declares the prefix for tests that should be skipped.

const TestPrefix = "test_"

TestPrefix declares the prefix for all test rules.

Functions ¶

func Load ¶

func Load(args []string, filter loader.Filter) (map[string]*ast.Module, storage.Store, error)

Load returns modules and an in-memory store for running tests.

func LoadBundles ¶

func LoadBundles(args []string, filter loader.Filter) (map[string]*bundle.Bundle, error)

LoadBundles will load the given args as bundles, either tarball or directory is OK.

func LoadBundlesWithParserOptions ¶

func LoadBundlesWithParserOptions(args []string, filter loader.Filter, popts ast.ParserOptions) (map[string]*bundle.Bundle, error)

LoadBundlesWithParserOptions will load the given args as bundles, either tarball or directory is OK. Bundles are parsed in accordance with the given ast.ParserOptions.

func LoadBundlesWithRegoVersion ¶

func LoadBundlesWithRegoVersion(args []string, filter loader.Filter, regoVersion ast.RegoVersion) (map[string]*bundle.Bundle, error)

LoadBundlesWithRegoVersion will load the given args as bundles, either tarball or directory is OK. Bundles are parsed in accordance with the given RegoVersion.

func LoadWithParserOptions ¶

func LoadWithParserOptions(args []string, filter loader.Filter, popts ast.ParserOptions) (map[string]*ast.Module, storage.Store, error)

LoadWithParserOptions returns modules and an in-memory store for running tests. Modules are parsed in accordance with the given ast.ParserOptions.

func LoadWithRegoVersion ¶

func LoadWithRegoVersion(args []string, filter loader.Filter, regoVersion ast.RegoVersion) (map[string]*ast.Module, storage.Store, error)

LoadWithRegoVersion returns modules and an in-memory store for running tests. Modules are parsed in accordance with the given RegoVersion.

Types ¶

type BenchmarkOptions ¶

type BenchmarkOptions struct {
	ReportAllocations bool
}

BenchmarkOptions defines options specific to benchmarking tests

type Builtin ¶

type Builtin struct {
	Decl *ast.Builtin
	Func func(*rego.Rego)
}

type JSONCoverageReporter ¶

type JSONCoverageReporter struct {
	Cover     *cover.Cover
	Modules   map[string]*ast.Module
	Output    io.Writer
	Threshold float64
	Verbose   bool
}

JSONCoverageReporter reports coverage as a JSON structure.

func (JSONCoverageReporter) Report ¶

func (r JSONCoverageReporter) Report(ch chan *Result) error

Report prints the test report to the reporter's output. If any tests fail or encounter errors, this function returns an error.

type JSONReporter ¶

type JSONReporter struct {
	Output io.Writer
}

JSONReporter reports test results as array of JSON objects.

func (JSONReporter) Report ¶

func (r JSONReporter) Report(ch chan *Result) error

Report prints the test report to the reporter's output.

type PrettyReporter ¶

type PrettyReporter struct {
	Output                   io.Writer
	Verbose                  bool
	FailureLine              bool
	LocalVars                bool
	BenchmarkResults         bool
	BenchMarkShowAllocations bool
	BenchMarkGoBenchFormat   bool
}

PrettyReporter reports test results in a simple human readable format.

func (PrettyReporter) Report ¶

func (r PrettyReporter) Report(ch chan *Result) error

Report prints the test report to the reporter's output.

type Reporter ¶

type Reporter interface {

	// Report is called with a channel that will contain test results.
	Report(chan *Result) error
}

Reporter defines the interface for reporting test results.

type Result ¶

type Result struct {
	Location        *ast.Location            `json:"location"`
	Package         string                   `json:"package"`
	Name            string                   `json:"name"`
	Fail            bool                     `json:"fail,omitempty"`
	Error           error                    `json:"error,omitempty"`
	Skip            bool                     `json:"skip,omitempty"`
	Duration        time.Duration            `json:"duration"`
	Trace           []*topdown.Event         `json:"trace,omitempty"`
	Output          []byte                   `json:"output,omitempty"`
	FailedAt        *ast.Expr                `json:"failed_at,omitempty"`
	BenchmarkResult *testing.BenchmarkResult `json:"benchmark_result,omitempty"`
	SubResults      SubResultMap             `json:"sub_results,omitempty"`
}

Result represents a single test case result.

func Run ¶

func Run(ctx context.Context, paths ...string) ([]*Result, error)

Run executes all test cases found under files in path.

func RunWithFilter ¶

func RunWithFilter(ctx context.Context, _ loader.Filter, paths ...string) ([]*Result, error)

RunWithFilter executes all test cases found under files in path. The filter will be applied to exclude files that should not be included.

func (*Result) Pass ¶

func (r *Result) Pass() bool

Pass returns true if the test case passed.

func (*Result) String ¶

func (r *Result) String() string

type Runner ¶

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

Runner implements simple test discovery and execution.

func NewRunner ¶

func NewRunner() *Runner

NewRunner returns a new runner.

func (*Runner) AddCustomBuiltins ¶

func (r *Runner) AddCustomBuiltins(builtinsList []*Builtin) *Runner

func (*Runner) CapturePrintOutput ¶

func (r *Runner) CapturePrintOutput(yes bool) *Runner

CapturePrintOutput captures print() call outputs during evaluation and includes the output in test results.

func (*Runner) EnableTracing ¶

func (r *Runner) EnableTracing(yes bool) *Runner

EnableTracing enables tracing of evaluation and includes traces in results. Tracing is currently mutually exclusive with coverage.

func (*Runner) Filter ¶

func (r *Runner) Filter(regex string) *Runner

Filter will set a test name regex filter for the test runner. Only test cases which match the filter will be run.

func (*Runner) RaiseBuiltinErrors ¶

func (r *Runner) RaiseBuiltinErrors(enabled bool) *Runner

RaiseBuiltinErrors sets the runner to raise errors encountered by builtins such as parsing input.

func (*Runner) Run ¶

func (r *Runner) Run(ctx context.Context, modules map[string]*ast.Module) (chan *Result, error)

Run executes all tests contained in supplied modules. Deprecated: Use RunTests and the Runner#SetModules or Runner#SetBundles helpers instead. This will NOT use the modules or bundles set on the Runner.

func (*Runner) RunBenchmarks ¶

func (r *Runner) RunBenchmarks(ctx context.Context, txn storage.Transaction, options BenchmarkOptions) (chan *Result, error)

RunBenchmarks executes tests similar to tester.Runner#RunTests but will repeat a number of times to get stable performance metrics.

func (*Runner) RunTests ¶

func (r *Runner) RunTests(ctx context.Context, txn storage.Transaction) (chan *Result, error)

RunTests executes tests found in either modules or bundles loaded on the runner.

func (*Runner) SetBundles ¶

func (r *Runner) SetBundles(bundles map[string]*bundle.Bundle) *Runner

SetBundles will add bundles to the Runner which will be compiled then used for discovering and evaluating tests.

func (*Runner) SetCompiler ¶

func (r *Runner) SetCompiler(compiler *ast.Compiler) *Runner

SetCompiler sets the compiler used by the runner.

func (*Runner) SetCoverageQueryTracer ¶

func (r *Runner) SetCoverageQueryTracer(tracer topdown.QueryTracer) *Runner

SetCoverageQueryTracer sets the tracer to use to compute coverage.

func (*Runner) SetCoverageTracer ¶

func (r *Runner) SetCoverageTracer(tracer topdown.Tracer) *Runner

SetCoverageTracer sets the tracer to use to compute coverage. Deprecated: Use SetCoverageQueryTracer instead.

func (*Runner) SetDefaultRegoVersion ¶

func (r *Runner) SetDefaultRegoVersion(v ast.RegoVersion) *Runner

SetDefaultRegoVersion sets the default Rego version to use when compiling modules. Not applicable if a custom ast.Compiler is set via [SetCompiler].

func (*Runner) SetModules ¶

func (r *Runner) SetModules(modules map[string]*ast.Module) *Runner

SetModules will add modules to the Runner which will be compiled then used for discovering and evaluating tests.

func (*Runner) SetRuntime ¶

func (r *Runner) SetRuntime(term *ast.Term) *Runner

SetRuntime sets runtime information to expose to the evaluation engine.

func (*Runner) SetStore ¶

func (r *Runner) SetStore(store storage.Store) *Runner

SetStore sets the store to execute tests over.

func (*Runner) SetTimeout ¶

func (r *Runner) SetTimeout(timout time.Duration) *Runner

SetTimeout sets the timeout for the individual test cases

func (*Runner) Target ¶

func (r *Runner) Target(target string) *Runner

Target sets the output target type to use.

type SubResult ¶

type SubResult struct {
	Name       string           `json:"name,omitempty"`
	Fail       bool             `json:"fail,omitempty"`
	Trace      []*topdown.Event `json:"-"`
	SubResults SubResultMap     `json:"sub_results,omitempty"`
}

func (*SubResult) String ¶

func (sr *SubResult) String() string

type SubResultMap ¶

type SubResultMap map[string]*SubResult

func (SubResultMap) Iter ¶

func (srm SubResultMap) Iter(yield func([]string, *SubResult) bool)

Iter is a depth-first iterator over all sub-results.

func (SubResultMap) String ¶

func (srm SubResultMap) String() string

func (SubResultMap) Update ¶

func (srm SubResultMap) Update(path ast.Array, trace []*topdown.Event) bool

type TestQueryTracer ¶

type TestQueryTracer struct {
	topdown.BufferTracer
}

func NewTestQueryTracer ¶

func NewTestQueryTracer() *TestQueryTracer

func (*TestQueryTracer) Events ¶

func (t *TestQueryTracer) Events() []*topdown.Event

func (*TestQueryTracer) TraceEvent ¶

func (t *TestQueryTracer) TraceEvent(e topdown.Event)

Source Files ¶

reporter.go runner.go test_tracer.go