planner

Documentation

Overview

Package planner provides functionalities for deciding what expectation matches the given request.

Index

• func MatchHeader(ctx context.Context, expected request.Request, actual service.Method, ...) (err error)
• func MatchPayload(ctx context.Context, expected request.Request, actual service.Method, ...) (err error)
• func MatchRequest(ctx context.Context, expected request.Request, actual service.Method, ...) error
• func MatchService(ctx context.Context, expected request.Request, actual service.Method, ...) (err error)
• func UnexpectedRequestError(m service.Method, in interface{}) error
• type Error
  • func NewError(ctx context.Context, expected request.Request, req service.Method, ...) *Error
  • func (e Error) Error() string
• type Planner
  • func FirstMatch() Planner
  • func Sequence() Planner

Functions

func MatchHeader

func MatchHeader(ctx context.Context, expected request.Request, actual service.Method, in interface{}) (err error)

MatchHeader matches the header of a given request.

func MatchPayload

func MatchPayload(ctx context.Context, expected request.Request, actual service.Method, in interface{}) (err error)

MatchPayload matches the payload of a given request.

func MatchRequest

func MatchRequest(ctx context.Context, expected request.Request, actual service.Method, in interface{}) error

MatchRequest checks whether a request is matched.

func MatchService

func MatchService(ctx context.Context, expected request.Request, actual service.Method, in interface{}) (err error)

MatchService matches the service of a given request.

func UnexpectedRequestError

func UnexpectedRequestError(m service.Method, in interface{}) error

UnexpectedRequestError returns an error because of the unexpected request.

Types

type Error

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

Error represents an error that occurs while matching a request.

func NewError

func NewError(ctx context.Context, expected request.Request, req service.Method, in interface{}, messageFormat string, messageArgs ...interface{}) *Error

NewError creates a new Error.

func (Error) Error

func (e Error) Error() string

Error satisfies the error interface.

type Planner

type Planner interface {
	// IsEmpty checks whether the planner has no expectation.
	IsEmpty() bool
	// Expect adds a new expectation.
	Expect(expect request.Request)
	// Plan decides how a request matches an expectation.
	Plan(ctx context.Context, req service.Method, in interface{}) (request.Request, error)
	// Remain returns remain expectations.
	Remain() []request.Request
	// Reset removes all the expectations.
	Reset()
}

Planner or Request Execution Planner is in charge of selecting the right expectation for a given request.

func FirstMatch

func FirstMatch() Planner

FirstMatch creates a new Planner that finds the first expectation that matches the incoming request.

For example, there are 3 expectations in order:

Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 40})
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 41}).
	Return(`{"id": 41, "name": "Item #41 - 1"}`)
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 41}).
	Return(`{"id": 41, "name": "Item #41 - 2"}`)
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 42})

When the server receives a request with payload `{"id": 41}`, the `FirstMatch` planner looks up and finds the second expectation which is the first expectation that matches all the criteria. After that, there are only 3 expectations left:

Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 40})
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 41}).
	Return(`{"id": 41, "name": "Item #41 - 2"}`)
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 42})

When the server receives another request with payload `{"id": 40}`, the `FirstMatch` planner does the same thing and there are only 2 expectations left:

Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 41}).
	Return(`{"id": 41, "name": "Item #41 - 2"}`)
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 42})

When the server receives another request with payload `{"id": 100}`, the `FirstMatch` planner can not match it with any expectations and the server returns a `FailedPrecondition` result with error message `unexpected request received`.

Due to the nature of the matcher, pay extra attention when you use repeatability. For example, given these expectations:

Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 41}).
	UnlimitedTimes().
	Return(`{"id": 41, "name": "Item #41 - 1"}`)
Server.ExpectUnary("grpctest.Service/GetItem").WithPayload(&Item{Id: 41}).
	Return(`{"id": 41, "name": "Item #41 - 2"}`)

The 2nd expectation is never taken in account because with the same criteria, the planner always picks the first match, which is the first expectation.

func Sequence

func Sequence() Planner

Sequence creates a new Planner that matches the request sequentially.