results

package
v0.57.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 17, 2023 License: Apache-2.0 Imports: 24 Imported by: 4

Documentation

Overview

Package results provides a low level API to extract data from a Sonobuoy result archive.

Index

Examples

Constants

View Source 
const (
	// StatusFailed is the key we base junit pass/failure off of and save into
	// our canonical results format.
	StatusFailed = "failed"

	// StatusPassed is the key we base junit pass/failure off of and save into
	// our canonical results format.
	StatusPassed = "passed"

	// StatusSkipped is the key we base junit pass/failure off of and save into
	// our canonical results format.
	StatusSkipped = "skipped"

	// StatusUnknown is the key we fallback to in our canonical results format
	// if another can not be determined.
	StatusUnknown = "unknown"

	// StatusEmpty is just the empty string; we equate this to StatusUnknown.
	StatusEmpty = ""

	// StatusTimeout is the key used when the plugin does not report results within the
	// timeout period. It will be treated as a failure (e.g. its parent will be marked
	// as a failure).
	StatusTimeout = "timeout"

	// PostProcessedResultsFile is the name of the file we create when doing
	// postprocessing on the plugin results.
	PostProcessedResultsFile = "sonobuoy_results.yaml"

	// MetadataFileKey is the key used in an Item's metadata field when the Item is
	// representing the a file summary (and its leaf nodes are individual tests or Suites).
	MetadataFileKey = "file"

	// MetadataTypeKey is the key used in an Item's metadata field when describing what type
	// of entry in the tree it is. Currently we just tag summaries, files, and nodes.
	MetadataTypeKey = "type"

	MetadataTypeNode    = "node"
	MetadataTypeFile    = "file"
	MetadataTypeSummary = "summary"

	MetadataDetailsFailure = "failure"
	MetadataDetailsOutput  = "output"
)
View Source 
const (
	// JUnitStdoutKey is the key in the Items.Details map for the system-out output.
	JUnitStdoutKey = "system-out"

	// JUnitStderrKey is the key in the Items.Details map for the system-out output.
	JUnitStderrKey = "system-err"

	// JUnitFailureKey is the key in the Items.Details map for the failure output.
	JUnitFailureKey = "failure"

	// JUnitErrorKey is the key in the Items.Details map for the error output.
	JUnitErrorKey = "error"
)
View Source 
const (
	ResultFormatJUnit  = "junit"
	ResultFormatE2E    = "e2e"
	ResultFormatGoJSON = "gojson"
	ResultFormatRaw    = "raw"
	ResultFormatManual = "manual"
)

ResultFormat constants are the supported values for the resultFormat field which enables post processing.

View Source 
const (
	// PluginsDir defines where in the archive directories for plugin results are.
	PluginsDir = "plugins/"

	// ResultsDir defines where in the archive the plugin results are.
	// Example: plugins/<name>/results
	ResultsDir = "results/"

	// ErrorsDir defines where in the archive the errors running the plugin get reported.
	// These are the Sonobuoy reported errors, e.g. failure to start a plugin, timeout, etc.
	// This is not the appropriate directory for things like test failures.
	// Example: plugins/<name>/errors
	ErrorsDir = "errors/"

	// DefaultErrFile is the file name used when Sonobuoy is reporting an error running a plugin.
	// Is written into the ErrorsDir directory.
	DefaultErrFile = "error.json"

	// CoreNodesFile is the filename of the core nodes json output, relative to nonNamespacedResourcesDir
	CoreNodesFile = "core_v1_nodes.json"

	// CorePodsFile is the filename of the core pod json output, relative to namespacedResourcesDir
	CorePodsFile = "core_v1_pods.json"

	// InfoFile contains data not that isn't strictly in another location
	// but still relevent to post-processing or understanding the run in some way.
	InfoFile = "info.json"

	// ClusterHealthFile is the filename of the cluster health, relative to metadataDir
	ClusterHealthFile = "clusterhealth.json"
)
View Source 
const (
	// UnknownVersion lets the consumer know if this client can detect the archive version or not.
	UnknownVersion = "v?.?"
	VersionEight   = "v0.8"
	VersionNine    = "v0.9"
	VersionTen     = "v0.10"
	VersionFifteen = "v0.15"
)

