Skip to content

Commit

Permalink
Merge pull request #262 from dolmen-go/add-godoc-links
Browse files Browse the repository at this point in the history
doc: add godoc links
  • Loading branch information
dnephin authored Jun 16, 2023
2 parents 684bd43 + fb6d0f6 commit a80f057
Show file tree
Hide file tree
Showing 5 changed files with 58 additions and 59 deletions.
66 changes: 33 additions & 33 deletions assert/assert.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ values in tests. When an assertion fails a helpful error message is printed.
# Example usage
All the assertions in this package use testing.T.Helper to mark themselves as
All the assertions in this package use [testing.T.Helper] to mark themselves as
test helpers. This allows the testing package to print the filename and line
number of the file function that failed.
Expand Down Expand Up @@ -67,19 +67,19 @@ message is omitted from these examples for brevity.
# Assert and Check
Assert and Check are very similar, they both accept a Comparison, and fail
[Assert] and [Check] are very similar, they both accept a [cmp.Comparison], and fail
the test when the comparison fails. The one difference is that Assert uses
testing.T.FailNow to fail the test, which will end the test execution immediately.
Check uses testing.T.Fail to fail the test, which allows it to return the
[testing.T.FailNow] to fail the test, which will end the test execution immediately.
Check uses [testing.T.Fail] to fail the test, which allows it to return the
result of the comparison, then proceed with the rest of the test case.
Like testing.T.FailNow, Assert must be called from the goroutine running the test,
not from other goroutines created during the test. Check is safe to use from any
Like [testing.T.FailNow], [Assert] must be called from the goroutine running the test,
not from other goroutines created during the test. [Check] is safe to use from any
goroutine.
# Comparisons
Package http://pkg.go.dev/gotest.tools/v3/assert/cmp provides
Package [gotest.tools/v3/assert/cmp] provides
many common comparisons. Additional comparisons can be written to compare
values in other ways. See the example Assert (CustomComparison).
Expand All @@ -98,11 +98,11 @@ import (
"gotest.tools/v3/internal/assert"
)

// BoolOrComparison can be a bool, cmp.Comparison, or error. See Assert for
// BoolOrComparison can be a bool, [cmp.Comparison], or error. See [Assert] for
// details about how this type is used.
type BoolOrComparison interface{}

