failure

package
v0.0.0-...-527d38f Latest Latest
Warning

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

 Go to latest Published: Nov 28, 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) Descriptor() protoreflect.EnumDescriptor

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 (x FindingLogLevel) Number() protoreflect.EnumNumber

func (FindingLogLevel) String 

func (x FindingLogLevel) String() string

func (FindingLogLevel) Type 

func (FindingLogLevel) Type() protoreflect.EnumType

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) Descriptor() protoreflect.EnumDescriptor

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 (x FindingTypeHint) Number() protoreflect.EnumNumber

func (FindingTypeHint) String 

func (x FindingTypeHint) String() string

func (FindingTypeHint) Type 

func (FindingTypeHint) Type() protoreflect.EnumType

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

Source Files

View all Source files

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.