ctxerr

Documentation

Index

• Variables
• type Context
  • func (c Context) AddArrayIndex(index int) (new Context)
  • func (c Context) AddCustomLevel(pathAdd string) (new Context)
  • func (c Context) AddField(field string) (new Context)
  • func (c Context) AddFunctionCall(fn string) (new Context)
  • func (c Context) AddMapKey(key any) (new Context)
  • func (c Context) AddPtr(num int) (new Context)
  • func (c Context) CannotCompareError() *Error
  • func (c Context) CollectError(err *Error) *Error
  • func (c *Context) InitErrors()
  • func (c Context) MergeErrors() *Error
  • func (c Context) ResetErrors() (new Context)
  • func (c Context) ResetPath(newRoot string) (new Context)
• type Error
  • func BadKind(got reflect.Value, okKinds string) *Error
  • func NilPointer(got reflect.Value, expected string) *Error
  • func OpBad(op, s string, args ...any) *Error
  • func OpBadUsage(op, usage string, param any, pos int, kind bool) *Error
  • func OpTooManyParams(op, usage string) *Error
  • func TypeMismatch(got, expected reflect.Type) *Error
  • func (e *Error) Append(buf *strings.Builder, prefix string, colorized bool)
  • func (e *Error) Error() string
  • func (e *Error) ErrorWithoutColors() string
  • func (e *Error) ExpectedString() string
  • func (e *Error) GotString() string
  • func (e *Error) SummaryString() string
• type ErrorSummary
  • func NewSummary(s string) ErrorSummary
  • func NewSummaryReason(got any, reason string) ErrorSummary
• type ErrorSummaryItem
  • func (s ErrorSummaryItem) AppendSummary(buf *strings.Builder, prefix string, colorized bool)
• type ErrorSummaryItems
  • func (s ErrorSummaryItems) AppendSummary(buf *strings.Builder, prefix string, colorized bool)
• type Path
  • func NewPath(root string) Path
  • func (p Path) AddArrayIndex(index int) Path
  • func (p Path) AddCustomLevel(custom string) Path
  • func (p Path) AddField(field string) Path
  • func (p Path) AddFunctionCall(fn string) Path
  • func (p Path) AddMapKey(key any) Path
  • func (p Path) AddPtr(num int) Path
  • func (p Path) Copy() Path
  • func (p Path) Equal(o Path) bool
  • func (p Path) Len() int
  • func (p Path) String() string

Variables

var BooleanError = &Error{}

BooleanError is the *Error returned when an error occurs in a boolean context.

var ErrTooManyErrors = &Error{
	Message: "Too many errors (use TESTDEEP_MAX_ERRORS=-1 to see all)",
}

ErrTooManyErrors is chained to the last error encountered when the maximum number of errors has been reached.

Types

type Context

type Context struct {
	Path        Path
	Visited     visited.Visited
	CurOperator location.GetLocationer
	Depth       int
	// 0 ≤ MaxErrors ≤ 1 stops when first error encoutered (without the
	// "Too many errors" error);
	// MaxErrors > 1 stops when MaxErrors'th error encoutered (with a
	// last "Too many errors" error);
	// < 0 do not stop until comparison ends.
	MaxErrors  int
	Errors     *[]*Error
	Anchors    *anchors.Info
	Hooks      *hooks.Info
	OriginalTB testing.TB // only used by Code operator
	// If true, the contents of the returned *Error will not be
	// checked. Can be used to avoid filling Error{} with expensive
	// computations.
	BooleanError bool
	// See ContextConfig.FailureIsFatal for details.
	FailureIsFatal bool
	// See ContextConfig.UseEqual for details.
	UseEqual bool
	// See ContextConfig.BeLax for details.
	BeLax bool
	// See ContextConfig.IgnoreUnexported for details.
	IgnoreUnexported bool
	// See ContextConfig.TestDeepInGotOK for details.
	TestDeepInGotOK bool
}

Context is used internally to keep track of the Cmp in-depth traversal.

func (Context) AddArrayIndex

func (c Context) AddArrayIndex(index int) (new Context)

