test

func Error ¶

func Error(err error, msg ...string)

Error is used to indicate a test is invalid due to some error having occurred. This is intended to be used in test helpers and matchers to report an error that invalidates a test.

i.e. the error does not indicate that the test failed, but rather that the test is invalid and therefore unreliable, due to an error that occurred during execution or evaluation of a test helper or matcher.

It should not be confused with the github.com/blugnu/test.Error or github.com/blugnu/test.Errorf functions.

If a valid test frame is available, it will report the error using the [Errorf] method of that test frame.

If no valid test frame is available, this function will panic with the provided error and message(s). Panicking ensures that test execution fails, avoiding a false positive outcome.

Alternatives ¶

To indicate that a test is invalid without any specific error, use the Invalid function.

To draw attention to a non-fatal issue in a test, use the Warning function.

test.Example()

// test.Error is used to mark a test as invalid with a specific error.
// It will fail the current test with an error message that includes
// the error and any additional message(s).
ErrPreconditionsNotMet := errors.New("pre-conditions not met")
test.Error(ErrPreconditionsNotMet, "explanation of the error")

Output:
<== INVALID TEST
ERROR: pre-conditions not met
explanation of the error

func Example ¶

func Example()

Example is used to initialise a testframe for an Example function (that is, a runnable example on pkg.go.dev).

In each example, a call to `test.Example()` is used to establish the test frame since there is no *testing.T available for example functions. In real tests, this would be replaced with `With(t)` where `t` is the *testing.T for the test.

func Invalid ¶

func Invalid(msg ...string)

Invalid is used to mark a test as invalid. It should be called by a matcher when the test cannot be run due to an invalid condition, such as attempting to use a matcher with an unsupported type, or when the test is not properly set up.

Calling this function will fail the current test with an error message that includes the provided message(s). If no message is provided, it will simply mark the test as invalid without any additional information.

The Go standard library testing package does not provide a way to mark a test as invalid, so this function is used to provide a consistent way to do so.

An invalid test is identified by a "<== INVALID TEST" error following the test location, followed by any message provided.

test.Example()

// test.Invalid is used to mark a test as invalid.
// It will fail the current test with an error message that includes
// the provided message(s).  If no message is provided, it will fail
// the test as invalid without any additional information.

test.Invalid("This test is invalid because of some reason")

Output:
<== INVALID TEST
This test is invalid because of some reason

func NilFrame ¶

func NilFrame() testframe.Nil

NilFrame returns a sentinel implementation of test.TestingT. It is used to simulate a nil test frame in tests, allowing for testing of behavior when a test helper or matcher is used without a valid test frame.

The NilFrame captures the current test frame in order to ensure correct cleanup; if there is no valid test frame, the NilFrame function itself will panic with testframe.ErrNoTestFrame.

Notes On Usage ¶

The NilFrame() sentinel mechanism is primarily intended for internal use, to verify the behaviour of the test package itself. It provides a mechanism to differentiate between an invalid call to With(nil) versus a deliberate intention to introduce a (simulated) nil frame to verify the behaviour of the package under those conditions.

It should not be necessary to use this in your own tests.

There are some important considerations to keep in mind if you do choose to test with a nil test frame:

Pushing a test.NilFrame() onto the stack obscurs any current test frame which is required for any tests to be evaluated. This means that expectations must be established *before* pushing the nil frame and evaluation of those expectations deferred, to execute after the code under test has completed.

For example, the internal usage is primarily to ensure that panics are raised by the test package when a nil test frame is encountered:

func TestSomething(t *testing.T) {
   test.With(t)

   Run(Test("some subtest", func() {
      defer Expect(Panic(test.ErrNoTestFrame)).DidOccur()

      test.With(test.NilFrame())

      // this should panic, meeting the expectation established
      // and deferred (above)
      T()
   })
}

Pushing a NilFrame also interferes with t.Helper() frame tracking, so be aware that test warnings about incorrect test locations and missing t.Helper() calls may be misleading when using a nil frame in a test.

func Warning ¶ added in v0.10.0

func Warning(msg string)

Warning is used to report a warning in a test. This should be used to indicate a condition that is not an error, but may indicate a problem or unexpected behavior in the test.

Although a warning does not invalidate a test, it does fail any current test execution.

For example, if all test cases in a table-driven test are skipped, a warning is produced indicating that the test did not run any test cases. This does not represent an error or failure in any individual test case, but fails the test, avoiding a false positive result.

If a valid test frame is available, it will report the warning using the Errorf, otherwise it will panic with the warning message.

The warning message will be prefixed with "WARNING: " to indicate that it is a warning and not an error. This is useful for indicating that the test is not invalid, but there is something noteworthy that should be considered by the developer.