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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Asset ¶
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 ¶
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 ¶
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 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 ¶
ImportPath attempts to infer the import path based on the GOPATH environment variable and the directory.
func MustAsset ¶
MustAsset is like Asset but panics when Asset would return an error. It simplifies safe initialization of global variables.
func RestoreAsset ¶
RestoreAsset restores an asset under the given directory
func RestoreAssets ¶
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 ¶ added in v0.3.6
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 ¶ added in v0.3.6
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package testimport contains a test import that the testing package uses for unit tests.
|
Package testimport contains a test import that the testing package uses for unit tests. |