Documentation ¶
Index ¶
- Constants
- Variables
- type Assertion
- type Case
- type CaseResult
- type Duration
- type Filter
- type Printer
- type PrinterGo
- func (p PrinterGo) Print(w StringWriter, r []SuiteResult, verbose bool) error
- func (p PrinterGo) PrintCase(w StringWriter, r *CaseResult, verbose bool) error
- func (p PrinterGo) PrintSuite(w StringWriter, r *SuiteResult, verbose bool) error
- func (p PrinterGo) PrintTest(w StringWriter, r *TestResult, verbose bool) error
- type Runner
- type RunnerOptions
- type StringWriter
- type Suite
- type SuiteResult
- type Test
- type TestResult
Constants ¶
const ( // Group is the API Group for Test YAML objects. Group = "test.gatekeeper.sh" // Kind is the Kind for Suite YAML objects. Kind = "Suite" )
Variables ¶
var ( // ErrNoFileSystem means a method which expects a filesystem got nil // instead. This is likely a bug in the code. ErrNoFileSystem = errors.New("no filesystem") // ErrNoTarget indicates that the user did not specify a target directory or // file. ErrNoTarget = errors.New("target not specified") // ErrUnsupportedExtension indicates that a user attempted to run tests in // a file type which is not supported. ErrUnsupportedExtension = errors.New("unsupported extension") // ErrNotADirectory indicates that a user is mistakenly attempting to // perform a directory-only action on a file (for example, recursively // traversing it). ErrNotADirectory = errors.New("not a directory") )
var ErrWritingString = errors.New("writing output")
ErrWritingString means there was a problem writing output to the writer passed to Print.
Functions ¶
This section is empty.
Types ¶
type Assertion ¶
type Assertion struct { // Violations, if set, indicates either whether there are violations, or how // many violations match this assertion. // // The value may be either an integer, of a string. If an integer, exactly // this number of violations must otherwise match this Assertion. If a string, // must be either "yes" or "no". If "yes" at least one violation must match // the Assertion to be satisfied. If "no", there must be zero violations // matching the Assertion to be satisfied. // // Defaults to "yes". Violations *intstr.IntOrString `json:"violations,omitempty"` // Message is a regular expression which matches the Msg field of individual // violations. // // If unset, has no effect and all violations match this Assertion. Message *string `json:"message,omitempty"` // contains filtered or unexported fields }
An Assertion is a declaration about the data returned by running an object against a Constraint.
type Case ¶
type Case struct { Name string `json:"name"` // Object is the path to the file containing a Kubernetes object to test. // NOTE: Object can be an AdmissionReview resource as well to facilitate open box testing. // To convert the object to an an AdmissionReview, the group, kind pair needs to be set // as "AdmissionReview, admission.k8s.io" Object string `json:"object"` // Inventory is a list of paths to files containing Kubernetes objects to put // in data.inventory for testing referential constraints. Inventory []string `json:"inventory"` // Assertions are statements which must be true about the result of running // Review with the Test's Constraint on the Case's Object. // // All Assertions must succeed in order for the test to pass. // If no assertions are present, assumes reviewing Object produces no // violations. Assertions []Assertion `json:"assertions"` // Skip, if true, skips this Case. Skip bool `json:"skip"` }
Case runs Constraint against a YAML object.
type CaseResult ¶
type CaseResult struct { // Name is the name given to this test for the Constraint under test. Name string // Skipped is whether this Case was skipped while running its parent Test. Skipped bool // Error is the either: // 1) why this case failed, or // 2) the error which prevented running this case. // We don't need to distinguish between 1 and 2 - they are both treated as // failures. Error error // Runtime is the time it took for this Case to run. Runtime Duration // Trace is an explanation of the underlying constraint evaluation. // For instance, for OPA based evaluations, the trace is an explanation of the rego query: // https://www.openpolicyagent.org/docs/v0.44.0/policy-reference/#tracing // NOTE: This is a string pointer to differentiate between an empty ("") trace and an unset one (nil); // also for efficiency reasons as traces could be arbitrarily large theoretically. Trace *string }
CaseResult is the result of evaluating a Constraint against a kubernetes object, and comparing the result with the expected result.
func (*CaseResult) IsFailure ¶
func (r *CaseResult) IsFailure() bool
IsFailure returns true if the test failed to execute or produced an unexpected result.
type Duration ¶
Duration is an alias of time.Duration to allow for custom formatting. Otherwise time formatting must be done inline everywhere.
type Filter ¶
type Filter interface { // MatchesTest returns true if the Test should be run. MatchesTest(*Test) bool // MatchesCase returns true if Case caseName in Test testName should be run. MatchesCase(testName, caseName string) bool }
func NewFilter ¶
NewFilter parses run into a Filter for selecting constraint tests and individual cases to run.
Empty string results in a Filter which matches all tests and their cases.
Examples: 1) NewFiler("require-foo-label//missing-label") Matches tests containing the string "require-foo-label" and cases containing the string "missing-label". So this would match all of the following: - Test: "require-foo-label", Case: "missing-label" - Test: "not-require-foo-label, Case: "not-missing-label" - Test: "require-foo-label", Case: "missing-label-and-annotation"
2) NewFilter("missing-label") Matches cases which either have a name containing "missing-label" or which are in a test named "missing-label". Matches the following: - Test: "forbid-missing-label", Case: "with-foo-label" - Test: "required-labels", Case: "missing-label"
3) NewFilter("^require-foo-label$//") Matches tests which exactly match "require-foo-label". Matches the following: - Test: "require-foo-label", Case: "with-foo-label" - Test: "require-foo-label", Case: "no-labels"
4) NewFilter("//empty-object") Matches tests whose names contain the string "empty-object". Matches the following: - Test: "forbid-foo-label", Case: "empty-object" - Test: "forbid-foo-label", Case: "another-empty-object" - Test: "require-bar-annotation", Case: "empty-object".
type Printer ¶
type Printer interface { // Print formats and writes SuiteResult to w. If verbose it true, prints more // extensive output (behavior is specific to the printer). Returns an error // if there is a problem writing to w. Print(w StringWriter, r []SuiteResult, verbose bool) error }
Printer knows how to print the results of running a Suite.
type PrinterGo ¶
type PrinterGo struct{}
func (PrinterGo) Print ¶
func (p PrinterGo) Print(w StringWriter, r []SuiteResult, verbose bool) error
func (PrinterGo) PrintCase ¶
func (p PrinterGo) PrintCase(w StringWriter, r *CaseResult, verbose bool) error
func (PrinterGo) PrintSuite ¶
func (p PrinterGo) PrintSuite(w StringWriter, r *SuiteResult, verbose bool) error
func (PrinterGo) PrintTest ¶
func (p PrinterGo) PrintTest(w StringWriter, r *TestResult, verbose bool) error
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner defines logic independent of how tests are run and the results are printed.
type RunnerOptions ¶
type RunnerOptions func(*Runner)
func IncludeTrace ¶
func IncludeTrace(includeTrace bool) RunnerOptions
func UseK8sCEL ¶
func UseK8sCEL(useK8sCEL bool) RunnerOptions
type StringWriter ¶
StringWriter knows how to write a string to a Writer.
Note: StringBuffer meets this interface.
type Suite ¶
type Suite struct { metav1.ObjectMeta // Tests is a list of Template&Constraint pairs, with tests to run on // each. Tests []Test `json:"tests"` // AbsolutePath is the absolute filepath of this Suite on disk. AbsolutePath string `json:"-"` // InputPath is the filepath passed by clients using this Suite. InputPath string `json:"-"` // Skip, if true, skips this Suite. Skip bool `json:"skip"` }
Suite defines a set of Constraint tests.
func ReadSuites ¶
ReadSuites returns the set of test Suites selected by path.
- If path is a path to a Suite, parses and returns the Suite.
- If the path is a directory and recursive is false, returns only the Suites defined in that directory.
- If the path is a directory and recursive is true returns all Suites in that directory and its subdirectories.
Returns an error if: - path is a file that does not define a Suite - any matched files containing Suites are not parseable.
type SuiteResult ¶
type SuiteResult struct { // Path is the path to the file which defines Suite. // This may be absolute or relative. Path string // Error is the error which stopped the Suite from executing. // If defined, TestResults is empty. Error error // Runtime is the time it took for this Suite of tests to run. Runtime Duration // TestResults are the results of running the tests for each defined // Template/Constraint pair. TestResults []TestResult // Skipped is whether this Suite was skipped and not run. Skipped bool }
SuiteResult is the Result of running a Suite of tests.
func (*SuiteResult) IsFailure ¶
func (r *SuiteResult) IsFailure() bool
IsFailure returns true if there was a problem running the Suite, or one of the Constraint tests failed.
type Test ¶
type Test struct { Name string `json:"name"` // Template is the path to the ConstraintTemplate, relative to the file // defining the Suite. Template string `json:"template"` // Constraint is the path to the Constraint, relative to the file defining // the Suite. Must be an instance of Template. Constraint string `json:"constraint"` // Cases are the test cases to run on the instantiated Constraint. // Mutually exclusive with Invalid. Cases []*Case `json:"cases,omitempty"` // Invalid, if true, specifies that the Constraint is expected to be invalid // for the Template. For example - a required field is missing or is of the // wrong type. // Mutually exclusive with Cases. Invalid bool `json:"invalid"` // Skip, if true, skips this Test. Skip bool `json:"skip"` }
Test defines a Template&Constraint pair to instantiate, and Cases to run on the instantiated Constraint.
type TestResult ¶
type TestResult struct { // Name is the name given to the Template/Constraint pair under test. Name string // Skipped is whether this Test was skipped while running its parent Suite. Skipped bool // Error is the error which prevented running tests for this Constraint. // If defined, CaseResults is empty. Error error // Runtime is the time it took for the Template/Constraint to be compiled, and // the test Cases to run. Runtime Duration // CaseResults are individual results for all tests defined for this Constraint. CaseResults []CaseResult }
TestResult is the results of: 1) Compiling the ConstraintTemplate, 2) Instantiating the Constraint, and 3) Running all Tests defined for the Constraint.
func (*TestResult) IsFailure ¶
func (r *TestResult) IsFailure() bool
IsFailure returns true if there was a problem running the Constraint tests, or one of its Tests failed.