bench

Documentation

Overview

Package bench defines a structure for benchmarked tests against custom CEL environments.

Index

• Variables
• func RunCase(b *testing.B, env *cel.Env, bc *Case)
• func RunDynamicEnvCase(b *testing.B, bc *DynamicEnvCase)
• func RunReferenceCases(b *testing.B, env *cel.Env)
• func RunReferenceDynamicEnvCases(b *testing.B)
• type Case
• type DynamicEnvCase

Variables

var (
	// ReferenceCases represent canonical CEL expressions for common use cases.
	ReferenceCases = []*Case{
		{
			Expr: `string_value == 'value'`,
			Options: []cel.EnvOption{
				cel.Variable("string_value", cel.StringType),
			},
			In: map[string]any{
				"string_value": "value",
			},
			Out: types.True,
		},
		{
			Expr: `string_value != 'value'`,
			Options: []cel.EnvOption{
				cel.Variable("string_value", cel.StringType),
			},
			In: map[string]any{
				"string_value": "value",
			},
			Out: types.False,
		},
		{
			Expr: `'value' in list_value`,
			Options: []cel.EnvOption{
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"list_value": []string{"a", "b", "c", "value"},
			},
			Out: types.True,
		},
		{
			Expr: `!('value' in list_value)`,
			Options: []cel.EnvOption{
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"list_value": []string{"a", "b", "c", "d"},
			},
			Out: types.True,
		},
		{
			Expr: `x in ['a', 'b', 'c', 'd']`,
			Options: []cel.EnvOption{
				cel.Variable("x", cel.StringType),
			},
			In: map[string]any{
				"x": "c",
			},
			Out: types.True,
		},
		{
			Expr: `!(x in ['a', 'b', 'c', 'd'])`,
			Options: []cel.EnvOption{
				cel.Variable("x", cel.StringType),
			},
			In: map[string]any{
				"x": "e",
			},
			Out: types.True,
		},
		{
			Expr: `x in list_value`,
			Options: []cel.EnvOption{
				cel.Variable("x", cel.StringType),
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"x":          "c",
				"list_value": []string{"a", "b", "c", "d"},
			},
			Out: types.True,
		},
		{
			Expr: `!(x in list_value)`,
			Options: []cel.EnvOption{
				cel.Variable("x", cel.StringType),
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"x":          "e",
				"list_value": []string{"a", "b", "c", "d"},
			},
			Out: types.True,
		},
		{
			Expr: `list_value.exists(e, e.contains('cd'))`,
			Options: []cel.EnvOption{
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"list_value": []string{"abc", "bcd", "cde", "def"},
			},
			Out: types.True,
		},
		{
			Expr: `list_value.exists(e, e.startsWith('cd'))`,
			Options: []cel.EnvOption{
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"list_value": []string{"abc", "bcd", "cde", "def"},
			},
			Out: types.True,
		},
		{
			Expr: `list_value.exists(e, e.matches('cd*'))`,
			Options: []cel.EnvOption{
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"list_value": []string{"abc", "bcd", "cde", "def"},
			},
			Out: types.True,
		},
		{
			Expr: `list_value.filter(e, e.matches('^cd+')) == ['cde']`,
			Options: []cel.EnvOption{
				cel.Variable("list_value", cel.ListType(cel.StringType)),
			},
			In: map[string]any{
				"list_value": []string{"abc", "bcd", "cde", "def"},
			},
			Out: types.True,
		},
		{
			Expr: `'formatted list: %s, size: %d'.format([['abc', 'cde'], 2])`,
			Options: []cel.EnvOption{
				ext.Strings(),
			},
			In:  map[string]any{},
			Out: types.String(`formatted list: ["abc", "cde"], size: 2`),
		},
	}
	// ReferenceDynamicEnvCases represent CEL expressions compiled in an extended environment.
	ReferenceDynamicEnvCases = []*DynamicEnvCase{

		{
			Expr: `a+b`,
			Options: func(b *testing.B) *cel.Env {
				stdenv, err := cel.NewEnv(cel.Variable("a", cel.IntType), cel.Variable("b", cel.IntType))
				if err != nil {
					b.Fatalf("cel.NewEnv() failed: %v", err)
				}
				return stdenv
			},
		},
		{
			Expr: `x == y && y == z`,
			Options: func(b *testing.B) *cel.Env {

				stdenv, err := cel.NewEnv(cel.Variable("x", cel.IntType), cel.Variable("y", cel.IntType))
				if err != nil {
					b.Fatalf("cel.NewEnv() failed: %v", err)
				}
				stdenv.Compile("x == y")
				stdenv, err = stdenv.Extend(cel.Variable("z", cel.IntType))
				if err != nil {
					b.Fatalf("cel.Extend() failed: %v", err)
				}
				return stdenv
			},
		},
		{
			Expr: `x + y + z`,
			Options: func(b *testing.B) *cel.Env {

				stdenv, err := cel.NewEnv(cel.Variable("x", cel.IntType), cel.Variable("y", cel.IntType))
				if err != nil {
					b.Fatalf("cel.NewEnv() failed: %v", err)
				}
				stdenv.Compile("x + y")
				stdenv, err = stdenv.Extend(cel.Variable("z", cel.IntType))
				if err != nil {
					b.Fatalf("cel.Extend() failed: %v", err)
				}
				return stdenv
			},
		},
	}
)

Functions

func RunCase

func RunCase(b *testing.B, env *cel.Env, bc *Case)

RunCase evaluates a single test case against a custom environment, running three different variants of the expression: optimized, unoptimized, and trace.

* `optimized` - applies the cel.EvalOptions(cel.OptOptimize) flag. * `unoptimized` - no optimization flags applied. * `trace` - observes the evaluation state of an expression.

In many cases the evaluation times may be similar, but when running comparisons against the baseline CEL environment, it may be useful to characterize the performance of the custom environment against the baseline.

func RunDynamicEnvCase

func RunDynamicEnvCase(b *testing.B, bc *DynamicEnvCase)

RunDynamicEnvCase runs a singular DynamicEnvCase.

func RunReferenceCases

func RunReferenceCases(b *testing.B, env *cel.Env)

RunReferenceCases evaluates the set of ReferenceCases against a custom CEL environment.

See: bench_test.go for an example.

func RunReferenceDynamicEnvCases

func RunReferenceDynamicEnvCases(b *testing.B)

RunReferenceDynamicEnvCases evaluates the set of ReferenceDynamicEnvCases.

Types

type Case

type Case struct {
	// Expr is a human-readable expression which is expected to compile.
	Expr string

	// Options indicate additional pieces of configuration such as CEL libraries, variables, and functions.
	Options []cel.EnvOption

	// In is expected to be a map[string]any or interpreter.Activation instance representing the input to the expression.
	In any

	// Out is the expected CEL valued output.
	Out ref.Val
}

Case represents a human-readable expression and an expected output given an input

type DynamicEnvCase

type DynamicEnvCase struct {
	// Expr is a human-readable expression which is expected to compile.
	Expr string

	// Options indicate additional pieces of configuration such as CEL libraries, variables, and functions.
	Options func(b *testing.B) *cel.Env

	// In is expected to be a map[string]any or interpreter.Activation instance representing the input to the expression.
	In any

	// Out is the expected CEL valued output.
	Out ref.Val
}

DynamicEnvCase represents an expression compiled in a dynamic environment.