// HaveFieldName returns a matcher that verifies MyType has a specific field value. func HaveFieldName(expected string) types.GomegaMatcher { return gcustom.MakeMatcher(func(actual any) (bool, error) { obj, err := toMyType(actual) if err != nil { return false, err } return obj.FieldName == expected, nil }).WithTemplate( "Expected {{.Actual}} to {{if .Negate}}not {{end}}have FieldName {{format .Data 0}}", ).WithTemplateData(expected) }


## Workflows

### 1. Plan the matcher

- Identify the **target type** (e.g., `*v1alpha1.NodeDevice`, `resource.Quantity`)
- Identify the **assertion** (field check, status check, condition check)
- Decide: single-parameter or multi-parameter matcher?
- Decide: does the assertion need a type-conversion helper?

### 2. Write the matcher function

Follow this checklist:

- [ ] Function returns `types.GomegaMatcher`
- [ ] Uses `gcustom.MakeMatcher` with `func(actual any) (bool, error)`
- [ ] Type-asserts `actual` via a `toXxx` helper (never inline the switch)
- [ ] Returns `false, err` on type mismatch
- [ ] Returns `false, nil` for logical mismatch (not an error)
- [ ] Adds `.WithTemplate(...)` for clear failure messages
- [ ] Adds `.WithTemplateData(...)` for parameterized messages
- [ ] Godoc starts with "// XxxMatcher returns a matcher that verifies..."

### 3. Write the type-assertion helper

Pattern for CRD types — accept both value and pointer:

```go
func toMyType(actual any) (*v1alpha1.MyType, error) {
    switch v := actual.(type) {
    case v1alpha1.MyType:
        return &v, nil
    case *v1alpha1.MyType:
        return v, nil
    default:
        return nil, errors.Errorf("expected v1alpha1.MyType or *v1alpha1.MyType, got %T", actual)
    }
}

For non-CRD types (e.g., resource.Quantity), handle the relevant input forms directly in the matcher.

4. Write tests

Follow the existing pattern from pkg/test/matcher/:

Use Ginkgo It for positive and negative cases
Test both Should and ShouldNot (via NotTo)
Test type error (pass wrong type, expect failure)
Test both value and pointer forms of the target type

var _ = Describe("HaveFieldName", func() {
    It("should match when field has expected value", func() {
        obj := &v1alpha1.MyType{FieldName: "expected"}
        Expect(obj).To(matcher.HaveFieldName("expected"))
    })

    It("should not match when field has different value", func() {
        obj := &v1alpha1.MyType{FieldName: "other"}
        Expect(obj).NotTo(matcher.HaveFieldName("expected"))
    })

    It("should match value type", func() {
        obj := v1alpha1.MyType{FieldName: "expected"}
        Expect(obj).To(matcher.HaveFieldName("expected"))
    })
})

Patterns

Simple boolean check

func BeHealthy() types.GomegaMatcher {
    return gcustom.MakeMatcher(func(actual any) (bool, error) {
        nx, err := toNodeDevice(actual)
        if err != nil { return false, err }
        return nx.Status.Health, nil
    })
}

Parameterized check

func HaveConditionStatus(conditionType string, status metav1.ConditionStatus) types.GomegaMatcher {
    return gcustom.MakeMatcher(func(actual any) (bool, error) {
        nx, err := toNodeDevice(actual)
        if err != nil { return false, err }
        cond := findCondition(nx.Status.Conditions, conditionType)
        if cond == nil { return false, nil }
        return cond.Status == status, nil
    }).WithTemplate(
        "Expected {{.Actual}} to {{if .Negate}}not {{end}}have condition {{format .Data 0}} with status {{format .Data 1}}",
    ).WithTemplateData([]any{conditionType, status})
}

Helper function for nested lookups

Keep helper functions unexported in the same package. They can be shared across matchers:

func findCondition(conditions []metav1.Condition, condType string) *metav1.Condition {
    for i := range conditions {
        if conditions[i].Type == condType {
            return &conditions[i]
        }
    }
    return nil
}

Key rules

Never return true, err — errors mean the match couldn't be evaluated, not that it succeeded
Return false, nil when the assertion logically fails (wrong value, condition not found)
Return false, err only for type errors or unexpected failures
Heavy parameters (structs > ~80 bytes like metav1.Condition) must be passed by pointer to avoid hugeParam lint errors
Reuse toXxx helpers across matchers for the same target type — they're unexported and package-scoped
Template format: use {{format .Data N}} for the Nth template data item; use {{if .Negate}}not {{end}} for negation support
Keep matchers in pkg/test/matcher/ package, co-located with existing matchers
Test file naming: <matcher_name>_test.go in the same package (matcher_test)

write-gomega-matcher

Write Gomega Custom Matcher

Quick start