Versions corresponding to Kubernetes minor version values. We used to roughly version our results tarballs in sync with minor version patches and so checking the server version for one of these prefixes would be sufficient to inform the parser where certain files would be.

Variables

This section is empty.

Functions

func AggregateStatus added in v0.54.0 

func AggregateStatus(useCustom bool, items ...Item) string

AggregateStatus defines the aggregation rules for status according to the following rules: If only pass/fail/unknown values are found, we apply very basic rules:

  • failure + * = failure
  • unknown + [pass|unknown] = unknown
  • empty list = unknown

If we find other values (e.g. from manual results typically) then we just combine/count them:

  • foo + bar = 'foo: 1, bar:1'

useCustom is specified rather than looking for custom values because different branches of the result tree may have/not have those values. So instead, we should look down the tree initially to decide.

func ClusterHealthFilePath added in v0.56.2 

func ClusterHealthFilePath() string

ClusterHealthFilePath returns the full path of the ClusterHealthFile

func ConfigFile 

func ConfigFile(version string) string

ConfigFile returns the path to the sonobuoy config file. This is not a method as it is used to determine the version of the archive.

func DiscoverVersion 

func DiscoverVersion(reader io.Reader) (string, error)

DiscoverVersion takes a Sonobuoy archive stream and extracts just the version of the archive.

func ExtractBytes 

func ExtractBytes(file string, path string, info os.FileInfo, buf *bytes.Buffer) error

ExtractBytes pulls out bytes into a buffer for any path matching file.

func ExtractConfig 

func ExtractConfig(path string, info os.FileInfo, conf *config.Config) error

ExtractConfig populates the config object regardless of version.

func ExtractFileIntoStruct 

func ExtractFileIntoStruct(file, path string, info os.FileInfo, object interface{}) error

ExtractFileIntoStruct is a helper for a common use case of extracting the contents of one file into the object. The first parameter is the desired file to extract, the second is the path being considered (by a WalkFn).

func ExtractIntoStruct 

func ExtractIntoStruct(predicate func(string) bool, path string, info os.FileInfo, object interface{}) error

ExtractIntoStruct takes a predicate function and some file information and decodes the contents of the file that matches the predicate into the interface passed in (generally a pointer to a struct/slice).

func FileOrAny added in v0.56.4 

func FileOrAny(files []string) func(fPath string, info os.FileInfo) bool

func FileOrExtension added in v0.56.4 

func FileOrExtension(files []string, exts ...string) fileSelector

FileOrExtension returns a function which will return true for files which have the exact name of the file given or the given extension (if no file is given). If the filename given is empty, it will be ignored and the extension matching will be used. If "*" is passed as the extension all files will match.

func IsFailureStatus added in v0.54.0 

func IsFailureStatus(s string) bool

IsFailureStatus returns true if the status is any one of the failure modes (e.g. StatusFailed or StatusTimeout).

func IsTimeoutErr added in v0.54.0 

func IsTimeoutErr(i Item) bool

IsTimeoutErr is the snippet of logic that determines whether or not a given Item represents a timeout error (i.e. Sonobuoy timed out waiting for results).

func JUnitErrored added in v0.17.1 

func JUnitErrored(testCase JUnitTestCase) bool

JUnitErrored returns true if the test errored.

func JUnitFailed added in v0.15.3 

func JUnitFailed(testCase JUnitTestCase) bool

JUnitFailed returns true if the test failed.

func JUnitPassed added in v0.15.3 

func JUnitPassed(testCase JUnitTestCase) bool

JUnitPassed returns true if the test passed.

func JUnitSkipped added in v0.15.3 

func JUnitSkipped(testCase JUnitTestCase) bool

JUnitSkipped returns true if the test was skipped.

func SaveProcessedResults added in v0.15.1 

func SaveProcessedResults(pluginName, baseDir string, item Item) error

SaveProcessedResults saves the given item in the predefined location for the postprocessed results (the path base/plugins/plugin_name/sonobuoy_results)

Types

type Item added in v0.15.1 

type Item struct {
	Name     string                 `json:"name" yaml:"name"`
	Status   string                 `json:"status" yaml:"status"`
	Metadata map[string]string      `json:"meta,omitempty" yaml:"meta,omitempty"`
	Details  map[string]interface{} `json:"details,omitempty" yaml:"details,omitempty"`
	Items    []Item                 `json:"items,omitempty" yaml:"items,omitempty"`
}

Item is the central format for plugin results. Various plugin types can be transformed into this simple format and set at a standard location in our results tarball for simplified processing by any consumer.

func GojsonProcessFile added in v0.56.4 

func GojsonProcessFile(pluginDir, currentFile string) (Item, error)

func JunitProcessFile added in v0.56.4 

func JunitProcessFile(pluginDir, currentFile string) (Item, error)

func PostProcessPlugin added in v0.15.1 

func PostProcessPlugin(p plugin.Interface, dir string) (Item, []error)

PostProcessPlugin will inspect the files in the given directory (representing the location of the results directory for a sonobuoy run, not the plugin specific results directory). Based on the type of plugin results, it will record what tests passed/failed (if junit) or record what files were produced (if raw) and return that information in an Item object. All errors encountered are returned.

func ProcessDir added in v0.56.4 

func ProcessDir(p plugin.Interface, pluginDir, dir string, processor postProcessor, shouldProcessFile fileSelector) ([]Item, error)

ProcessDir will walk the files in a given directory, using the fileSelector function to choose which files to process with the postProcessor. The plugin directory is also passed in (e.g. plugins/e2e) in order to make filepaths relative to that directory.

func RawProcessFile added in v0.56.4 

func RawProcessFile(pluginDir, currentFile string) (Item, error)

RawProcessFile will return an Item object with the File value set to the path in question. If the file is unable to be stat'd then the status of the Item is StatusFailed (StatusPassed otherwise).

func (Item) Empty added in v0.15.1 

func (i Item) Empty() bool

Empty returns true if the Item is empty.

func (*Item) GetSubTreeByName added in v0.17.1 

func (i *Item) GetSubTreeByName(root string) *Item

GetSubTreeByName traverses the tree and returns a reference to the subtree whose root has the given name.

func (*Item) IsLeaf added in v0.56.4 

func (i *Item) IsLeaf() bool

IsLeaf returns true if the item has no sub-items (children). Typically refers to individual tests whereas non-leaf nodes more commonly refer to suites, nodes, or files rolled up from the individual tests.

func (*Item) Walk added in v0.56.4 

func (i *Item) Walk(fn func(*Item) error) error

Walk will do a depth-first traversal of the Item tree calling fn on each item. If an error is returned, traversal will stop.

type JUnitAlphabetizedTestCases added in v0.15.3 

type JUnitAlphabetizedTestCases []JUnitTestCase

JUnitAlphabetizedTestCases implements Sort over the list of testCases.

func (JUnitAlphabetizedTestCases) Len added in v0.15.3 

func (a JUnitAlphabetizedTestCases) Len() int

func (JUnitAlphabetizedTestCases) Less added in v0.15.3 

func (a JUnitAlphabetizedTestCases) Less(i, j int) bool

func (JUnitAlphabetizedTestCases) Swap added in v0.15.3 

func (a JUnitAlphabetizedTestCases) Swap(i, j int)

type JUnitErrorMessage added in v0.17.1 

type JUnitErrorMessage struct {
	Message  string `xml:"message,attr"`
	Type     string `xml:"type,attr"`
	Contents string `xml:",chardata"`
}

JUnitErrorMessage contains data related to a failed test.

