failure

package
v0.0.0-...-e834411 Latest Latest
Warning

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

Go to latest
Published: Dec 4, 2024 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	FindingTypeHint_name = map[int32]string{
		0: "Text",
		1: "UnifiedDiff",
		2: "CmpDiff",
	}
	FindingTypeHint_value = map[string]int32{
		"Text":        0,
		"UnifiedDiff": 1,
		"CmpDiff":     2,
	}
)

Enum value maps for FindingTypeHint.

View Source
var (
	FindingLogLevel_name = map[int32]string{
		0: "Unknown",
		1: "Error",
		2: "Warn",
	}
	FindingLogLevel_value = map[string]int32{
		"Unknown": 0,
		"Error":   1,
		"Warn":    2,
	}
)

Enum value maps for FindingLogLevel.

View Source
var File_go_chromium_org_luci_common_testing_truth_failure_summary_proto protoreflect.FileDescriptor

Functions

This section is empty.

Types

type Comparison

type Comparison struct {

	// This is the logical name of the comparison function that produced this
	// Summary, e.g. `should.Equal` or `should.HaveLength`.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Optional type argument names. Will be used with name like
	// `should.Equal[T[0], ...]`.
	//
	// Non-primitive types should be the short Go type name like
	// `pkgname.TypeName`.
	TypeArguments []string `protobuf:"bytes,2,rep,name=type_arguments,json=typeArguments,proto3" json:"type_arguments,omitempty"`
	// Optional argument values. Will be used with name like
	// `should.HaveLength(arg)`.
	Arguments []string `protobuf:"bytes,3,rep,name=arguments,proto3" json:"arguments,omitempty"`
	// contains filtered or unexported fields
}

Comparison describes the comparison function or operation which produced a failure.Summary.

func (*Comparison) Descriptor deprecated

func (*Comparison) Descriptor() ([]byte, []int)

Deprecated: Use Comparison.ProtoReflect.Descriptor instead.

func (*Comparison) GetArguments

func (x *Comparison) GetArguments() []string

func (*Comparison) GetName

func (x *Comparison) GetName() string

func (*Comparison) GetTypeArguments

func (x *Comparison) GetTypeArguments() []string

func (*Comparison) ProtoMessage

func (*Comparison) ProtoMessage()

func (*Comparison) ProtoReflect

func (x *Comparison) ProtoReflect() protoreflect.Message

func (*Comparison) Reset

func (x *Comparison) Reset()

func (*Comparison) String

func (x *Comparison) String() string

type Finding

type Finding struct {

	// The name of this finding. Some conventional values:
	//   - Expected - the Go rendering of the actual value that the Comparison
	//     evaluated.
	//   - Actual - the Go rendering of the actual value that the Comparison
	//     evaluated.
	//   - Diff - a combination of the Expected and Actual values which reveals
	//     something useful about the comparison. Usually computed with go-cmp,
	//     but it doesn't have to be!
	//   - Because - an explaination (in English :/) of why the Comparison
	//     failed.
	//
	// However, the name only needs to make sense in the context of the
	// Comparison, so use a name which makes sense.
	//
	// Also recall that you can have multiple Findings, and they will be
	// rendered in order.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// The value of this Finding as a list of lines.
	//
	// The content here is completely up to you and needs to make sense in the
	// context of the Comparison and this Finding's name.
	//
	// See also `type`.
	Value []string `protobuf:"bytes,2,rep,name=value,proto3" json:"value,omitempty"`
	// This is a type hint for the renderer, when the renderer may like to
	// interpret `value` in some way to display it better (for example - to
	// colorize the output).
	//
	// This hint system is expected to be a 'good enough' compromise vs. trying
	// to have the renderer directly compute things like diffs.
	Type FindingTypeHint `protobuf:"varint,3,opt,name=type,proto3,enum=luci.common.testing.assert.failure.FindingTypeHint" json:"type,omitempty"`
	// Level is the "log level" of this finding.
	Level FindingLogLevel `protobuf:"varint,4,opt,name=level,proto3,enum=luci.common.testing.assert.failure.FindingLogLevel" json:"level,omitempty"`
	// contains filtered or unexported fields
}

