be

README

Expect(👨🏼‍💻).To(Be(🚀))

expectto/be is a Golang package that offers a substantial collection of Be matchers. Every Be matcher is compatible with both Ginkgo/Gomega and Gomock. Where possible, arguments of matchers can be either finite values or matchers (Be/Gomega/Gomock).
Employing expectto/be matchers enables you to create straightforward, readable, and maintainable unit or integration tests in Golang. Tasks such as testing HTTP requests, validating JSON responses, and more become remarkably comprehensive and straightforward.

Table of Contents

• Installation

• Example

• Matchers

  • Be (core)
  • Be Reflected
  • Be Math
  • Be String
  • Be Time
  • Be JWT
  • Be URL
  • Be JSON
  • Be HTTP

• Contributing

• License

Installation

To use Be in your Golang project, simply import it:

import "github.com/expectto/be"

Example

Consider the following example demonstrating the usage of expectto/be's HTTP request matchers:

req, err := buildRequestForServiceFoo()
Expect(err).To(Succeed())

// Matching an HTTP request
Expect(req).To(be_http.Request(
    // Matching the URL
    be_http.HavingURL(be_url.URL(
        be_url.WithHttps(),
        be_url.HavingHost("example.com"),
        be_url.HavingPath("/path"),
        be_url.HavingSearchParam("status", "active"),
        be_url.HavingSearchParam("v", be_reflected.AsNumericString()),
        be_url.HavingSearchParam("q", "Hello World"),
    )),

    // Matching the HTTP method
    be_http.POST()

    // Matching request's context
    be_http.HavingCtx(be_ctx.Ctx(
        be_ctx.WithDeadline(be_time.LaterThan(time.Now().Add(30*time.Minute))),
        be_ctx.WithValue("foobar", 100),
    )),

    // Matching the request body using JSON matchers
    be_http.HavingBody(
        be_json.Matcher(
            be_json.JsonAsReader,
            be_json.HaveKeyValue("hello", "world"),
            be_json.HaveKeyValue("n", be_reflected.AsInteger()),
            be_json.HaveKeyValue("ids", be_reflected.AsSliceOf[string]),
            be_json.HaveKeyValue("details", And(
                be_reflected.AsObjects(),
                be.HaveLength(2),
                ContainElements(
                    be_json.HaveKeyValue("key", "foo"),
                    be_json.HaveKeyValue("key", "bar"),
                ),
            )),
        ),

        // Matching HTTP headers
        be_http.HavingHeader("X-Custom", "Hey-There"),
        be_http.HavingHeader("Authorization",
            be_string.MatchTemplate("Bearer {{jwt}}",
                be_string.Var("jwt",
                    be_jwt.Token(
                        be_jwt.Valid(),
                        be_jwt.HavingClaim("name", "John Doe"),
                    ),
                ),
            ),
        ),
    ),
))      

Matchers

Core Be

📦 be provides a set of core matchers for common testing scenarios.
See detailed docs

Core matchers:

Always, Never, All, Any, Eq, Not, HaveLength, Dive, DiveAny, DiveFirst

be_reflected

📦 be_reflected provides Be matchers that use reflection, enabling expressive assertions on values' reflect kinds and types.
See detailed docs

General Matchers based on reflect.Kind:

AsKind, AsFunc, AsChan, AsPointer, AsFinalPointer, AsStruct, AsPointerToStruct, AsSlice, AsPointerToSlice, AsSliceOf, AsMap, AsPointerToMap, AsObject, AsObjects, AsPointerToObject

Data Type Matchers based on reflect.Kind

AsString, AsBytes, AsNumeric, AsNumericString, AsInteger, AsIntegerString, AsFloat, AsFloatishString,

Interface Matchers based on reflect.Kind

AsReader,AsStringer

Matchers based on types compatibility:

AssignableTo, Implementing

be_math

📦 be_math provides Be matchers for mathematical operations.
See detailed docs

Matchers on math:

GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, Approx, InRange, Odd, Even, Negative, Positive, Zero, Integral, DivisibleBy

Shortcut aliases for math matchers:

Gt, Gte, Lt, Lte

be_string

📦 be_string provides Be matchers for string-related assertions.
See detailed docs

Matchers on strings

NonEmptyString, EmptyString, Alpha, Numeric, AlphaNumeric, AlphaNumericWithDots, Float, Titled, LowerCaseOnly, MatchWildcard, ValidEmail

Template matchers

MatchTemplate