type JUnitFailureMessage added in v0.15.3 

type JUnitFailureMessage struct {
	Message  string `xml:"message,attr"`
	Type     string `xml:"type,attr"`
	Contents string `xml:",chardata"`
}

JUnitFailureMessage contains data related to a failed test.

type JUnitProperty added in v0.15.3 

type JUnitProperty struct {
	Name  string `xml:"name,attr"`
	Value string `xml:"value,attr"`
}

JUnitProperty represents a key/value pair used to define properties.

type JUnitResult added in v0.55.1 

type JUnitResult struct {
	Suites JUnitTestSuites
}

JUnitResult is a wrapper around the suite[s] which enable results to be either a single suite or a collection of suites. For instance, e2e tests (which use the onsi/ginkgo reporter) report a single, top-level testsuite whereas other tools report a top-level testsuites object which may have 1+ testsuite children. Only one of the fields should be set, not both.

func (*JUnitResult) UnmarshalXML added in v0.55.1 

func (j *JUnitResult) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML will unmarshal the document into either the 'Suites' field of the JUnitResult. If a single testsuite is found (instead of a testsuites object) it is unmarshalled and then added into the set of JUnitResult.Suites.Suites

type JUnitSkipMessage added in v0.15.3 

type JUnitSkipMessage struct {
	Message string `xml:"message,attr"`
}

JUnitSkipMessage contains the reason why a testcase was skipped.

type JUnitTestCase added in v0.15.3 

type JUnitTestCase struct {
	XMLName      xml.Name             `xml:"testcase"`
	Classname    string               `xml:"classname,attr"`
	Name         string               `xml:"name,attr"`
	Time         string               `xml:"time,attr"`
	SkipMessage  *JUnitSkipMessage    `xml:"skipped,omitempty"`
	Failure      *JUnitFailureMessage `xml:"failure,omitempty"`
	ErrorMessage *JUnitErrorMessage   `xml:"error,omitempty"`
	SystemOut    string               `xml:"system-out,omitempty"`
	SystemErr    string               `xml:"system-err,omitempty"`
}

JUnitTestCase is a single test case with its result.

func JUnitFilter added in v0.15.3 

func JUnitFilter(predicate func(testCase JUnitTestCase) bool, testSuite JUnitTestSuite) []JUnitTestCase

JUnitFilter keeps only the tests that match the predicate function.

type JUnitTestSuite added in v0.15.3 

type JUnitTestSuite struct {
	XMLName    xml.Name        `xml:"testsuite"`
	Tests      int             `xml:"tests,attr"`
	Failures   int             `xml:"failures,attr"`
	Time       float64         `xml:"time,attr"`
	Name       string          `xml:"name,attr"`
	Properties []JUnitProperty `xml:"properties>property,omitempty"`
	TestCases  []JUnitTestCase `xml:"testcase"`
}

JUnitTestSuite is a single JUnit test suite which may contain many testcases.

type JUnitTestSuites added in v0.15.3 

type JUnitTestSuites struct {
	XMLName xml.Name         `xml:"testsuites"`
	Suites  []JUnitTestSuite `xml:"testsuite"`
}

JUnitTestSuites is a collection of JUnit test suites.

type Reader 

type Reader struct {
	// Embedded reader assumed to be the *.tar.gz of results. If the tarball has
	// been extracted already, set the RootDir instead.
	io.Reader

	// RootDir, if set, instructs the reader to read as if the tarball of results
	// was extracted to the given root directory.
	RootDir string

	Version string
}

Reader holds a reader and a version. It uses the version to know where to find files within the archive.

func NewReaderFromBytes 

func NewReaderFromBytes(data []byte) (*Reader, error)

NewReaderFromBytes is a helper constructor that will discover the version of the archive and return a new Reader with the correct version already populated.

Example 
package main

import (
	"fmt"
	"os"

	"github.com/vmware-tanzu/sonobuoy/pkg/client/results"
)

