gcustom

Documentation

Overview

package gcustom provides a simple mechanism for creating custom Gomega matchers

Index

• func ParseTemplate(templ string) (*template.Template, error)
• type CustomGomegaMatcher
  • func MakeMatcher(matchFunc any, args ...any) CustomGomegaMatcher
  • func (c CustomGomegaMatcher) FailureMessage(actual any) string
  • func (c CustomGomegaMatcher) Match(actual any) (bool, error)
  • func (c CustomGomegaMatcher) NegatedFailureMessage(actual any) string
  • func (c CustomGomegaMatcher) WithMessage(message string) CustomGomegaMatcher
  • func (c CustomGomegaMatcher) WithPrecompiledTemplate(templ *template.Template, data ...any) CustomGomegaMatcher
  • func (c CustomGomegaMatcher) WithTemplate(templ string, data ...any) CustomGomegaMatcher
  • func (c CustomGomegaMatcher) WithTemplateData(data any) CustomGomegaMatcher

Functions

func ParseTemplate

func ParseTemplate(templ string) (*template.Template, error)

ParseTemplate allows you to precompile templates for MakeMatcher's custom matchers.

Use ParseTemplate if you are concerned about performance and would like to avoid repeatedly parsing failure message templates. The data made available to the template is documented in the WithTemplate() method of CustomGomegaMatcher.

Once parsed you can pass the template in either as an argument to MakeMatcher(matchFunc, <template>) or using MakeMatcher(matchFunc).WithPrecompiledTemplate(template)

Types

type CustomGomegaMatcher

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

CustomGomegaMatcher is generated by MakeMatcher - you should always use MakeMatcher to construct custom matchers

func MakeMatcher

func MakeMatcher(matchFunc any, args ...any) CustomGomegaMatcher

MakeMatcher builds a Gomega-compatible matcher from a function (the matchFunc).

matchFunc must return (bool, error) and take a single argument. If you want to perform type-checking yourself pass in a matchFunc of type `func(actual any) (bool, error)`. If you want to only operate on a specific type, pass in `func(actual DesiredType) (bool, error)`; MakeMatcher will take care of checking types for you and notifying the user if they use the matcher with an invalid type.

MakeMatcher(matchFunc) builds a matcher with generic failure messages that look like:

Custom matcher failed for:
    <formatted actual>

for the positive failure case (i.e. when Expect(actual).To(match) fails) and

Custom matcher succeeded (but was expected to fail) for:
     <formatted actual>

for the negative case (i.e. when Expect(actual).NotTo(match) fails).

There are two ways to provide a different message. You can either provide a simple message string:

matcher := MakeMatcher(matchFunc, message)
matcher := MakeMatcher(matchFunc).WithMessage(message)

(where message is of type string) or a template:

matcher := MakeMatcher(matchFunc).WithTemplate(templateString)

where templateString is a string that is compiled by WithTemplate into a matcher. Alternatively you can provide a precompiled template like this:

template, err = gcustom.ParseTemplate(templateString) //use gcustom's ParseTemplate to get some additional functions mixed in
matcher := MakeMatcher(matchFunc, template)
matcher := MakeMatcher(matchFunc).WithPrecompiled(template)

When a simple message string is provided the positive failure message will look like:

Expected:
	<formatted actual>
to <message>

and the negative failure message will look like:

Expected:
	<formatted actual>
not to <message>

A template allows you to have greater control over the message. For more details see the docs for WithTemplate

func (CustomGomegaMatcher) FailureMessage

func (c CustomGomegaMatcher) FailureMessage(actual any) string

FailureMessage generates the positive failure message configured via WithMessage or WithTemplate/WithPrecompiledTemplate i.e. this is the failure message when Expect(actual).To(match) fails

func (CustomGomegaMatcher) Match

func (c CustomGomegaMatcher) Match(actual any) (bool, error)

Match runs the passed-in match func and satisfies the GomegaMatcher interface

func (CustomGomegaMatcher) NegatedFailureMessage

func (c CustomGomegaMatcher) NegatedFailureMessage(actual any) string

NegatedFailureMessage generates the negative failure message configured via WithMessage or WithTemplate/WithPrecompiledTemplate i.e. this is the failure message when Expect(actual).NotTo(match) fails

func (CustomGomegaMatcher) WithMessage

func (c CustomGomegaMatcher) WithMessage(message string) CustomGomegaMatcher

WithMessage returns a CustomGomegaMatcher configured with a message to display when failure occurs. Matchers configured this way produce a positive failure message that looks like:

Expected:
	<formatted actual>
to <message>

and a negative failure message that looks like:

Expected:
	<formatted actual>
not to <message>

func (CustomGomegaMatcher) WithPrecompiledTemplate

func (c CustomGomegaMatcher) WithPrecompiledTemplate(templ *template.Template, data ...any) CustomGomegaMatcher

WithPrecompiledTemplate returns a CustomGomegaMatcher configured to use the passed-in template. The template should be precompiled with gcustom.ParseTemplate().

As with WithTemplate() you can provide a single pice of additional data as an optional argument. This is accessed in the template via {{.Data}}

func (CustomGomegaMatcher) WithTemplate

func (c CustomGomegaMatcher) WithTemplate(templ string, data ...any) CustomGomegaMatcher

WithTemplate compiles the passed-in template and returns a CustomGomegaMatcher configured to use that template to generate failure messages.

Templates are provided the following variables and functions:

{{.Failure}} - a bool that, if true, indicates this should be a positive failure message, otherwise this should be a negated failure message {{.NegatedFailure}} - a bool that, if true, indicates this should be a negated failure message, otherwise this should be a positive failure message {{.To}} - is set to "to" if this is a positive failure message and "not to" if this is a negated failure message {{.Actual}} - the actual passed in to the matcher {{.FormattedActual}} - a string representing the formatted actual. This can be multiple lines and is always generated with an indentation of 1 {{format <object> <optional-indentation}} - a function that allows you to use Gomega's default formatting from within the template. The passed-in <object> is formatted and <optional-indentation> can be set to an integer to control indentation.

In addition, you can provide custom data to the template by calling WithTemplate(templateString, data) (where data can be anything). This is provided to the template as {{.Data}}.

Here's a simple example of all these pieces working together:

func HaveWidget(widget Widget) OmegaMatcher {
	return MakeMatcher(func(machine Machine) (bool, error) {
		return machine.HasWidget(widget), nil
	}).WithTemplate("Expected:\n{{.FormattedActual}}\n{{.To}} have widget named {{.Data.Name}}:\n{{format .Data 1}}", widget)
}

Expect(machine).To(HaveWidget(Widget{Name: "sprocket", Version: 2}))

Would generate a failure message that looks like:

Expected:
	<formatted machine>
to have widget named sprocket:
	<formatted sprocket>

func (CustomGomegaMatcher) WithTemplateData

func (c CustomGomegaMatcher) WithTemplateData(data any) CustomGomegaMatcher

WithTemplateData() returns a CustomGomegaMatcher configured to provide it's template with the passed-in data. The following are equivalent:

MakeMatcher(matchFunc).WithTemplate(templateString, data) MakeMatcher(matchFunc).WithTemplate(templateString).WithTemplateData(data)