be_time

📦 be_time provides Be matchers on time.Time.
See detailed docs

Time Matchers

LaterThan, LaterThanEqual, EarlierThan, EarlierThanEqual, Eq, Approx,
SameExactMilli, SameExactSecond, SameExactMinute, SameExactHour,
SameExactDay, SameExactWeekday, SameExactWeek, SameExactMonth,
SameSecond, SameMinute, SameHour, SameDay, SameYearDay,
SameWeek, SameMonth, SameYear, SameTimzone, SameOffset, IsDST

be_jwt

📦 be_jwt provides Be matchers for handling JSON Web Tokens (JWT). It includes matchers for transforming and validating JWT tokens. Matchers corresponds to specific golang jwt implementation.
See detailed docs

Transformers for JWT matching:

TransformSignedJwtFromString, TransformJwtFromString

Matchers on JWT:

Token, Valid, HavingClaims, HavingClaim, HavingMethodAlg, SignedVia

be_url

📦 be_url provides Be matchers on url.URL.
See detailed docs

Transformers for URL Matchers:

TransformUrlFromString, TransformSchemelessUrlFromString

URL Matchers:

URL, HavingHost, HavingHostname, HavingScheme, NotHavingScheme, WithHttps, WithHttp, HavingPort, NotHavingPort, HavingPath, HavingRawQuery, HavingSearchParam, HavingMultipleSearchParam, HavingUsername, HavingUserinfo, HavingPassword

be_ctx

📦 be_ctx provides Be matchers on context.Context.
See detailed docs

Context Matchers:

Ctx, CtxWithValue, CtxWithDeadline, CtxWithError

be_json

📦 be_json provides Be matchers for expressive assertions on JSON.
See detailed docs

JSON Matchers:

Matcher, HaveKeyValue

be_http

📦 be_http provides Be matchers for expressive assertions on http.Request.
See detailed docs

Matchers on HTTP:

Request, HavingMethod,
GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, CONNECT, TRACE,
HavingURL, HavingBody, HavingHost, HavingProto, HavingHeader, HavingHeaders

Contributing

Be welcomes contributions! Feel free to open issues, suggest improvements, or submit pull requests. Contribution guidelines for this project

License

This project is licensed under the MIT License.

Documentation

Index

• Variables
• func All(ms ...any) types.BeMatcher
• func Always() types.BeMatcher
• func Any(ms ...any) types.BeMatcher
• func Dive(matcher any) types.BeMatcher
• func DiveAny(matcher any) types.BeMatcher
• func DiveFirst(matcher any) types.BeMatcher
• func Eq(expected any) types.BeMatcher
• func HaveLength(args ...any) types.BeMatcher
• func Never(err error) types.BeMatcher
• func Not(expected any) types.BeMatcher

Variables

var Ctx = be_ctx.Ctx

Ctx is an alias for be_ctx.Ctx

var HttpRequest = be_http.Request

HttpRequest is an alias for be_http.Request matcher

var JwtToken = be_jwt.Token

JwtToken is an alias for be_jwt.Token matcher

var StringAsTemplate = be_string.MatchTemplate

StringAsTemplate is an alias for be_string.MatchTemplate matcher

var URL = be_url.URL

URL is an alias for be_url.URL matcher

Functions

func All

func All(ms ...any) types.BeMatcher

All is like gomega.And()

func Always

func Always() types.BeMatcher

Always does always match

func Any

func Any(ms ...any) types.BeMatcher

Any is like gomega.Or()

func Dive

func Dive(matcher any) types.BeMatcher

Dive applies the given matcher to each (every) element of the slice. Note: Dive is very close to gomega.HaveEach

func DiveAny

func DiveAny(matcher any) types.BeMatcher

DiveAny applies the given matcher to each element and succeeds in case if it succeeds at least at one item

func DiveFirst

func DiveFirst(matcher any) types.BeMatcher

DiveFirst applies the given matcher to the first element of the given slice

func Eq

func Eq(expected any) types.BeMatcher

Eq is like gomega.Equal()

func HaveLength

func HaveLength(args ...any) types.BeMatcher

HaveLength is like gomega.HaveLen() HaveLength succeeds if the actual value has a length that matches the provided conditions. It accepts either a count value or one or more Gomega matchers to specify the desired length conditions.

func Never

func Never(err error) types.BeMatcher

Never does never succeed (does always fail)

func Not

func Not(expected any) types.BeMatcher

Not is like gomega.Not()