Documentation
¶
Overview ¶
Package celtest provides functions for testing CEL policies and expressions.
Package celtest provides functions for testing CEL policies and expressions.
Index ¶
- func TriggerTests(t *testing.T, testRunnerOpts ...TestRunnerOption)
- func UpdateTestResourcesPaths(testResourcesDir string, paths []*string) error
- type ActivationFactory
- type Program
- type Test
- type TestResult
- type TestRunner
- type TestRunnerOption
- func AddFileDescriptorSetProto(fds *descpb.FileDescriptorSet) TestRunnerOption
- func CustomTestCompiler(c compiler.Compiler) TestRunnerOption
- func DefaultTestSuiteParser(path string) TestRunnerOption
- func EnableCoverage() TestRunnerOption
- func FileDescriptorSet(path string) TestRunnerOption
- func PartialEvalProgramOption() TestRunnerOption
- func TestCompiler(compileOpts ...any) TestRunnerOption
- func TestExpression(value string) TestRunnerOption
- func TestInputActivationFactory(f ActivationFactory) TestRunnerOption
- func TestRunnerOptionsFromFlags(testResourcesDir string, testRunnerOpts []TestRunnerOption, ...) TestRunnerOption
- func TestSuite(path string) TestRunnerOption
- func TestSuiteParserOption(p TestSuiteParser) TestRunnerOption
- type TestSuiteParser
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func TriggerTests ¶
func TriggerTests(t *testing.T, testRunnerOpts ...TestRunnerOption)
TriggerTests triggers tests for a CEL policy, expression or checked expression with the provided set of options. The options can be used to: - configure the Compiler used for parsing and compiling the expression - configure the Test Runner used for parsing and executing the tests
func UpdateTestResourcesPaths ¶
UpdateTestResourcesPaths updates the list of paths with their absolute paths as per their location in the testResourcesDir directory. This will allow the executable targets to locate and access the data dependencies needed to trigger the tests. For example: In case of Bazel, this method can be used to update the file paths with the corresponding location in the runfiles directory tree:
UpdateTestResourcesPaths(os.Getenv("RUNFILES_DIR"), <file_paths_list>)
Types ¶
type ActivationFactory ¶
type ActivationFactory func(vars any) (cel.Activation, error)
ActivationFactory is a function which creates a CEL activation from the provided variables.
type Program ¶
type Program struct {
cel.Program
PolicyMetadata map[string]any
Ast *cel.Ast
CoverageStats map[int64]set
}
Program represents the result of creating CEL programs for the configured expressions in the test runner. It encompasses the following: - CELProgram - the evaluable CEL program - PolicyMetadata - the metadata map obtained while creating the CEL AST from the expression - Ast - the CEL AST created from the expression - CoverageStats - the coverage report map obtained from calculating the coverage if enabled.
type Test ¶
type Test struct {
// contains filtered or unexported fields
}
Test represents a single test case to be executed. It encompasses the following: - name: The name of the test case. - input: The input to be used for evaluating the CEL expression. - resultMatcher: A function that takes in the result of evaluating the CEL expression and returns a TestResult.
func NewTest ¶
func NewTest(name string, input cel.PartialActivation, resultMatcher func(ref.Val, error) TestResult) *Test
NewTest creates a new Test with the provided name, input and result matcher.
type TestResult ¶
TestResult represents the result of a test case execution. It contains the validation result along with the expected result and any errors encountered during the execution. - Success: Whether the result matcher condition validating the test case was satisfied. - Wanted: The expected result of the test case. - Error: Any error encountered during the execution.
type TestRunner ¶
type TestRunner struct {
compiler.Compiler
Expressions []compiler.InputExpression
TestSuiteFilePath string
FileDescriptorSet *descpb.FileDescriptorSet
EnableCoverage bool
// contains filtered or unexported fields
}
TestRunner provides a structure to hold the different components required to execute tests for a list of Input Expressions. The TestRunner can be configured with the following options: - Compiler: The compiler used for parsing and compiling the input expressions. - Input Expressions: The list of input expressions to be tested. - Test Suite File Path: The path to the test suite file. - File Descriptor Set Path: The path to the file descriptor set file. - test Suite Parser: A parser for a test suite file serialized in Textproto/YAML format. - test Program Options: A list of options to be used when creating the CEL programs. - EnableCoverage: A boolean to enable coverage calculation.
The TestRunner provides the following methods: - Programs: Creates a list of CEL programs from the input expressions. - Tests: Creates a list of tests from the test suite file. - ExecuteTest: Executes a single
func NewTestRunner ¶
func NewTestRunner(opts ...TestRunnerOption) (*TestRunner, error)
NewTestRunner creates a Test Runner with the provided options. The options can be used to: - configure the Compiler used for parsing and compiling the input expressions - configure the Test Runner used for parsing and executing the tests
func (*TestRunner) ExecuteTest ¶
ExecuteTest executes the test case against the provided list of programs and returns an error if the test fails. During the test execution, the intermediate values encountered during the evaluation of each program are collected and stored in the CoverageStats map of the TestRunner.
func (*TestRunner) Programs ¶
func (tr *TestRunner) Programs(t *testing.T, opts ...cel.ProgramOption) ([]Program, error)
Programs creates a list of CEL programs from the input expressions configured in the test runner using the provided program options.
type TestRunnerOption ¶
type TestRunnerOption func(*TestRunner) (*TestRunner, error)
TestRunnerOption is used to configure the following attributes of the Test Runner: - set the Compiler - add Input Expressions - set the test suite file path - set the test suite parser based on the file format: YAML or Textproto
func AddFileDescriptorSetProto ¶
func AddFileDescriptorSetProto(fds *descpb.FileDescriptorSet) TestRunnerOption
AddFileDescriptorSetProto creates a Test Runner Option which adds a file descriptor set proto to the test runner. The file descriptor set is used to register proto messages in the global proto registry.
func CustomTestCompiler ¶
func CustomTestCompiler(c compiler.Compiler) TestRunnerOption
CustomTestCompiler returns a TestRunnerOption which configures the test runner with a custom compiler.
func DefaultTestSuiteParser ¶
func DefaultTestSuiteParser(path string) TestRunnerOption
DefaultTestSuiteParser returns a TestRunnerOption which configures the test runner with the default test suite parser. Deprecated: prefer TestSuite(path)
func EnableCoverage ¶
func EnableCoverage() TestRunnerOption
EnableCoverage returns a TestRunnerOption which enables coverage calculation for the test run.
func FileDescriptorSet ¶
func FileDescriptorSet(path string) TestRunnerOption
FileDescriptorSet creates a Test Runner Option which adds a file descriptor set to the test runner. The file descriptor set is used to register proto messages in the global proto registry.
func PartialEvalProgramOption ¶
func PartialEvalProgramOption() TestRunnerOption
PartialEvalProgramOption returns a TestRunnerOption which enables partial evaluation for the CEL program by setting the OptPartialEval eval option.
Note: The test setup uses env.PartialVars() for creating PartialActivation.
func TestCompiler ¶
func TestCompiler(compileOpts ...any) TestRunnerOption
TestCompiler returns a TestRunnerOption which configures the test runner with a compiler created using the set of compiler options.
func TestExpression ¶
func TestExpression(value string) TestRunnerOption
TestExpression returns a TestRunnerOption which configures a policy file, expression file, or raw expression for testing
func TestInputActivationFactory ¶
func TestInputActivationFactory(f ActivationFactory) TestRunnerOption
TestInputActivationFactory updates the test runner with the provided activation factory. The activation factory is used to create a CEL activation from the provided variables.
func TestRunnerOptionsFromFlags ¶
func TestRunnerOptionsFromFlags(testResourcesDir string, testRunnerOpts []TestRunnerOption, testCompilerOpts ...any) TestRunnerOption
TestRunnerOptionsFromFlags returns a TestRunnerOption which configures the following attributes of the test runner using the parsed flags and the optionally provided test runner and test compiler options:
- Test compiler - The `file_descriptor_set`, `base_config_path` and `config_path` flags are used to set up the test compiler. The optionally provided test compiler options are also used to augment the test compiler.
- Test suite parser - The `test_suite_path` flag is used to set up the test suite parser.
- File descriptor set path - The value of the `file_descriptor_set` flag is set as the File Descriptor Set Path of the test runner.
- Test expression - The `cel_expr` flag is used to populate the test expressions which need to be evaluated by the test runner.
- Enable coverage - The `enable_coverage` flag is used to enable coverage calculation and reporting.
func TestSuite ¶
func TestSuite(path string) TestRunnerOption
TestSuite provides a reference to the test suite file (either .yaml or .textproto)
func TestSuiteParserOption ¶
func TestSuiteParserOption(p TestSuiteParser) TestRunnerOption
TestSuiteParserOption returns a TestRunnerOption which configures the test runner with a custom test suite parser.
type TestSuiteParser ¶
type TestSuiteParser interface {
ParseTextproto(string) (*conformancepb.TestSuite, error)
ParseYAML(string) (*test.Suite, error)
}
TestSuiteParser is an interface for parsing a test suite: - ParseTextproto: Returns a cel.spec.expr.conformance.test.TestSuite message. - ParseYAML: Returns a test.Suite object. In case the test suite is serialized in a Textproto/YAML file, the path of the file is passed as an argument to the parse method.
Source Files