testing

README

Sentinel Import Test Framework

This folder contains a library for testing imports that are written in Go.

This works by building the import binary dynamically during go test and executing your test policy. The policy must pass. If the policy fails, the failure trace is logged and shown. Execution is done via the publicly available sentinel binary.

Example

You can see an example in the import_test.go file in this folder. This test actually runs as part of the unit tests to verify the behavior.

Documentation

Overview

Package testing provides support for automated testing for import plugins.

Index

• func Asset(name string) ([]byte, error)
• func AssetDir(name string) ([]string, error)
• func AssetInfo(name string) (os.FileInfo, error)
• func AssetNames() []string
• func Clean()
• func ImportPath(dir string) (string, error)
• func MustAsset(name string) []byte
• func RestoreAsset(dir, name string) error
• func RestoreAssets(dir, name string) error
• func TestImport(t testing.T, c TestImportCase)
• func TestImportDir(t testing.T, path string, customize func(*TestImportCase))
• type TestImportCase
  • func LoadTestImportCase(t testing.T, path string) TestImportCase

Functions

func Asset

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetDir

func AssetDir(name string) ([]string, error)

AssetDir returns the file names below a certain directory embedded in the file by go-bindata. For example if you run go-bindata on data/... and data contains the following hierarchy:

data/
  foo.txt
  img/
    a.png
    b.png

then AssetDir("data") would return []string{"foo.txt", "img"} AssetDir("data/img") would return []string{"a.png", "b.png"} AssetDir("foo.txt") and AssetDir("notexist") would return an error AssetDir("") will return []string{"data"}.

func AssetInfo

func AssetInfo(name string) (os.FileInfo, error)

AssetInfo loads and returns the asset info for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetNames

func AssetNames() []string

AssetNames returns the names of the assets.

func Clean

func Clean()

Clean cleans any temporary files created. This should always be called at the end of any set of import tests.

func ImportPath

func ImportPath(dir string) (string, error)

ImportPath attempts to infer the import path based on the GOPATH environment variable and the directory.

func MustAsset

func MustAsset(name string) []byte

MustAsset is like Asset but panics when Asset would return an error. It simplifies safe initialization of global variables.

func RestoreAsset

func RestoreAsset(dir, name string) error

RestoreAsset restores an asset under the given directory

func RestoreAssets

func RestoreAssets(dir, name string) error

RestoreAssets restores an asset under the given directory recursively

func TestImport

func TestImport(t testing.T, c TestImportCase)

TestImport tests that a sdk.Import implementation works as expected.

func TestImportDir

func TestImportDir(t testing.T, path string, customize func(*TestImportCase))

TestImportDir iterates over files in a directory, calls LoadTestImportCase on each file suffixed with ".sentinel", and executes all of the import tests.

Types

type TestImportCase

type TestImportCase struct {
	// Source is a policy to execute. This should be a full program ending
	// in `main = ` and an assignment. For example `main = subject.foo`.
	Source string

	// This is the configuration that will be sent to the plugin. This
	// must serialize to JSON since the JSON will be used to pass the
	// configuration.
	Config map[string]interface{}

	// This is extra data to inject into the global scope of the policy
	// execution
	Global map[string]interface{}

	// Mock is mocked import data
	Mock map[string]map[string]interface{}

	// ImportPath is the path to a Go package on your GOPATH containing
	// the import to test. If this is blank, the test case uses heuristics
	// to extract the GOPATH and use the current package for testing.
	// This package is expected to expose a "New" function which adheres to
	// the sdk/rpc.ImportFunc signature.
	//
	// This should usually be blank. This maximizes portability of the
	// import if it were to be forked or moved.
	//
	// For a given import path, the test binary will be built exactly once
	// per test run.
	ImportPath string

	// ImportName allows passing a custom name for the import to be used in
	// test cases. By default, the import is simply named "subject". The
	// import name is what is used within this policy's source to access
	// functionality provided by the import.
	ImportName string

	// A string containing any expected runtime error during evaluation. If
	// this field is non-empty, a runtime error is expected to occur, and
	// the Sentinel output is searched for the string given here. If the
	// output contains the string, the test passes. If it does not contain
	// the string, the test will fail.
	//
	// More advanced matches can be done with regular expression patterns.
	// If the Error string is delimited by slashes (/), the string is
	// compiled as a regular expression and the Sentinel output is matched
	// against the resulting pattern. If a match is found, the test passes.
	// If it does not match, the tests will fail.
	Error string
}

TestImportCase is a single test case for configuring TestImport.

func LoadTestImportCase

func LoadTestImportCase(t testing.T, path string) TestImportCase

LoadTestImportCase is used to load a TestImportCase from a Sentinel policy file. Certain test case pragmas are supported in the top-most comment body. The following is a completely valid example:

//config: {"option1": "value1"}
//error: failed to do the thing
main = rule { true }

The above would load a TestImport case using the specified options. The config is loaded as a JSON string and unmarshaled into the Config field. The error field is loaded as a string into the Error field. Pragmas *must* be at the very top of the file, starting at line one. When a non-pragma line is encountered, parsing will end and any further pragmas are discarded.

This makes boilerplate very simple for a large number of Sentinel tests, and allows an entire test to be captured neatly into a single file which also happens to be the policy being tested.