Finding is a fact which is logically associated with this Summary (which, in turn, is the outcome of a failing Comparison).

Each finding has a 'name' and a 'value'.

Typically, these can be renderings of the compared values (typically named "Expected" and/or "Actual"), a combination of the compared values (e.g. "Diff"), or a summary of why the comparison failed (e.g. "Because").

A Finding may also have a hint to the renderer about how `value` could be interpreted. This can be used to e.g. add color to a diff.

We previously considered storing the ACTUAL values, and then having the rendering process compute the diff, but:

  • This is generally impossible if the Summary needs to traverse a process boundary.
  • It turns out computing the diff on a Go type is tricky! See: go-cmp and protobuf comparison.
  • These are test results... carrying a full Go type all the way to the renderer is mega-overkill. Usually you can just add another Finding to clarify what's going on and this is sufficient to fix the test, which is why we're doing all this stuff... right? :)

func (*Finding) Descriptor deprecated

func (*Finding) Descriptor() ([]byte, []int)

Deprecated: Use Finding.ProtoReflect.Descriptor instead.

func (*Finding) GetLevel

func (x *Finding) GetLevel() FindingLogLevel

func (*Finding) GetName

func (x *Finding) GetName() string

func (*Finding) GetType

func (x *Finding) GetType() FindingTypeHint

func (*Finding) GetValue

func (x *Finding) GetValue() []string

func (*Finding) ProtoMessage

func (*Finding) ProtoMessage()

func (*Finding) ProtoReflect

func (x *Finding) ProtoReflect() protoreflect.Message

func (*Finding) Reset

func (x *Finding) Reset()

func (*Finding) String

func (x *Finding) String() string

type FindingLogLevel

type FindingLogLevel int32

FindingLogLevel is the "log level" (like debug, info &c) of the finding.

We are not including the full suite of log4j-esque levels because we don't need them all.

const (
	// Unknown is the default value.
	FindingLogLevel_Unknown FindingLogLevel = 0
	// Error indicates that the finding is an error-level finding.
	// These are always shown.
	FindingLogLevel_Error FindingLogLevel = 1
	// Warn indicates that the finding is a warn-level finding.
	// These should only be shown when the user wants verbose stuff.
	FindingLogLevel_Warn FindingLogLevel = 2
)

func (FindingLogLevel) Descriptor

func (FindingLogLevel) Enum

func (x FindingLogLevel) Enum() *FindingLogLevel

func (FindingLogLevel) EnumDescriptor deprecated

func (FindingLogLevel) EnumDescriptor() ([]byte, []int)

Deprecated: Use FindingLogLevel.Descriptor instead.

func (FindingLogLevel) Number

func (FindingLogLevel) String

func (x FindingLogLevel) String() string

func (FindingLogLevel) Type

type FindingTypeHint

type FindingTypeHint int32

FindingTypeHint is a type hint for the Summary.Finding.type field.

This is declared as a top-level type to avoid ugly Summary_Finding_FindingTypeXXX symbols.

const (
	// Indicates that `value` is just a verbatim string and needs no special
	// rendering.
	FindingTypeHint_Text FindingTypeHint = 0
	// These indicate that `value` is a kind of diff and MAY be colorized by
	// the renderer if appropriate.
	FindingTypeHint_UnifiedDiff FindingTypeHint = 1
	FindingTypeHint_CmpDiff     FindingTypeHint = 2
)

func (FindingTypeHint) Descriptor

func (FindingTypeHint) Enum

func (x FindingTypeHint) Enum() *FindingTypeHint

func (FindingTypeHint) EnumDescriptor deprecated

func (FindingTypeHint) EnumDescriptor() ([]byte, []int)

Deprecated: Use FindingTypeHint.Descriptor instead.

func (FindingTypeHint) Number

func (FindingTypeHint) String

func (x FindingTypeHint) String() string

func (FindingTypeHint) Type

type Stack