// TestingT is the subset of testing.T used by the assert package.
// TestingT is the subset of [testing.T] (see also [testing.TB]) used by the assert package.
type TestingT interface {
FailNow()
Fail()
Expand Down Expand Up @@ -133,11 +133,11 @@ type helperT interface {
//
// Extra details can be added to the failure message using msgAndArgs. msgAndArgs
// may be either a single string, or a format string and args that will be
// passed to fmt.Sprintf.
// passed to [fmt.Sprintf].
//
// Assert uses t.FailNow to fail the test. Like t.FailNow, Assert must be called
// Assert uses [testing.TB.FailNow] to fail the test. Like t.FailNow, Assert must be called
// from the goroutine running the test function, not from other
// goroutines created during the test. Use Check from other goroutines.
// goroutines created during the test. Use [Check] from other goroutines.
func Assert(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
ht.Helper()
Expand All @@ -151,7 +151,7 @@ func Assert(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{})
// failed, a failure message is printed, and Check returns false. If the comparison
// is successful Check returns true. Check may be called from any goroutine.
//
// See Assert for details about the comparison arg and failure messages.
// See [Assert] for details about the comparison arg and failure messages.
func Check(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) bool {
if ht, ok := t.(helperT); ok {
ht.Helper()
Expand All @@ -166,9 +166,9 @@ func Check(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) b
// NilError fails the test immediately if err is not nil, and includes err.Error
// in the failure message.
//
// NilError uses t.FailNow to fail the test. Like t.FailNow, NilError must be
// NilError uses [testing.TB.FailNow] to fail the test. Like t.FailNow, NilError must be
// called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check from other goroutines.
// goroutines created during the test. Use [Check] from other goroutines.
func NilError(t TestingT, err error, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
ht.Helper()
Expand All @@ -193,9 +193,9 @@ func NilError(t TestingT, err error, msgAndArgs ...interface{}) {
// the unified diff will be augmented by replacing whitespace characters with
// visible characters to identify the whitespace difference.
//
// Equal uses t.FailNow to fail the test. Like t.FailNow, Equal must be
// Equal uses [testing.T.FailNow] to fail the test. Like t.FailNow, Equal must be
// called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check with cmp.Equal from other
// goroutines created during the test. Use [Check] with [cmp.Equal] from other
// goroutines.
func Equal(t TestingT, x, y interface{}, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
Expand All @@ -206,15 +206,15 @@ func Equal(t TestingT, x, y interface{}, msgAndArgs ...interface{}) {
}
}

// DeepEqual uses google/go-cmp (https://godoc.org/github.com/google/go-cmp/cmp)
// DeepEqual uses [github.com/google/go-cmp/cmp]
// to assert two values are equal and fails the test if they are not equal.
//
// Package http://pkg.go.dev/gotest.tools/v3/assert/opt provides some additional
// Package [gotest.tools/v3/assert/opt] provides some additional
// commonly used Options.
//
// DeepEqual uses t.FailNow to fail the test. Like t.FailNow, DeepEqual must be
// DeepEqual uses [testing.T.FailNow] to fail the test. Like t.FailNow, DeepEqual must be
// called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check with cmp.DeepEqual from other
// goroutines created during the test. Use [Check] with [cmp.DeepEqual] from other
// goroutines.
func DeepEqual(t TestingT, x, y interface{}, opts ...gocmp.Option) {
if ht, ok := t.(helperT); ok {
Expand All @@ -227,13 +227,13 @@ func DeepEqual(t TestingT, x, y interface{}, opts ...gocmp.Option) {

// Error fails the test if err is nil, or if err.Error is not equal to expected.
// Both err.Error and expected will be included in the failure message.
// Error performs an exact match of the error text. Use ErrorContains if only
// part of the error message is relevant. Use ErrorType or ErrorIs to compare
// Error performs an exact match of the error text. Use [ErrorContains] if only
// part of the error message is relevant. Use [ErrorType] or [ErrorIs] to compare
// errors by type.
//
// Error uses t.FailNow to fail the test. Like t.FailNow, Error must be
// Error uses [testing.T.FailNow] to fail the test. Like t.FailNow, Error must be
// called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check with cmp.Error from other
// goroutines created during the test. Use [Check] with [cmp.Error] from other
// goroutines.
func Error(t TestingT, err error, expected string, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
Expand All @@ -248,9 +248,9 @@ func Error(t TestingT, err error, expected string, msgAndArgs ...interface{}) {
// contain the expected substring. Both err.Error and the expected substring
// will be included in the failure message.
//
// ErrorContains uses t.FailNow to fail the test. Like t.FailNow, ErrorContains
// ErrorContains uses [testing.T.FailNow] to fail the test. Like t.FailNow, ErrorContains
// must be called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check with cmp.ErrorContains from other
// goroutines created during the test. Use [Check] with [cmp.ErrorContains] from other
// goroutines.
func ErrorContains(t TestingT, err error, substring string, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
Expand Down Expand Up @@ -280,12 +280,12 @@ func ErrorContains(t TestingT, err error, substring string, msgAndArgs ...interf
// reflect.Type
// The assertion fails if err does not implement the reflect.Type.
//
// ErrorType uses t.FailNow to fail the test. Like t.FailNow, ErrorType
// ErrorType uses [testing.T.FailNow] to fail the test. Like t.FailNow, ErrorType
// must be called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check with cmp.ErrorType from other
// goroutines created during the test. Use [Check] with [cmp.ErrorType] from other
// goroutines.
//
// Deprecated: Use ErrorIs
// Deprecated: Use [ErrorIs]
func ErrorType(t TestingT, err error, expected interface{}, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
ht.Helper()
Expand All @@ -296,12 +296,12 @@ func ErrorType(t TestingT, err error, expected interface{}, msgAndArgs ...interf
}

// ErrorIs fails the test if err is nil, or the error does not match expected
// when compared using errors.Is. See https://golang.org/pkg/errors/#Is for
// when compared using errors.Is. See [errors.Is] for
// accepted arguments.
//
// ErrorIs uses t.FailNow to fail the test. Like t.FailNow, ErrorIs
// ErrorIs uses [testing.T.FailNow] to fail the test. Like t.FailNow, ErrorIs
// must be called from the goroutine running the test function, not from other
// goroutines created during the test. Use Check with cmp.ErrorIs from other
// goroutines created during the test. Use [Check] with [cmp.ErrorIs] from other
// goroutines.
func ErrorIs(t TestingT, err error, expected error, msgAndArgs ...interface{}) {
if ht, ok := t.(helperT); ok {
Expand Down
2 changes: 1 addition & 1 deletion assert/cmd/gty-migrate-from-testify/doc.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/*
Command gty-migrate-from-testify migrates packages from
testify/assert and testify/require to gotest.tools/v3/assert.
testify/assert and testify/require to [gotest.tools/v3/assert].
$ go get gotest.tools/v3/assert/cmd/gty-migrate-from-testify
Expand Down
25 changes: 12 additions & 13 deletions assert/cmp/compare.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,16 @@ import (
"gotest.tools/v3/internal/format"
)

// Comparison is a function which compares values and returns ResultSuccess if
// Comparison is a function which compares values and returns [ResultSuccess] if
// the actual value matches the expected value. If the values do not match the
// Result will contain a message about why it failed.
// [Result] will contain a message about why it failed.
type Comparison func() Result

// DeepEqual compares two values using google/go-cmp
// (https://godoc.org/github.com/google/go-cmp/cmp)
// DeepEqual compares two values using [github.com/google/go-cmp/cmp]
// and succeeds if the values are equal.
//
// The comparison can be customized using comparison Options.
// Package http://pkg.go.dev/gotest.tools/v3/assert/opt provides some additional
// Package [gotest.tools/v3/assert/opt] provides some additional
// commonly used Options.
func DeepEqual(x, y interface{}, opts ...cmp.Option) Comparison {
return func() (result Result) {
Expand Down Expand Up @@ -61,7 +60,7 @@ func toResult(success bool, msg string) Result {
return ResultFailure(msg)
}

// RegexOrPattern may be either a *regexp.Regexp or a string that is a valid
// RegexOrPattern may be either a [*regexp.Regexp] or a string that is a valid
// regexp pattern.
type RegexOrPattern interface{}

Expand Down Expand Up @@ -95,7 +94,7 @@ func Regexp(re RegexOrPattern, v string) Comparison {
}
}

// Equal succeeds if x == y. See assert.Equal for full documentation.
// Equal succeeds if x == y. See [gotest.tools/v3/assert.Equal] for full documentation.
func Equal(x, y interface{}) Comparison {
return func() Result {
switch {
Expand Down Expand Up @@ -159,10 +158,10 @@ func Len(seq interface{}, expected int) Comparison {
// slice, or array.
//
// If collection is a string, item must also be a string, and is compared using
// strings.Contains().
// [strings.Contains].
// If collection is a Map, contains will succeed if item is a key in the map.
// If collection is a slice or array, item is compared to each item in the
// sequence using reflect.DeepEqual().
// sequence using [reflect.DeepEqual].
func Contains(collection interface{}, item interface{}) Comparison {
return func() Result {
colValue := reflect.ValueOf(collection)
Expand Down Expand Up @@ -259,7 +258,7 @@ func formatErrorMessage(err error) string {

// Nil succeeds if obj is a nil interface, pointer, or function.
//
// Use NilError() for comparing errors. Use Len(obj, 0) for comparing slices,
// Use [gotest.tools/v3/assert.NilError] for comparing errors. Use Len(obj, 0) for comparing slices,
// maps, and channels.
func Nil(obj interface{}) Comparison {
msgFunc := func(value reflect.Value) string {
Expand Down Expand Up @@ -306,9 +305,9 @@ func isNil(obj interface{}, msgFunc func(reflect.Value) string) Comparison {
//
// reflect.Type
//
// Fails if err does not implement the reflect.Type.
// Fails if err does not implement the [reflect.Type].
//
// Deprecated: Use ErrorIs
// Deprecated: Use [ErrorIs]
func ErrorType(err error, expected interface{}) Comparison {
return func() Result {
switch expectedType := expected.(type) {
Expand Down Expand Up @@ -383,7 +382,7 @@ var (
)

// ErrorIs succeeds if errors.Is(actual, expected) returns true. See
// https://golang.org/pkg/errors/#Is for accepted argument values.
// [errors.Is] for accepted argument values.
func ErrorIs(actual error, expected error) Comparison {
return func() Result {
if errors.Is(actual, expected) {
Expand Down
12 changes: 6 additions & 6 deletions assert/cmp/result.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ import (
"gotest.tools/v3/internal/source"
)

// A Result of a Comparison.
// A Result of a [Comparison].
type Result interface {
Success() bool
}

// StringResult is an implementation of Result that reports the error message
// StringResult is an implementation of [Result] that reports the error message
// string verbatim and does not provide any templating or formatting of the
// message.
type StringResult struct {
Expand All @@ -34,16 +34,16 @@ func (r StringResult) FailureMessage() string {
return r.message
}

// ResultSuccess is a constant which is returned by a ComparisonWithResult to
// ResultSuccess is a constant which is returned by a [Comparison] to
// indicate success.
var ResultSuccess = StringResult{success: true}

// ResultFailure returns a failed Result with a failure message.
// ResultFailure returns a failed [Result] with a failure message.
func ResultFailure(message string) StringResult {
return StringResult{message: message}
}

// ResultFromError returns ResultSuccess if err is nil. Otherwise ResultFailure
// ResultFromError returns [ResultSuccess] if err is nil. Otherwise [ResultFailure]
// is returned with the error message as the failure message.
func ResultFromError(err error) Result {
if err == nil {
Expand Down Expand Up @@ -74,7 +74,7 @@ func (r templatedResult) UpdatedExpected(stackIndex int) error {
return source.UpdateExpectedValue(stackIndex+1, r.data["x"], r.data["y"])
}

// ResultFailureTemplate returns a Result with a template string and data which
// ResultFailureTemplate returns a [Result] with a template string and data which
// can be used to format a failure message. The template may access data from .Data,
// the comparison args with the callArg function, and the formatNode function may
// be used to format the call args.
Expand Down
12 changes: 6 additions & 6 deletions assert/opt/opt.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import (
gocmp "github.com/google/go-cmp/cmp"
)

// DurationWithThreshold returns a gocmp.Comparer for comparing time.Duration. The
// DurationWithThreshold returns a [gocmp.Comparer] for comparing [time.Duration]. The
// Comparer returns true if the difference between the two Duration values is
// within the threshold and neither value is zero.
func DurationWithThreshold(threshold time.Duration) gocmp.Option {
Expand All @@ -28,7 +28,7 @@ func cmpDuration(threshold time.Duration) func(x, y time.Duration) bool {
}
}

// TimeWithThreshold returns a gocmp.Comparer for comparing time.Time. The
// TimeWithThreshold returns a [gocmp.Comparer] for comparing [time.Time]. The
// Comparer returns true if the difference between the two Time values is
// within the threshold and neither value is zero.
func TimeWithThreshold(threshold time.Duration) gocmp.Option {
Expand All @@ -45,12 +45,12 @@ func cmpTime(threshold time.Duration) func(x, y time.Time) bool {
}
}

// PathString is a gocmp.FilterPath filter that returns true when path.String()
// PathString is a [gocmp.FilterPath] filter that returns true when path.String()
// matches any of the specs.
//
// The path spec is a dot separated string where each segment is a field name.
// Slices, Arrays, and Maps are always matched against every element in the
// sequence. gocmp.Indirect, gocmp.Transform, and gocmp.TypeAssertion are always
// sequence. [gocmp.Indirect], [gocmp.Transform], and [gocmp.TypeAssertion] are always
// ignored.
//
// Note: this path filter is not type safe. Incorrect paths will be silently
Expand All @@ -66,7 +66,7 @@ func PathString(specs ...string) func(path gocmp.Path) bool {
}
}

// PathDebug is a gocmp.FilerPath filter that always returns false. It prints
// PathDebug is a [gocmp.FilterPath] filter that always returns false. It prints
// each path it receives. It can be used to debug path matching problems.
func PathDebug(path gocmp.Path) bool {
fmt.Printf("PATH string=%s gostring=%s\n", path, path.GoString())
Expand Down Expand Up @@ -95,7 +95,7 @@ func stepTypeFields(step gocmp.PathStep) string {
return ""
}

// PathField is a gocmp.FilerPath filter that matches a struct field by name.
// PathField is a [gocmp.FilterPath] filter that matches a struct field by name.
// PathField will match every instance of the field in a recursive or nested
// structure.
func PathField(structType interface{}, field string) func(gocmp.Path) bool {
Expand Down

0 comments on commit a80f057

Please sign in to comment.