AddArrayIndex creates a new Context from current one plus an array dereference for index-th item.

func (Context) AddCustomLevel

func (c Context) AddCustomLevel(pathAdd string) (new Context)

AddCustomLevel creates a new Context from current one plus pathAdd.

func (Context) AddField

func (c Context) AddField(field string) (new Context)

AddField creates a new Context from current one plus "." + field.

func (Context) AddFunctionCall

func (c Context) AddFunctionCall(fn string) (new Context)

AddFunctionCall creates a new Context from current one inside a function call.

func (Context) AddMapKey

func (c Context) AddMapKey(key any) (new Context)

AddMapKey creates a new Context from current one plus a map dereference for key key.

func (Context) AddPtr

func (c Context) AddPtr(num int) (new Context)

AddPtr creates a new Context from current one plus a pointer dereference.

func (Context) CannotCompareError

func (c Context) CannotCompareError() *Error

CannotCompareError returns a generic error used when the access of unexported fields cannot be overridden.

func (Context) CollectError

func (c Context) CollectError(err *Error) *Error

CollectError collects an error in the context. It returns an error if the collector is full, nil otherwise.

In boolean context, it ignores the passed error and returns the BooleanError.

func (*Context) InitErrors

func (c *Context) InitErrors()

InitErrors initializes Context *Errors slice, if MaxErrors < 0 or MaxErrors > 1.

func (Context) MergeErrors

func (c Context) MergeErrors() *Error

MergeErrors merges all collected errors in the first one and returns it. It returns nil if no errors have been collected.

func (Context) ResetErrors

func (c Context) ResetErrors() (new Context)

ResetErrors returns a new Context without any Error set.

func (Context) ResetPath

func (c Context) ResetPath(newRoot string) (new Context)

ResetPath creates a new Context from current one but reinitializing Path.

type Error

type Error struct {
	// Context when the error occurred
	Context Context
	// Message describes the error
	Message string
	// Got value
	Got any
	// Expected value
	Expected any
	// If not nil, Summary is used to display summary instead of using
	// Got + Expected fields
	Summary ErrorSummary
	// If initialized, location of TestDeep operator originator of the error
	Location location.Location
	// If defined, the current Error comes from this Error
	Origin *Error
	// If defined, points to the next Error
	Next *Error
}

Error represents errors generated by td (go-testdeep) functions.

func BadKind

func BadKind(got reflect.Value, okKinds string) *Error

BadKind returns a “bad kind” *Error, saying got kind does not match kind(s) listed in okKinds. It is the caller responsibility to check the kinds compatibility. got can be invalid, in this case it is displayed as nil.

func NilPointer

func NilPointer(got reflect.Value, expected string) *Error

NilPointer returns a “nil pointer” *Error, saying got value is a nil pointer instead of what expected lists. It is the caller responsibility to check got contains a nil pointer. got should not be invalid.

func OpBad

func OpBad(op, s string, args ...any) *Error

OpBad returns an *Error to notice the user a bad operator constructor usage. If len(args) is > 0, s and args are given to fmt.Sprintf.

func OpBadUsage

func OpBadUsage(op, usage string, param any, pos int, kind bool) *Error

OpBadUsage returns a string to notice the user he passed a bad parameter to an operator constructor.

func OpTooManyParams

func OpTooManyParams(op, usage string) *Error

OpTooManyParams returns an *Error to notice the user he called a variadic operator constructor with too many parameters.

func TypeMismatch

func TypeMismatch(got, expected reflect.Type) *Error

TypeMismatch returns a "type mismatch" error. It is the caller responsibility to check that both types differ.

If they resolve to the same name (via their String method), it tries to deeply dump the full package name of each type.

It works pretty well with the exception of identical anomymous structs in 2 different packages with the same last name: in this case reflect does not allow us to retrieve the package from which each type comes.

package foo // in a/
var Foo struct { a int }

package foo // in b/
var Foo struct { a int }

package ctxerr
import(
  a_foo "a/foo"
  b_foo "b/foo"
)
…
TypeMismatch(reflect.TypeOf(a_foo.Foo), reflect.TypeOf(b_foo.Foo))

