metamorphic

README

metamorphic

Documentation

Overview

Package metamorphic provides facilities for running metamorphic, property-based testing. By running logically equivalent operations with different conditions, metamorphic tests can identify bugs without requiring an oracle.

Index

• func Generate[I any](n int, fn func() I) []I
• func Run[S any](t testing.TB, initial S, ops []Op[S])
• func Step[S any](l *Logger, s S, op Op[S])
• type ItemWeight
• type Logger
  • func NewLogger(t testing.TB) *Logger
  • func RunInTandem[S any](t testing.TB, initial []S, ops []Op[S]) []*Logger
  • func (l *Logger) Commentf(format string, args ...any)
  • func (l *Logger) Error(err error)
  • func (l *Logger) Errorf(format string, args ...any)
  • func (l *Logger) FailNow()
  • func (l *Logger) Fatal(args ...any)
  • func (l *Logger) History() string
  • func (l *Logger) Log(args ...any)
  • func (l *Logger) Logf(format string, args ...interface{})
  • func (l *Logger) Write(b []byte) (int, error)
• type Op
• type Weighted
  • func (w Weighted[I]) Random(rng *rand.Rand) func() I
  • func (w Weighted[I]) RandomDeck(rng *rand.Rand) func() I

Functions

func Generate

func Generate[I any](n int, fn func() I) []I

Generate generates a sequence of n items, calling fn to produce each item. It's intended to be used with a function returned by (Weighted).Random or (Weighted).RandomDeck.

func Run

func Run[S any](t testing.TB, initial S, ops []Op[S])

Run runs the provided operations, using the provided initial state.

func Step

func Step[S any](l *Logger, s S, op Op[S])

Step runs the provided operation against the provided state.

Types

type ItemWeight

type ItemWeight[I any] struct {
	Item   I
	Weight int
}

ItemWeight holds an item and its corresponding weight.

type Logger

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

Logger logs test operation's outputs and errors, maintaining a cumulative history of the test. Logger may be used analogously to the standard library's testing.TB.

func NewLogger

func NewLogger(t testing.TB) *Logger

NewLogger constructs a new logger for running randomized tests.

func RunInTandem

func RunInTandem[S any](t testing.TB, initial []S, ops []Op[S]) []*Logger

RunInTandem takes n initial states and runs the provided set of operations against each incrementally. It fails the test as soon as any of the logs diverge.

func (*Logger) Commentf

func (l *Logger) Commentf(format string, args ...any)

Commentf writes a comment to the log file. Commentf always appends a newline after the comment. Commentf may prepend a newline before the message if there isn't already one.

func (*Logger) Error

func (l *Logger) Error(err error)

Error fails the test run, logging the provided error.

func (*Logger) Errorf

func (l *Logger) Errorf(format string, args ...any)

Errorf fails the test run, logging the provided message.

func (*Logger) FailNow

func (l *Logger) FailNow()

FailNow marks the function as having failed and stops its execution by calling runtime.Goexit. FailNow is implemented by calling through to the underlying *testing.T's FailNow.

func (*Logger) Fatal

func (l *Logger) Fatal(args ...any)

Fatal is equivalent to Log followed by FailNow.

func (*Logger) History

func (l *Logger) History() string

History returns the history accumulated by the Logger.

func (*Logger) Log

func (l *Logger) Log(args ...any)

Log formats its arguments using default formatting, analogous to Print, and records the text in the test's recorded history.

func (*Logger) Logf

func (l *Logger) Logf(format string, args ...interface{})

Logf formats its arguments according to the format, analogous to Printf, and records the text in the test's recorded history.

func (*Logger) Write

func (l *Logger) Write(b []byte) (int, error)

Write implements io.Writer.

type Op

type Op[S any] interface {
	fmt.Stringer

	// Run runs the operation, logging its outcome to Logger.
	Run(*Logger, S)
}

Op represents a single operation within a metamorphic test.

type Weighted

type Weighted[I any] []ItemWeight[I]

Weighted is a slice of items and their weights.

func (Weighted[I]) Random

func (w Weighted[I]) Random(rng *rand.Rand) func() I

Random returns a function that returns one item at random, using the distribution indicated by item weights and the provided pseudorandom number generator for randomness.

func (Weighted[I]) RandomDeck

func (w Weighted[I]) RandomDeck(rng *rand.Rand) func() I

RandomDeck returns a function that returns one item at random, using a deck-style distribution to ensure each item is returned with the desired frequency. Randomness is taken from the provided pseudorandom number generator.