func main() {
	path := "testdata/results-0.8.tar.gz"
	data, err := os.ReadFile(path)
	if err != nil {
		panic(err)
	}
	results, err := results.NewReaderFromBytes(data)
	if err != nil {
		panic(err)
	}
	fmt.Println(results.Version)
}

Output:

v0.8

func NewReaderFromDir added in v0.56.3 

func NewReaderFromDir(root string) *Reader

NewReaderFromDir creates a reader that will process the directory `root`. It is assumed this directory contains the extracted results. Note: Assumes 'VersionFifteen' of results, which is current as of this writing. Older versions probably don't even need support at this point.

func NewReaderWithVersion 

func NewReaderWithVersion(reader io.Reader, version string) *Reader

NewReaderWithVersion creates a results.Reader that interprets a results archive of the version passed in. Useful if the reader can be read only once and if the version of the data to read is known.

Example 
package main

import (
	"compress/gzip"
	"fmt"
	"os"

	"github.com/vmware-tanzu/sonobuoy/pkg/client/results"
)

func main() {
	path := "testdata/results-0.9.tar.gz"
	f, err := os.Open(path)
	if err != nil {
		panic(err)
	}
	reader, err := gzip.NewReader(f)
	if err != nil {
		panic(err)
	}
	r := results.NewReaderWithVersion(reader, results.VersionNine)
	fmt.Println(r.Version)
}

Output:

v0.9

func (*Reader) FileReader added in v0.15.1 

func (r *Reader) FileReader(filename string) (io.Reader, error)

FileReader returns a reader for a file in the archive.

func (*Reader) Metadata 

func (r *Reader) Metadata() string

Metadata is the location of the metadata directory in the results archive.

func (*Reader) NamespacedResources 

func (r *Reader) NamespacedResources() string

NamespacedResources returns the path to the directory that contains information about namespaced Kubernetes resources.

func (*Reader) NodesFile 

func (r *Reader) NodesFile() string

NodesFile returns the path to the file that lists the nodes of the Kubernetes cluster.

func (*Reader) NonNamespacedResources 

func (r *Reader) NonNamespacedResources() string

NonNamespacedResources returns the path to the non-namespaced directory.

func (*Reader) PluginResultsItem added in v0.15.1 

func (r *Reader) PluginResultsItem(plugin string) (*Item, error)

PluginResultsItem returns the results file from the given plugin if found, error otherwise.

func (*Reader) PluginResultsReader added in v0.15.1 

func (r *Reader) PluginResultsReader(plugin string) (io.Reader, error)

PluginResultsReader returns the results file from the given plugin if found, error otherwise.

func (*Reader) ReadVersion added in v0.56.3 

func (r *Reader) ReadVersion() (string, error)

func (*Reader) RunInfoFile added in v0.16.1 

func (r *Reader) RunInfoFile() string

RunInfoFile returns the path to the Sonobuoy RunInfo file which is extra metadata about the run. This was added in v0.16.1. The function will return the same string even for earlier versions where that file does not exist.

func (*Reader) ServerGroupsFile 

func (r *Reader) ServerGroupsFile() string

ServerGroupsFile returns the path to the groups the Kubernetes API supported at the time of the run.

func (*Reader) ServerVersionFile 

func (r *Reader) ServerVersionFile() string

ServerVersionFile is the location of the file that contains the Kubernetes version Sonobuoy ran on.

func (*Reader) WalkFiles 

func (r *Reader) WalkFiles(walkfn filepath.WalkFunc) error

WalkFiles walks all of the files in the archive. Processing stops at the first error. The error is returned except in the special case of errStopWalk which will stop processing but nil will be returned. In the case where the reader is based on a directory (not a tarball) ensure the WalkFuncs realize that the root directory will be part of the path.

Source Files

View all Source files

Directories

Path Synopsis
package e2e defines files and directories found in the e2e plugin results.
 package e2e defines files and directories found in the e2e plugin results.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.