returns an error producing:

type mismatch
     got: struct { a int }
expected: struct { a int }

func (*Error) Append

func (e *Error) Append(buf *strings.Builder, prefix string, colorized bool)

Append appends the a contents to buf using prefix prefix for each line.

func (*Error) Error

func (e *Error) Error() string

Error implements error interface.

func (*Error) ErrorWithoutColors

func (e *Error) ErrorWithoutColors() string

ErrorWithoutColors is the same as Error.Error but guarantees the resulting string does not contain any ANSI color escape sequences.

func (*Error) ExpectedString

func (e *Error) ExpectedString() string

ExpectedString returns the string corresponding to the Expected field. Returns the empty string if the e Summary field is not nil.

func (*Error) GotString

func (e *Error) GotString() string

GotString returns the string corresponding to the Got field. Returns the empty string if the e Summary field is not nil.

func (*Error) SummaryString

func (e *Error) SummaryString() string

SummaryString returns the string corresponding to the Summary field without any ANSI color escape sequences. Returns the empty string if the e Summary field is nil.

type ErrorSummary

type ErrorSummary interface {
	AppendSummary(buf *strings.Builder, prefix string, colorized bool)
}

ErrorSummary is the interface used to render error summaries. See Error.Summary.

func NewSummary

func NewSummary(s string) ErrorSummary

NewSummary returns an ErrorSummary composed by the simple string s.

func NewSummaryReason

func NewSummaryReason(got any, reason string) ErrorSummary

NewSummaryReason returns an ErrorSummary meaning that the value got failed for an (optional) reason.

With a given reason "it is not nil", the generated summary is:

        value: the_got_value
it failed coz: it is not nil

If reason is empty, the generated summary is:

  value: the_got_value
it failed but didn't say why

type ErrorSummaryItem

type ErrorSummaryItem struct {
	Label       string
	Value       string
	Explanation string
}

ErrorSummaryItem implements the ErrorSummary interface and allows to render a labeled value.

With explanation set:

Label: value
Explanation

With an empty explantion:

Label: value

func (ErrorSummaryItem) AppendSummary

func (s ErrorSummaryItem) AppendSummary(buf *strings.Builder, prefix string, colorized bool)

AppendSummary implements the ErrorSummary interface.

type ErrorSummaryItems

type ErrorSummaryItems []ErrorSummaryItem

ErrorSummaryItems implements the ErrorSummary interface and allows to render summaries with several labeled values. For example:

Missing 6 items: the 6 items...
  Extra 2 items: the 2 items...

func (ErrorSummaryItems) AppendSummary

func (s ErrorSummaryItems) AppendSummary(buf *strings.Builder, prefix string, colorized bool)

AppendSummary implements ErrorSummary interface.

type Path

type Path []pathLevel

Path defines a structure depth path, typically used to mark a position during a deep traversal in case of error.

func NewPath

func NewPath(root string) Path

NewPath returns a new Path initialized with root root node.

func (Path) AddArrayIndex

func (p Path) AddArrayIndex(index int) Path

AddArrayIndex adds a level corresponding to an array index.

func (Path) AddCustomLevel

func (p Path) AddCustomLevel(custom string) Path

AddCustomLevel adds a custom level.

func (Path) AddField

func (p Path) AddField(field string) Path

AddField adds a level corresponding to a struct field.

func (Path) AddFunctionCall

func (p Path) AddFunctionCall(fn string) Path

AddFunctionCall adds a level corresponding to a function call.

func (Path) AddMapKey

func (p Path) AddMapKey(key any) Path

AddMapKey adds a level corresponding to a map key.

func (Path) AddPtr

func (p Path) AddPtr(num int) Path

AddPtr adds num pointers levels.

func (Path) Copy

func (p Path) Copy() Path

Copy returns a new Path, exact but independent copy of p.

func (Path) Equal

func (p Path) Equal(o Path) bool

Equal returns true if p and o are equal, false otherwise.

func (Path) Len

func (p Path) Len() int

Len returns the number of levels, excluding pointers ones.

func (Path) String

func (p Path) String() string