goldclient

Documentation

Index

• Constants
• func WithContext(ctx context.Context, g gcsuploader.GCSUploader, h httpclient.HTTPClient, ...) context.Context
• type CloudClient
  • func LoadCloudClient(workDir string) (*CloudClient, error)
  • func NewCloudClient(config GoldClientConfig) (*CloudClient, error)
  • func (c *CloudClient) Check(ctx context.Context, name types.TestName, imgFileName string, ...) (bool, error)
  • func (c *CloudClient) Diff(ctx context.Context, grouping paramtools.Params, imgFileName, outDir string) error
  • func (c *CloudClient) DumpBaseline() (string, error)
  • func (c *CloudClient) DumpKnownHashes() (string, error)
  • func (c *CloudClient) Finalize(ctx context.Context) error
  • func (c *CloudClient) MostRecentPositiveDigest(ctx context.Context, id tiling.TraceIDV2) (types.Digest, error)
  • func (c *CloudClient) SetSharedConfig(ctx context.Context, sharedConfig jsonio.GoldResults, skipValidation bool) error
  • func (c *CloudClient) Test(ctx context.Context, name types.TestName, imgFileName string, ...) (bool, error)
  • func (c *CloudClient) TriageAsPositive(ctx context.Context, testName types.TestName, digest types.Digest, ...) error
  • func (c *CloudClient) Whoami(ctx context.Context) (string, error)
• type GoldClient
• type GoldClientConfig
• type GoldClientDebug

Constants

const (
	// ErrorWriterKey is the context key used for the error Writer. If not provided, StdErr will
	// be used.
	ErrorWriterKey = contextKey("errWriter")
	// LogWriterKey is the context key used for the log Writer.  If not provided, StdOut will
	// be used.
	LogWriterKey = contextKey("logWriter")
)

Functions

func WithContext

func WithContext(ctx context.Context, g gcsuploader.GCSUploader, h httpclient.HTTPClient, i imagedownloader.ImageDownloader) context.Context

WithContext returns a context with the given authenticated network clients loaded. By putting these values on the context, it makes it easier to stub out during tests and not require several extra arguments on each function call. Failure to have these set will result in panics when the function is called. If values have already been set on this context, the new value will be ignored.

Types

type CloudClient

type CloudClient struct {
	// contains filtered or unexported fields
}

CloudClient implements the GoldClient interface for the remote Gold service.

func LoadCloudClient

func LoadCloudClient(workDir string) (*CloudClient, error)

LoadCloudClient returns a GoldClient that has previously been stored to disk in the path given by workDir.

func NewCloudClient

func NewCloudClient(config GoldClientConfig) (*CloudClient, error)

NewCloudClient returns an implementation of the GoldClient that relies on the Gold service. If a new instance is created for each call to Test, the arguments of the first call are preserved. They are cached in a JSON file in the work directory.

func (*CloudClient) Check

func (c *CloudClient) Check(ctx context.Context, name types.TestName, imgFileName string, keys, optionalKeys map[string]string) (bool, error)

Check implements the GoldClient interface.

func (*CloudClient) Diff

func (c *CloudClient) Diff(ctx context.Context, grouping paramtools.Params, imgFileName, outDir string) error

Diff fulfills the GoldClient interface.

func (*CloudClient) DumpBaseline

func (c *CloudClient) DumpBaseline() (string, error)

DumpBaseline fulfills the GoldClientDebug interface

func (*CloudClient) DumpKnownHashes

func (c *CloudClient) DumpKnownHashes() (string, error)

DumpKnownHashes fulfills the GoldClientDebug interface

func (*CloudClient) Finalize

func (c *CloudClient) Finalize(ctx context.Context) error

Finalize implements the GoldClient interface.

func (*CloudClient) MostRecentPositiveDigest

func (c *CloudClient) MostRecentPositiveDigest(ctx context.Context, id tiling.TraceIDV2) (types.Digest, error)

MostRecentPositiveDigest fulfills the GoldClient interface.

func (*CloudClient) SetSharedConfig

func (c *CloudClient) SetSharedConfig(ctx context.Context, sharedConfig jsonio.GoldResults, skipValidation bool) error

SetSharedConfig implements the GoldClient interface.

func (*CloudClient) Test

func (c *CloudClient) Test(ctx context.Context, name types.TestName, imgFileName string, imgDigest types.Digest, additionalKeys, optionalKeys map[string]string) (bool, error)

Test implements the GoldClient interface.

func (*CloudClient) TriageAsPositive

func (c *CloudClient) TriageAsPositive(ctx context.Context, testName types.TestName, digest types.Digest, algorithmName string) error

TriageAsPositive fulfills the GoldClient interface.

func (*CloudClient) Whoami

func (c *CloudClient) Whoami(ctx context.Context) (string, error)

Whoami fulfills the GoldClient interface.

type GoldClient

