erltest

Documentation

Overview

this package contains the TestReceiver which is a process that can have message expectations set on them. These expectations match messages sent to the process inbox and execute a [TestExpectation] function. The function returns true to pass and false to fail the test.

Index

• Variables
• type BoolTestCallExpectation
• type BoolTestExpectation
• type ExpectArg
• type Expectation
• type ExpectationFailure
  • func Fail(ea ExpectArg, reason string) *ExpectationFailure
  • func (ef *ExpectationFailure) String() string
• type ReceiverOpt
  • func Name(name string) ReceiverOpt
  • func NoFail() ReceiverOpt
  • func Parent(parent erl.PID) ReceiverOpt
  • func ReceiverTimeout(t time.Duration) ReceiverOpt
  • func SetLogger(logger *slog.Logger) ReceiverOpt
  • func WaitTimeout(t time.Duration) ReceiverOpt
• type TestDependency
• type TestReceiver
  • func NewReceiver(t *testing.T, opts ...ReceiverOpt) (erl.PID, *TestReceiver)
  • func (tr *TestReceiver) Expect(matchTerm any, e Expectation)
  • func (tr *TestReceiver) ExpectCall(matchTerm any, e Expectation)
  • func (tr *TestReceiver) ExpectCast(matchTerm any, e Expectation)
  • func (tr *TestReceiver) Failures() []*ExpectationFailure
  • func (tr *TestReceiver) Join(pid erl.PID, td TestDependency)
  • func (tr *TestReceiver) Pass() (int, bool)
  • func (tr *TestReceiver) Receive(self erl.PID, inbox <-chan any) error
  • func (tr *TestReceiver) Self() erl.PID
  • func (tr *TestReceiver) StartSupervised(startLink func(self erl.PID) (erl.PID, error)) erl.PID
  • func (tr *TestReceiver) Stop()
  • func (tr *TestReceiver) T() *testing.T
  • func (tr *TestReceiver) Wait()
  • func (tr *TestReceiver) WaitOn(e ...Expectation)

Variables

var (
	DefaultReceiverTimeout time.Duration = chronos.Dur("10s")
	DefaultWaitTimeout     time.Duration = chronos.Dur("5s")
)

Types

type BoolTestCallExpectation

type BoolTestCallExpectation func(self erl.PID, from genserver.From, msg any) bool

type BoolTestExpectation

type BoolTestExpectation func(self erl.PID, msg any) bool

type ExpectArg

type ExpectArg struct {
	// The term that was matched against. A simple type in the case of [reflect.Type], or
	// possibly a string, number, etc.
	Match any
	Msg   any
	// This is only populated for Calls
	From     *genserver.From
	Self     erl.PID
	MsgCount int
	Exp      Expectation
}

type Expectation

type Expectation interface {
	Check(arg ExpectArg) (Expectation, *ExpectationFailure)
	Satisfied(testDone bool) bool
	// unique identifier, to simplify nested Expectation registration with the [TestReceiver]
	ID() string
	Name() string
}

type ExpectationFailure

type ExpectationFailure struct {
	// The matching term that led to the ExpectationFailure
	Match any
	// The failed expectation
	Exp Expectation
	// The actual message that matched [Match] and was evaluated by the Expectation
	Msg any
	// Failure message
	Reason string
}

func Fail

func Fail(ea ExpectArg, reason string) *ExpectationFailure

func (*ExpectationFailure) String

func (ef *ExpectationFailure) String() string

type ReceiverOpt

type ReceiverOpt func(ro receiverOptions) receiverOptions

func Name

func Name(name string) ReceiverOpt

Set a name for the test receiver, that will be used in log messages

func NoFail

func NoFail() ReceiverOpt

Set this if you do not want the TestReceiver to call testing.T.Fail in the [Wait] method.

func Parent

func Parent(parent erl.PID) ReceiverOpt

Set a parent for this test process. Defaults to [erl.rootPID]

func ReceiverTimeout

func ReceiverTimeout(t time.Duration) ReceiverOpt

Specify how long the test reciever should run for before stopping. this needs to be set otherwise tests will hang until exceptions are matched or the 10min Go default is reached. See DefaultReceiverTimeout

func SetLogger

func SetLogger(logger *slog.Logger) ReceiverOpt

XXX: might remove.

func WaitTimeout

func WaitTimeout(t time.Duration) ReceiverOpt

Specify how long for [TestReciever.Wait] for all expectations to be met see DefaultWaitTimeout. Will set the receiver timeout to double the wait timeout so there's no need to call ReceiverTimeout in most cases.

type TestDependency

type TestDependency interface {
	Pass() (int, bool)
}

used to inject more complex mocks based on a TestReceiver and have them checked when [Wait] is called

type TestReceiver

type TestReceiver struct {
	// contains filtered or unexported fields
}

func NewReceiver

func NewReceiver(t *testing.T, opts ...ReceiverOpt) (erl.PID, *TestReceiver)

Creates a new TestReceiver, which is a process that you can set message matching expectations on.

func (*TestReceiver) Expect

func (tr *TestReceiver) Expect(matchTerm any, e Expectation)

Set an expectation that will be matched whenever a [matchTerm] msg type is received.

func (*TestReceiver) ExpectCall

func (tr *TestReceiver) ExpectCall(matchTerm any, e Expectation)

This is like [Expect] but is only tested against genserver.CallRequest messages. NOTE: You should use genserver.Reply to send a response to the genserver.From, otherwise the caller will timeout

func (*TestReceiver) ExpectCast

func (tr *TestReceiver) ExpectCast(matchTerm any, e Expectation)

This is like [Expect] but is only tested against genserver.CastRequest messages.

func (*TestReceiver) Failures

func (tr *TestReceiver) Failures() []*ExpectationFailure

func (*TestReceiver) Join

func (tr *TestReceiver) Join(pid erl.PID, td TestDependency)

func (*TestReceiver) Pass

func (tr *TestReceiver) Pass() (int, bool)

returns the number of failed expectations and whether all expectations have been satisifed. An expectation is not satisfied unless it is invoked in the correct time and order

func (*TestReceiver) Receive

func (tr *TestReceiver) Receive(self erl.PID, inbox <-chan any) error

func (*TestReceiver) Self

func (tr *TestReceiver) Self() erl.PID

func (*TestReceiver) StartSupervised

func (tr *TestReceiver) StartSupervised(startLink func(self erl.PID) (erl.PID, error)) erl.PID

starts the process via [startLink] with the TestReceiver as the parent. If [startLink] returns an error the test is failed. The process will be synchronously killed when calling [Stop]

func (*TestReceiver) Stop

func (tr *TestReceiver) Stop()

will cause the test receiver to exit, sending signals to linked and monitoring processes. This is not needed for normal test cleanup (that is handled via [t.Cleanup()])

func (*TestReceiver) T

func (tr *TestReceiver) T() *testing.T

return the *testing.T. Don't use this in situations that could run after a test is failed, the race detector doesn't like that.

func (*TestReceiver) Wait

func (tr *TestReceiver) Wait()

Returns when the WaitTimeout expires or an expectation fails. If at the end of the timeout not all expectations are satisifed, the test is failed. Call this after you have sent your messages and want fail if your expecations don't pass

func (*TestReceiver) WaitOn

func (tr *TestReceiver) WaitOn(e ...Expectation)

Register an expectation with this TestReciever. It will be checked when Pass is called (and as a consequnce, cause [Wait] to block until its success)