custom-matchers

Writing your own matchers

When no built-in matcher fits and composition (And/Or/WithTransform/SatisfyAll — see gomega:composing-matchers) can't express it cleanly, write a custom matcher. Reach for gcustom.MakeMatcher first — it's the modern, low-boilerplate path. Drop to a hand-written type only when you need full control. Docs: https://onsi.github.io/gomega/#adding-your-own-matchers.

gcustom.MakeMatcher — the recommended path

gcustom.MakeMatcher(matchFunc, ...) builds a full types.GomegaMatcher from one function. The match function must be func(actual T) (bool, error):

import (
	"github.com/onsi/gomega/gcustom"
	"github.com/onsi/gomega/types"

	"encoding/json"
	"fmt"
	"net/http"
	"reflect"
)

func RepresentJSONifiedObject(expected any) types.GomegaMatcher {
	return gcustom.MakeMatcher(func(response *http.Response) (bool, error) {
		ptr := reflect.New(reflect.TypeOf(expected)).Interface()
		if err := json.NewDecoder(response.Body).Decode(ptr); err != nil {
			return false, fmt.Errorf("failed to decode JSON: %w", err)
		}
		decoded := reflect.ValueOf(ptr).Elem().Interface()
		return reflect.DeepEqual(decoded, expected), nil
	}).WithTemplate("Expected:\n{{.FormattedActual}}\n{{.To}} contain the JSON representation of\n{{format .Data 1}}").WithTemplateData(expected)
}

Then Expect(resp).To(RepresentJSONifiedObject(book)) just works.

Typed match funcs get free type-checking. Because the func takes *http.Response, gcustom rejects any other actual with a clear error before calling your code. Use func(actual any) (bool, error) only if you want to handle multiple types or do your own type checks.

Return (false, err) for bad input, not a panic. A non-nil error fails the assertion in both the To and NotTo directions — you can't accidentally pass a negated assertion by feeding garbage.

Messages: WithMessage vs WithTemplate

• .WithMessage("contain the JSON representation") — simplest. Renders Expected:\n<actual>\nto contain the JSON representation (and not to when negated).
• .WithTemplate(tmpl, optionalData) — full control. WithTemplate(tmpl, data) is shorthand for .WithTemplate(tmpl).WithTemplateData(data).
• Omit both and you get a generic Custom matcher failed for:\n<actual> message.