type GoldClient interface {
	// SetSharedConfig populates the config with details that will be shared
	// with all tests. This is safe to be called more than once, although
	// new settings will overwrite the old ones. This will cause the
	// baseline and known hashes to be (re-)downloaded from Gold.
	SetSharedConfig(ctx context.Context, sharedConfig jsonio.GoldResults, skipValidation bool) error

	// Test adds a test result to the current test run.
	//
	// The provided image will be uploaded to GCS if the hash of its pixels has not been seen before.
	// Using auth.SetDryRun(true) can prevent this. If imgDigest is provided, that hash will
	// override the built-in hashing. If imgDigest is provided and imgFileName is not, it is assumed
	// that the image has already been uploaded to GCS.
	//
	// additionalKeys is an optional set of key/value pairs that apply to only this test. This is
	// typically a small amount of data (and can be nil). If there are many keys, they are likely
	// shared between tests and should be added in SetSharedConfig.
	//
	// optionalKeys can be used to specify a non-exact image matching algorithm and its parameters,
	// and any other optional keys specific to this test. This is optional and can be nil.
	// TODO(lovisolo): Explicitly mention key used to specify a non-exact image matching algorithm.
	//
	// If the GoldClient is configured for pass/fail mode, a JSON file will be uploaded to GCS with
	// the test results, and the returned boolean will indicate whether the test passed the
	// comparison against the baseline using the specified non-exact image matching algorithm, or
	// exact matching if none is specified.
	//
	// If the GoldClient is *not* configured for pass/fail mode, no JSON will be uploaded, and Test
	// will return true.
	//
	// An error is only returned if there was a technical problem in processing the test.
	Test(ctx context.Context, name types.TestName, imgFileName string, imgDigest types.Digest, additionalKeys, optionalKeys map[string]string) (bool, error)

	// Check operates similarly to Test, except it does not persist anything about the call. That is,
	// the image will not be uploaded to Gold, only compared against the baseline.
	//
	// Argument optionalKeys is used to specify a non-exact image matching algorithm and its
	// parameters. TODO(lovisolo): Explicitly mention the optional key used for this.
	//
	// Argument keys is required if a non-exact image matching algorithm is specified. The test keys
	// are used to compute the ID of the trace from which to retrieve the most recent positive image
	// to be used as the basis of the non-exact image comparison.
	//
	// If both keys and optionalKeys are empty, an exact comparison will be carried out against the
	// baseline.
	Check(ctx context.Context, name types.TestName, imgFileName string, keys, optionalKeys map[string]string) (bool, error)

	// Diff computes a diff of the closest image to the given image file and puts it into outDir,
	// along with the closest image file itself.
	Diff(ctx context.Context, grouping paramtools.Params, imgFileName, outDir string) error

	// Finalize uploads the JSON file for all Test() calls previously seen.
	// A no-op if configured for pass/fail mode, since the JSON would have been uploaded
	// on the calls to Test().
	Finalize(ctx context.Context) error

	// Whoami makes a request to Gold's /json/v1/whoami endpoint and returns the email address in the
	// response. For debugging purposes only.
	Whoami(ctx context.Context) (string, error)

	// TriageAsPositive triages the given digest for the given test as positive by making a request
	// to Gold's /json/v2/triage endpoint. The image matching algorithm name will be used as the author
	// of the triage operation.
	TriageAsPositive(ctx context.Context, testName types.TestName, digest types.Digest, algorithmName string) error

	// MostRecentPositiveDigest retrieves the most recent positive digest for the given trace via
	// Gold's /json/v2/latestpositivedigest/{traceId} endpoint.
	MostRecentPositiveDigest(ctx context.Context, traceId tiling.TraceIDV2) (types.Digest, error)
}

GoldClient is the uniform interface to communicate with the Gold service.

type GoldClientConfig

type GoldClientConfig struct {
	// WorkDir is a temporary directory that caches data for one run with multiple calls to GoldClient
	WorkDir string

	// InstanceID is the id of the backend Gold instance
	InstanceID string

	// PassFailStep indicates whether each call to Test(...) should return a pass/fail value.
	PassFailStep bool

	// FailureFile is a file on disk that will contain newline-separated links to triage
	// any failures. Only written to if PassFailStep is true
	FailureFile string

	// OverrideGoldURL is optional and overrides the formulaic GoldURL (typically legacy instances).
	OverrideGoldURL string

	// OverrideBucket is optional and overrides the formulaic GCS Bucket.
	OverrideBucket string

	// UploadOnly is a mode where we don't check expectations against the server - i.e.
	// we just operate in upload mode.
	UploadOnly bool
}

GoldClientConfig is a config structure to configure GoldClient instances

type GoldClientDebug

type GoldClientDebug interface {
	// DumpBaseline returns a human-readable representation of the baseline as a string.
	// This is a set of test names that each have a set of image
	// digests that each have exactly one types.Label.
	DumpBaseline() (string, error)
	// DumpKnownHashes returns a human-readable representation of the known image digests
	// which is a list of hashes.
	DumpKnownHashes() (string, error)
}

GoldClientDebug contains some "optional" methods that can assist in debugging.