tstkit

README

• The tstkit Package
  • The Buffer Type
    • WetBuffer
    • DryBuffer
  • Clocks

The tstkit Package

The tstkit package provides a set of reusable test helpers to streamline Go testing. Instead of rewriting common test utilities, this package offers a curated collection. Its goal is to balance simplicity and functionality, focusing on practical tools generic.

The Buffer Type

The Buffer type, defined in buffer.go, is a thread-safe wrapper around bytes.Buffer. It supports three kinds of behavior for test cleanup:

WetBuffer

A WetBuffer uses Buffer and ensures it's written to and its contents are examined during the test.

func TestAction(t *testing.T) {
    // --- Given ---
    buf := tstkit.WetBuffer(t, "wet-buffer")

    // --- When ---
    Action(buf) // Writes to buf.

    // --- Then ---
    // Fails if Action doesn't write to buf or if buf.String() is not called.
    assert.Equal(t, "expected output", buf.String())   
}

To skip the examination requirement:

buf := tstkit.WetBuffer(t, "wet-buffer").SkipExamine()
buf.WriteString("data") // No failure for unexamined content

DryBuffer

A DryBuffer ensures the buffer remains empty.

func TestAction(t *testing.T) {
    // --- Given ---
    buf := tstkit.DryBuffer(t, "dry-buffer")

    // --- When ---
    DoSomething(buf) // Must not write to buf.

    // --- Then ---
    // Fails if DoSomething writes to buf.
}

Clocks

The tstkit implements four functions with the same signature as time.Time which can be used to inject deterministic clocks.

• ClockStartingAt - returns current time with given offset.
• ClockFixed - always returns the same time.
• ClockDeterministic - returns time advanced by given duration no mather how fast you call it.
• TikTak - like ClockDeterministic with duration set to 1 second.

Documentation

Overview

Package tstkit provides utilities for testing.

Index

• Constants
• func ClockDeterministic(start time.Time, tick time.Duration) func() time.Time
• func ClockFixed(tim time.Time) func() time.Time
• func ClockStartingAt(tim time.Time) func() time.Time
• func TikTak(start time.Time) func() time.Time
• type Buffer
  • func DryBuffer(t tester.T, names ...string) *Buffer
  • func NewBuffer(names ...string) *Buffer
  • func WetBuffer(t tester.T, names ...string) *Buffer
  • func (buf *Buffer) Kind() string
  • func (buf *Buffer) MustWriteString(s string) int
  • func (buf *Buffer) Name() string
  • func (buf *Buffer) Reset()
  • func (buf *Buffer) SkipExamine() *Buffer
  • func (buf *Buffer) String() string
  • func (buf *Buffer) Write(p []byte) (n int, err error)
  • func (buf *Buffer) WriteString(s string) (n int, err error)

Constants

const (
	BufferDry   = "dry"     // BufferDry enforces no data is written.
	BufferWet   = "wet"     // BufferWet enforces data is written and examined.
	BuffDefault = "default" // BuffDefault applies no cleanup checks.
)

Buffer kinds define the behavior of a Buffer during test cleanup.

Functions

func ClockDeterministic

func ClockDeterministic(start time.Time, tick time.Duration) func() time.Time

ClockDeterministic returns the function with the same signature as time.Now and returning time advancing by the given tick with every call no matter how fast or slow you call it.

func ClockFixed

func ClockFixed(tim time.Time) func() time.Time

ClockFixed returns the function with the same signature as time.Now which always returns the given time.

func ClockStartingAt

func ClockStartingAt(tim time.Time) func() time.Time

ClockStartingAt returns the function with the same signature as time.Now and returning time as if the current time was set to the given value.

func TikTak

func TikTak(start time.Time) func() time.Time

TikTak returns a deterministic clock advancing one second for each call.

Types

type Buffer

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

Buffer is a thread-safe buffer that wraps bytes.Buffer. It tracks write and read operations and supports test cleanup checks based on its kind.

func DryBuffer

func DryBuffer(t tester.T, names ...string) *Buffer

DryBuffer creates a thread-safe Buffer with the dry kind BufferDry, which fails the test during cleanup if any data was written to it. An optional name can be provided for use in test log output. The provided tester.T is used to register cleanup checks and report failures.

Example:

buf := DryBuffer(t, "dry-buffer")
buf.WriteString("data") // Will fail test during cleanup.

func NewBuffer

func NewBuffer(names ...string) *Buffer

NewBuffer creates a new thread-safe Buffer with the BuffDefault kind. An optional name can be provided. If no name is provided, Buffer.Name returns an empty string.

Example:

buf := NewBuffer("my-buffer") // Named buffer.
buf := NewBuffer()            // Unnamed buffer.

func WetBuffer

func WetBuffer(t tester.T, names ...string) *Buffer

WetBuffer creates a thread-safe Buffer with the wet kind BufferWet, which fails the test during cleanup if no data was written or if the contents were not read via Buffer.String. An optional name can be provided for use in test log output. The provided tester.T is used to register cleanup checks and report failures.

Example:

buf := WetBuffer(t, "wet-buffer")
buf.WriteString("data")
// Must call buf.SkipExamine() or buf.String() to avoid test failure.

func (*Buffer) Kind

func (buf *Buffer) Kind() string

Kind returns the buffer's kind.

func (*Buffer) MustWriteString

func (buf *Buffer) MustWriteString(s string) int

MustWriteString writes the string s to the buffer, incrementing the write counter. It panics if the write operation fails. This is useful in tests where write failures are unexpected and should halt execution.

func (*Buffer) Name

func (buf *Buffer) Name() string

Name returns the buffer's name or an empty string if no name was provided during creation.

func (*Buffer) Reset

func (buf *Buffer) Reset()

Reset clears the buffer's contents and resets the write and read counters. It is thread-safe and prepares the buffer for reuse in tests.

func (*Buffer) SkipExamine

func (buf *Buffer) SkipExamine() *Buffer

SkipExamine disables the cleanup requirement for the test to examine the buffer. This is useful when the buffer is WetBuffer but we do not want to examine what was written to it. Implements fluent interface.

func (*Buffer) String

func (buf *Buffer) String() string

String returns the current contents of the buffer as a string, incrementing the read counter. It is thread-safe and implements the fmt.Stringer interface and is intended for inspecting buffer data during tests.

func (*Buffer) Write

func (buf *Buffer) Write(p []byte) (n int, err error)

Write writes the byte slice p to the buffer, incrementing the write counter. It is thread-safe and implements the io.Writer interface.

func (*Buffer) WriteString

func (buf *Buffer) WriteString(s string) (n int, err error)

WriteString writes the string s to the buffer, incrementing the write counter. It is thread-safe and implements the io.StringWriter interface.