type Stack struct {
	Name   string         `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	Frames []*Stack_Frame `protobuf:"bytes,2,rep,name=frames,proto3" json:"frames,omitempty"`
	// contains filtered or unexported fields
}

Stack is an arbitrary source code context attached to a failure.Summary.

Conventional names:

  • "at" - The single filename/lineno of where the assertion took place. This can be added by using `truth.LineContext()` on a returned *Failure from a comparison.Func, or by using `assert.WithContext...` or `check.WithContext...`. This is useful when writing assertion helper functions - Go will report the filename:NN of the 'top most' stack frame, as calculated via testing.T.Helper calls, but sometimes you also want to add the location of the assert itself, inside the helper.

This can also be used to attach things like panic stack traces, etc. to a Failure.

func (*Stack) Descriptor deprecated

func (*Stack) Descriptor() ([]byte, []int)

Deprecated: Use Stack.ProtoReflect.Descriptor instead.

func (*Stack) GetFrames

func (x *Stack) GetFrames() []*Stack_Frame

func (*Stack) GetName

func (x *Stack) GetName() string

func (*Stack) ProtoMessage

func (*Stack) ProtoMessage()

func (*Stack) ProtoReflect

func (x *Stack) ProtoReflect() protoreflect.Message

func (*Stack) Reset

func (x *Stack) Reset()

func (*Stack) String

func (x *Stack) String() string

type Stack_Frame

type Stack_Frame struct {
	Filename string `protobuf:"bytes,1,opt,name=filename,proto3" json:"filename,omitempty"`
	Lineno   int64  `protobuf:"varint,2,opt,name=lineno,proto3" json:"lineno,omitempty"`
	// contains filtered or unexported fields
}

func (*Stack_Frame) Descriptor deprecated

func (*Stack_Frame) Descriptor() ([]byte, []int)

Deprecated: Use Stack_Frame.ProtoReflect.Descriptor instead.

func (*Stack_Frame) GetFilename

func (x *Stack_Frame) GetFilename() string

func (*Stack_Frame) GetLineno

func (x *Stack_Frame) GetLineno() int64

func (*Stack_Frame) ProtoMessage

func (*Stack_Frame) ProtoMessage()

func (*Stack_Frame) ProtoReflect

func (x *Stack_Frame) ProtoReflect() protoreflect.Message

func (*Stack_Frame) Reset

func (x *Stack_Frame) Reset()

func (*Stack_Frame) String

func (x *Stack_Frame) String() string

type Summary

type Summary struct {

	// Information about the Comparison which produced this failure Summary.
	Comparison *Comparison `protobuf:"bytes,1,opt,name=comparison,proto3" json:"comparison,omitempty"`
	// Optional list of source code context, in the form of whole or partial stack
	// traces.
	SourceContext []*Stack `protobuf:"bytes,2,rep,name=source_context,json=sourceContext,proto3" json:"source_context,omitempty"`
	// The list of findings that describe this failure.
	Findings []*Finding `protobuf:"bytes,3,rep,name=findings,proto3" json:"findings,omitempty"`
	// contains filtered or unexported fields
}

Summary is the factual outcome of a failing Comparison.

As an example:

comparison { name: "should.Equal" type_arguments: "string" }
findings { name: "Expected" value: "\"hello\"" }
findings { name: "Actual" value: "\"meepmorp\"" }

Will be rendered for the CLI like:

filename_test.go:123: Check should.Equal[string] FAILED
                        Expected: "hello"
                        Actual: "meepmorp"

In the future we expect other interfaces (like a web browser) to render these in a similarly suitable way.

Note that failure.Summary is not intended to be hand-assembled, but is meant to be built with the FailureBuilder functionality in the comparison package.

func (*Summary) Descriptor deprecated

func (*Summary) Descriptor() ([]byte, []int)

Deprecated: Use Summary.ProtoReflect.Descriptor instead.

func (*Summary) GetComparison

func (x *Summary) GetComparison() *Comparison

func (*Summary) GetFindings

func (x *Summary) GetFindings() []*Finding

func (*Summary) GetSourceContext

func (x *Summary) GetSourceContext() []*Stack

func (*Summary) ProtoMessage

func (*Summary) ProtoMessage()

func (*Summary) ProtoReflect

func (x *Summary) ProtoReflect() protoreflect.Message

func (*Summary) Reset

func (x *Summary) Reset()

func (*Summary) String

func (x *Summary) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL