githubv4mock

Documentation

Overview

githubv4mock package provides a mock GraphQL server used for testing queries produced via shurcooL/githubv4 or shurcooL/graphql modules.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

• func NewMockedHTTPClient(ms ...Matcher) *http.Client
• func Ptr[T any](v T) *T
• type GQLResponse
  • func DataResponse(data map[string]any) GQLResponse
  • func ErrorResponse(errorMsg string) GQLResponse
• type Matcher
  • func NewMutationMatcher(mutation any, input any, variables map[string]any, response GQLResponse) Matcher
  • func NewQueryMatcher(query any, variables map[string]any, response GQLResponse) Matcher

Functions

func NewMockedHTTPClient

func NewMockedHTTPClient(ms ...Matcher) *http.Client

NewMockedHTTPClient creates a new HTTP client that registers a handler for /graphql POST requests. For each request, an attempt will be be made to match the request body against the provided matchers. If a match is found, the corresponding response will be returned with StatusOK.

Note that query and variable matching can be slightly fickle. The client expects an EXACT match on the query, which in most cases will have been constructed from a type with graphql tags. The query construction code in shurcooL/githubv4 uses the field types to derive the query string, thus a go string is not the same as a graphql.ID, even though `type ID string`. It is therefore expected that matching variables have the right type for example:

githubv4mock.NewQueryMatcher(
    struct {
        Repository struct {
            PullRequest struct {
                 ID githubv4.ID
            } `graphql:"pullRequest(number: $prNum)"`
        } `graphql:"repository(owner: $owner, name: $repo)"`
    }{},
    map[string]any{
        "owner": githubv4.String("owner"),
        "repo":  githubv4.String("repo"),
        "prNum": githubv4.Int(42),
    },
    githubv4mock.DataResponse(
        map[string]any{
            "repository": map[string]any{
                "pullRequest": map[string]any{
                     "id": "PR_kwDODKw3uc6WYN1T",
                 },
            },
        },
    ),
)

To aid in variable equality checks, values are considered equal if they approximate to the same type. This is required because when the http handler is called, the request body no longer has the type information. This manifests particularly when using the githubv4.Input types which have type deffed fields in their structs. For example:

type CloseIssueInput struct {
  IssueID ID `json:"issueId"`
  StateReason *IssueClosedStateReason `json:"stateReason,omitempty"`
}

This client does not currently provide a mechanism for out-of-band errors e.g. returning a 500, and errors are constrained to GQL errors returned in the response body with a 200 status code.

func Ptr

func Ptr[T any](v T) *T

Types

type GQLResponse

type GQLResponse struct {
	Data   map[string]any `json:"data"`
	Errors []struct {
		Message string `json:"message"`
	} `json:"errors,omitempty"`
}

func DataResponse

func DataResponse(data map[string]any) GQLResponse

DataResponse is the happy path response constructor for a mocked GraphQL request.

func ErrorResponse

func ErrorResponse(errorMsg string) GQLResponse

ErrorResponse is the unhappy path response constructor for a mocked GraphQL request.\ Note that for the moment it is only possible to return a single error message.

type Matcher

type Matcher struct {
	Request   string
	Variables map[string]any

	Response GQLResponse
}

func NewMutationMatcher

func NewMutationMatcher(mutation any, input any, variables map[string]any, response GQLResponse) Matcher

NewMutationMatcher constructs a new matcher for the provided mutation and variables. If the provided mutation is a string, it will be used-as-is, otherwise it will be converted to a string using the constructMutation function taken from shurcooL/graphql.

The input parameter is a special form of variable, matching the usage in shurcooL/githubv4. It will be added to the query as a variable called `input`. Furthermore, it will be converted to a map[string]any to be used for later equality comparison, as when the http handler is called, the request body will no longer contain the input struct type information.

func NewQueryMatcher

func NewQueryMatcher(query any, variables map[string]any, response GQLResponse) Matcher

NewQueryMatcher constructs a new matcher for the provided query and variables. If the provided query is a string, it will be used-as-is, otherwise it will be converted to a string using the constructQuery function taken from shurcooL/graphql.