gtest

Documentation

Index

• func IsSending[T any](tb TestingFatalHelper, ch <-chan T) T
• func NewLogger(t testing.TB) *slog.Logger
• func NotSending[T any](tb TestingFatalHelper, ch <-chan T)
• func NotSendingSoon[T any](tb TestingFatalHelper, ch <-chan T)
• func ReceiveOrTimeout[T any](tb TestingFatalHelper, ch <-chan T, timeout ScaledDuration) T
• func ReceiveSoon[T any](tb TestingFatalHelper, ch <-chan T) T
• func SendOrTimeout[T any](tb TestingFatalHelper, ch chan<- T, x T, timeout ScaledDuration)
• func SendSoon[T any](tb TestingFatalHelper, ch chan<- T, x T)
• func Sleep(dur ScaledDuration)
• type ScaledDuration
  • func ScaleMs(ms int64) ScaledDuration
• type TestingFatalHelper

Functions

func IsSending

func IsSending[T any](tb TestingFatalHelper, ch <-chan T) T

IsSending checks that a value is immediately ready to be ready from ch. If the value cannot be immediately received, tb.Fatal is called.

func NewLogger

func NewLogger(t testing.TB) *slog.Logger

NewLogger returns a *slog.Logger associated with the test t.

func NotSending

func NotSending[T any](tb TestingFatalHelper, ch <-chan T)

NotSending checks if a value is ready to be read from ch. If a value is available, tb.Fatal is called, and the received value is logged.

func NotSendingSoon

func NotSendingSoon[T any](tb TestingFatalHelper, ch <-chan T)

NotSendingSoon asserts that a read from ch is blocked for a reasonable, short duration.

If there are any other synchronization events available, NotSending should be preferred, because this will block the test for a short duration.

func ReceiveOrTimeout

func ReceiveOrTimeout[T any](tb TestingFatalHelper, ch <-chan T, timeout ScaledDuration) T

ReceiveOrTimeout attempts to receive a value from ch. If the value cannot be received within the given timeout, tb.Fatal is called. Use ScaleMs to produce the ScaledDuration value; this offers flexibility for slower machines without modifying tests.

Most tests should use ReceiveSoon; ReceiveOrTimeout should be reserved for exceptional cases.

func ReceiveSoon

func ReceiveSoon[T any](tb TestingFatalHelper, ch <-chan T) T

ReceiveSoon attempts to receive a value from ch. If the receive is blocked for a reasonable default timeout, tb.Fatal is called.

func SendOrTimeout

func SendOrTimeout[T any](tb TestingFatalHelper, ch chan<- T, x T, timeout ScaledDuration)

SendOrTimeout attempts to send x to ch. If the send is blocked for the entire timeout, tb.Fatal is called. Use ScaleMs to produce the ScaledDuration value; this offers flexibility for slower machines without modifying tests.

Most tests should use SendSoon; SendOrTimeout should be reserved for exceptional cases.

func SendSoon

func SendSoon[T any](tb TestingFatalHelper, ch chan<- T, x T)

SendSoon attempts to send x to ch. If the send is blocked for a reasonable default timeout, tb.Fatal is called.

func Sleep

func Sleep(dur ScaledDuration)

Sleep calls time.Sleep with the given scaled duration, to avoid a consumer of gtest needing to convert between a ScaledDuration and a time.Duration.

Types

type ScaledDuration

type ScaledDuration time.Duration

var TimeFactor ScaledDuration = 1

TimeFactor is a multiplier that can be controlled by the GORDIAN_TEST_TIME_FACTOR environment variable to increase test-related timeouts.

While a flat 100ms timer usually suffices on a workstation, that duration may not suffice on a contended CI machine. Rather than requiring tests to be changed to use a longer timeout, the operator can set e.g. GORDIAN_TEST_TIME_FACTOR=3 to triple how long the timeouts are.

The variable is exported in case programmatic control outside of environment variables is needed.

func ScaleMs

func ScaleMs(ms int64) ScaledDuration

ScaleMs returns ms in milliseconds, multiplied by TimeFactor so that test timeouts can be easily adjusted for machines running under load.

This type is used in SendOrTimeout and ReceiveOrTimeout to ensure callers do not use literal timeout values, which would cause flaky tests on slower machines.

type TestingFatalHelper

type TestingFatalHelper interface {
	Helper()

	Fatalf(format string, args ...any)
}

TestingFatalHelper is a subset of testing.TB to satisfy the requirements of ReceiveOrTimeout and SendOrTimeout, and to allow those helpers to themselves be easily tested.