mock

Documentation

Overview

Package mock provides small testing helpers modelled on Laravel's Mock facade — the bits applications reach for over and over in tests without pulling in a full mocking framework.

Three primitives:

• Clock — controllable time source. Inject as time.Now() and Advance it deterministically.
• Calls — generic call recorder. Counts and stores arguments each time a function is invoked.
• HTTPServer — pre-canned httptest.Server with route-by-method responses and recorded request inspection.

Index

• func BodyJSON(b []byte, dst any) error
• func MustReadBody(r io.Reader) []byte
• type Calls
  • func NewCalls[T any]() *Calls[T]
  • func (c *Calls[T]) All() []T
  • func (c *Calls[T]) AssertCalled(t testingT)
  • func (c *Calls[T]) AssertCount(t testingT, want int)
  • func (c *Calls[T]) AssertNotCalled(t testingT)
  • func (c *Calls[T]) At(i int) T
  • func (c *Calls[T]) Count() int
  • func (c *Calls[T]) Last() T
  • func (c *Calls[T]) Record(arg T)
  • func (c *Calls[T]) Reset()
• type Clock
  • func NewClock(start time.Time) *Clock
  • func (c *Clock) Advance(d time.Duration)
  • func (c *Clock) Now() time.Time
  • func (c *Clock) Set(t time.Time)
• type HTTPServer
  • func NewHTTPServer() *HTTPServer
  • func (h *HTTPServer) Close()
  • func (h *HTTPServer) LastRequest() RecordedRequest
  • func (h *HTTPServer) On(method, path string) *RouteBuilder
  • func (h *HTTPServer) OnJSON(method, path string, status int, body any) error
  • func (h *HTTPServer) Requests() []RecordedRequest
  • func (h *HTTPServer) Reset()
  • func (h *HTTPServer) URL() string
• type RecordedRequest
• type RouteBuilder
  • func (b *RouteBuilder) Header(k, v string) *RouteBuilder
  • func (b *RouteBuilder) Reply(status int, body []byte)
  • func (b *RouteBuilder) ReplyJSON(status int, body any) error

Functions

func BodyJSON

func BodyJSON(b []byte, dst any) error

BodyJSON unmarshals the request body into dst. Returns nil on empty body so tests can guard.

func MustReadBody

func MustReadBody(r io.Reader) []byte

MustReadBody drains r.Body and returns its bytes. Panics on read error — tests calling MustReadBody assume a well-formed reader.

Types

type Calls

type Calls[T any] struct {
	// contains filtered or unexported fields
}

Calls records each invocation of a tracked function. T is the argument tuple — typically a struct that captures the relevant fields:

type sendCall struct{ To, Subject string }
calls := mock.NewCalls[sendCall]()
mailer.SendFunc = func(to, subj string) {
    calls.Record(sendCall{to, subj})
}
// later:
calls.AssertCount(t, 2)
last := calls.Last()

func NewCalls

func NewCalls[T any]() *Calls[T]

NewCalls returns an empty recorder.

func (*Calls[T]) All

func (c *Calls[T]) All() []T

All returns a copy of the recorded list.

func (*Calls[T]) AssertCalled

func (c *Calls[T]) AssertCalled(t testingT)

AssertCalled fails t if no calls have been recorded.

func (*Calls[T]) AssertCount

func (c *Calls[T]) AssertCount(t testingT, want int)

AssertCount fails t if the recorded count differs from want.

func (*Calls[T]) AssertNotCalled

func (c *Calls[T]) AssertNotCalled(t testingT)

AssertNotCalled fails t if any calls have been recorded.

func (*Calls[T]) At

func (c *Calls[T]) At(i int) T

At returns the i-th recorded argument. Panics on out-of-range.

func (*Calls[T]) Count

func (c *Calls[T]) Count() int

Count returns how many times Record has been called.

func (*Calls[T]) Last

func (c *Calls[T]) Last() T

Last returns the most recent recorded argument (zero value if none).

func (*Calls[T]) Record

func (c *Calls[T]) Record(arg T)

Record appends arg to the call list.

func (*Calls[T]) Reset

func (c *Calls[T]) Reset()

Reset wipes the recorded list.

type Clock

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

Clock is a controllable time source for tests. Inject it as a `func() time.Time` so production callers still use time.Now without changes.

func NewClock

func NewClock(start time.Time) *Clock

NewClock returns a Clock fixed at start.

func (*Clock) Advance

func (c *Clock) Advance(d time.Duration)

Advance moves the clock forward by d. Negative durations rewind.

func (*Clock) Now

func (c *Clock) Now() time.Time

Now returns the current frozen instant.

func (*Clock) Set

func (c *Clock) Set(t time.Time)

Set jumps the clock to t.

type HTTPServer

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

HTTPServer is a thin wrapper around httptest.Server with route-by- (method, path) registration and request capture. Suitable for shaping responses from external APIs in tests.

func NewHTTPServer

func NewHTTPServer() *HTTPServer

NewHTTPServer starts a fresh httptest.Server. Always call Close().

func (*HTTPServer) Close

func (h *HTTPServer) Close()

Close releases the underlying server.

func (*HTTPServer) LastRequest

func (h *HTTPServer) LastRequest() RecordedRequest

LastRequest returns the most recent request (or zero if none).

func (*HTTPServer) On

func (h *HTTPServer) On(method, path string) *RouteBuilder

On registers a canned response for (method, path).

srv.On("GET", "/users/42").Reply(200, []byte(`{"id":42}`))

func (*HTTPServer) OnJSON

func (h *HTTPServer) OnJSON(method, path string, status int, body any) error

OnJSON registers a JSON response.

func (*HTTPServer) Requests

func (h *HTTPServer) Requests() []RecordedRequest

Requests returns a copy of every request the server has received.

func (*HTTPServer) Reset

func (h *HTTPServer) Reset()

Reset clears recorded requests but keeps registered routes.

func (*HTTPServer) URL

func (h *HTTPServer) URL() string

URL returns the base URL of the test server (e.g. http://127.0.0.1:PORT).

type RecordedRequest

type RecordedRequest struct {
	Method string
	Path   string
	Query  string
	Header http.Header
	Body   []byte
}

RecordedRequest captures the relevant bits of an incoming request.

type RouteBuilder

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

RouteBuilder accumulates a response on a registered route.

func (*RouteBuilder) Header

func (b *RouteBuilder) Header(k, v string) *RouteBuilder

Header adds a response header.

func (*RouteBuilder) Reply

func (b *RouteBuilder) Reply(status int, body []byte)

Reply finalises the route with the given status and body.

func (*RouteBuilder) ReplyJSON

func (b *RouteBuilder) ReplyJSON(status int, body any) error

ReplyJSON marshals body as JSON and registers the route.