testutil

func AllowInvalidGraphQL ¶

func AllowInvalidGraphQL(tb testing.TB)

AllowInvalidGraphQL exempts tb, and every subtest under it, from GraphQL document validation.

It exists for the test that deliberately sends a malformed document, which is the only honest reason to want it: a document the pinned schema refuses is a document GitLab refuses, so silencing the gate anywhere else silences a real defect. Say in a comment at the call site which malformed document the test is sending and why it has to.

Declare it on the test that calls NewTestClient, not on a subtest under one. The exemption is looked up under the name of the test the validation reports against, and that is the test the client belongs to: with a client built in the parent and driven from subtests, which is the common shape here, a subtest's exemption is never consulted and the refusal is reported against the parent while every subtest passes.

The exemption lasts for tb's lifetime and is released on cleanup.

func AssertCapturedDecodeFailures ¶

func AssertCapturedDecodeFailures(t *testing.T, cases []CapturedCase)

AssertCapturedDecodeFailures runs each case under a subtest of its own and fails the ones whose handler answered successfully, or with an error that does not name the captured response's decode failure.

Every package that reads a field client-go does not model asserts the same thing about every handler it converted (ADR-0021), so the table lives with the handlers and the assertion lives here.

func AssertEmbeddedResource ¶

func AssertEmbeddedResource(t *testing.T, ctx context.Context, session *mcp.ClientSession, name string, args map[string]any, wantURI string, toggle EmbedToggle)

AssertEmbeddedResource verifies that an MCP tool behaves correctly under both states of the embedded-resource toggle. It invokes the named tool via session twice:

1. With toggle(true) — expects an *mcp.EmbeddedResource block whose URI matches wantURI and whose MIME type is "application/json".
2. With toggle(false) — expects no EmbeddedResource blocks.

The toggle is always restored to its enabled (production default) state on test exit via testing.T.Cleanup. The test fails the surrounding run if either subtest fails.

func AssertQueryParam ¶

func AssertQueryParam(t *testing.T, r *http.Request, key, expected string)

AssertQueryParam fails the test if the URL query parameter key does not equal expected. Missing parameters are reported as a mismatch with an empty actual value.

func AssertRequestMethod ¶

func AssertRequestMethod(t *testing.T, r *http.Request, expected string)

AssertRequestMethod fails the test if r.Method does not equal expected. It calls testing.T.Helper so failure lines point at the caller.

func AssertRequestPath ¶

func AssertRequestPath(t *testing.T, r *http.Request, expected string)

AssertRequestPath fails the test if r.URL.Path does not equal expected. It calls testing.T.Helper so failure lines point at the caller.

func AssertUnreadableBodyRefused ¶ added in v3.1.0

func AssertUnreadableBodyRefused(t *testing.T, cases []CapturedCase)

AssertUnreadableBodyRefused runs each case under a subtest of its own and fails the ones whose handler answered successfully, or with an error that names neither decoder's failure.

It is AssertCapturedDecodeFailures for a field client-go has since caught up with. Both decoders read the same bytes and the SDK's runs first, so once client-go models the field the capture reads, no body can fail the capture alone and the stricter assertion is unsatisfiable. What survives is the behavior these tests were written for: a handler refuses a body it cannot read rather than publishing a half-filled result.

func CancelOnArrival ¶ added in v3.1.0

func CancelOnArrival(tb testing.TB, respond http.HandlerFunc) (context.Context, *gitlabclient.Client)

CancelOnArrival is the fixture for the one thing a handler's cancellation test cannot learn from a context cancelled up front: whether the request the handler builds carries the caller's context at all.

client-go takes that context only as a request option, gl.WithContext, and builds the request from context.Background() without it. A handler that forgets the option compiles, passes every other test and serves correct answers, while neither the action deadline nor an abandoned HTTP POST ever reaches the request it sends. A context that is already cancelled cannot tell the two apart in a handler that checks ctx.Err() before it builds anything, as the handlers this fixture was written for do: that handler returns before any request exists, whether or not it would have passed the context on.

The context returned here is cancelled the moment the first request reaches the mock, and the mock holds every request until the client abandons it or five seconds pass, answering through respond only in the second case. A handler whose first request carried the context therefore returns promptly with an error for which errors.Is(err, context.Canceled) holds; one whose first request did not waits out the hold and returns whatever respond answered, which a test asserting the cancellation reports.

A handler that sends more than one request is not proved by that alone: a later request that carries the context is refused by the transport once the context is cancelled, so a handler whose first call dropped it and whose second passed it would still end in context.Canceled. Every request that sits out the hold is therefore counted, and the test fails at cleanup when any did, naming how many.

The cancel is made through a sync.Once on the handler's own goroutine rather than by a watcher goroutine, since a CancelFunc may be called from anywhere and a goroutine that waited for the arrival would be one more thing a test that never sends a request could leak.

func CancelledCtx ¶

func CancelledCtx(t *testing.T) context.Context

CancelledCtx returns a context.Context that is already cancelled. Use it to test handler cancellation paths without dealing with real timers.

The returned context returns context.Canceled from context.Context.Err immediately. The associated cancel function is intentionally dropped — callers must not attempt to cancel it again.

func CaptureSlog ¶

func CaptureSlog(t *testing.T) *bytes.Buffer

CaptureSlog redirects slog output to an in-memory bytes.Buffer for the duration of the test. The original slog.Default logger is restored via testing.T.Cleanup.

CaptureSlog is NOT safe for testing.T.Parallel: it acquires [captureSlogMu] for the lifetime of the test and would deadlock with another parallel CaptureSlog caller.

func ConnectLegacyElicitationClient ¶

func ConnectLegacyElicitationClient(ctx context.Context, t *testing.T, server *mcp.Server, handler ElicitHandlerFunc, opts LegacyClientOptions) *mcp.ServerSession

ConnectLegacyElicitationClient connects a minimal legacy MCP client (protocol 2025-11-25, elicitation capability advertised) to server and returns the resulting server session. Server-initiated elicitation/create requests are answered by handler; ping requests are acknowledged; all other server-initiated requests fail with MethodNotFound. The session and the fake client are torn down via t.Cleanup.

After the handshake, handler runs on the fake client's serving goroutine, not the test goroutine: report failures inside handler with t.Errorf or by returning an error, never t.Fatal/t.FailNow (which only terminate the calling goroutine).

func FillFixture ¶ added in v3.1.0

func FillFixture(t reflect.Type, opts FixtureOptions) reflect.Value

FillFixture builds a value of type t the way a GitLab response would fill it, with values a scan can recognize: a string gets a sentinel of letters and digits made from its field name, a URL-shaped field an address under FixtureURLBase, a time-shaped string the RFC 3339 sentinel, a number 7, a flag true, a time.Time the sentinel instant, a slice two elements, a map one entry, a pointer an allocated value, and the shared pagination shapes the state asked for. An interface stays nil, nesting stops at depth 5, and the zero state returns the zero value.

func FixtureText ¶ added in v3.1.0

func FixtureText(path string) string

FixtureText is the sentinel a string field carries: an address for a URL-shaped field, the RFC 3339 sentinel for a time-shaped one, and for the rest the field's own name and a digit, letters and digits only, so the value holds no Markdown and can be found in the render.

func FixtureURLShaped ¶ added in v3.1.0

func FixtureURLShaped(name string) bool

FixtureURLShaped reports whether a field name says it holds an address, which is what decides that the field gets a fixture URL, and what keeps a hostile render from putting its payload where only an address can go.

func FollowKeyset ¶ added in v3.3.0

func FollowKeyset(r KeysetReporter, listing *KeysetListing, call func(pageToken string) (KeysetPage, error))

FollowKeyset reads a KeysetListing to its end through call, the way a caller follows a keyset list: once with no page_token, then once with the token the first call published. It reports through r unless the first page publishes the listing's next link and says more follow, the second request carries exactly the query of that link, the first request asks for keyset pagination, the second page publishes no token and says nothing follows, and each page carries the rows its body holds.

The second request is held to the whole of the link because GitLab writes every parameter it read into it: one sent beside the token that the link does not carry is a second form of a parameter it does, which Rack refuses.

call is the handler under test, invoked with the page_token to send and returning what its output reported.

func ForbiddenHandler ¶

func ForbiddenHandler(t *testing.T) http.Handler

ForbiddenHandler returns an http.Handler for mocks that must never be called. Each request is counted atomically and answered with a deterministic 500 so the client under test fails loudly, and a testing.T.Cleanup hook asserts on the test goroutine that no request arrived. This is the sanctioned replacement for `t.Fatal("should not be called")` inside handler literals, which the testing package forbids off the test goroutine (see .github/instructions/test-goroutines.instructions.md).

func FormFile ¶ added in v3.1.0

func FormFile(form *multipart.Form, name string) (multipart.File, *multipart.FileHeader, error)

FormFile returns the first file of a multipart form field, opened, with its header, the way Request.FormFile answers for a parsed form. A field that carries no file reports http.ErrMissingFile, as Request.FormFile does.

func FormValue ¶ added in v3.1.0

func FormValue(form *multipart.Form, name string) string

FormValue returns the first value of a multipart form field, or an empty string when the form carries none, which is what Request.FormValue answers for a parsed form. An absent field is an assertion for the test goroutine to make, not a panic on the server's.

func GFMCells ¶ added in v3.1.0

func GFMCells(line string) []string

GFMCells splits one table line into its cells the way GFM does: on every pipe not preceded by a backslash, the entity | left alone, with the one leading and one trailing pipe the house style writes removed.

func GitLabQueryComplexity ¶ added in v3.1.0

func GitLabQueryComplexity(document string, variables map[string]any) (int, error)

GitLabQueryComplexity estimates the complexity GitLab computes for document sent with variables, which is the figure it refuses a query on (GitLabAuthenticatedMaxComplexity).

No unit test reaches GitLab and the validating transport judges a document by the schema alone, which says nothing about cost, so a selection that grew past the limit used to pass every test and fail on every instance. This is GitLab's computation, legacy mode of graphql-ruby's QueryComplexity with Types::BaseField's field costs, run over the pinned schema: each field costs its own cost, one unless [gitLabFieldCosts] records otherwise, plus its children; a selection set costs, for each object type its selections can resolve to, the sum of the fields that apply to that type, whether selected on it or on an interface it implements, and the largest of those sums.

It is an estimate because the field costs live in GitLab's Ruby rather than in its schema, and the table holds only those a measurement has needed. A caller therefore holds the estimate equal to a figure GitLab reported for the same document, so that a change to the selection changes the estimate and sends whoever made it to measure again.

It refuses what it does not model rather than guessing: a document that GitLab would not accept, one defining other than one operation, a selection carrying a directive (skip and include change what is counted), a response key selected twice on one type, and a page size that is not a number.

func GraphQLHandler ¶

func GraphQLHandler(handlers map[string]http.HandlerFunc) http.Handler

GraphQLHandler returns an http.Handler that routes GraphQL POST requests by matching the request's query string against handler keys. The first key that appears as a substring of the query wins; keys are therefore evaluated longest-first so specific mutation names take precedence over shorter operation roots (e.g. "vulnerabilityDismiss" matches before "vulnerability"), and keys of one length in lexical order.

The request body is parsed into a [graphqlRequest], then reattached to r so downstream handlers can read it again. Non-POST requests are rejected with 405 Method Not Allowed, malformed JSON with 400 Bad Request, and queries that match no key with 400 Bad Request.

Keys should be GraphQL operation identifiers (field names, type names, or mutation names) that uniquely identify the operation, for example:

testutil.GraphQLHandler(map[string]http.HandlerFunc{
    "vulnerabilities":      handleListVulnerabilities,
    "vulnerabilityDismiss": handleDismissVulnerability,
})

func IsolateTempDir ¶

func IsolateTempDir(t *testing.T, dir string)

IsolateTempDir points os.TempDir at dir for the duration of the test.

Setting TMPDIR alone is a POSIX-only instruction. On Windows os.TempDir never reads it, so a test that sets only TMPDIR keeps the real temporary directory and its isolation silently does nothing.

That silence is expensive in exactly the tests this helper exists for. The upload, download and import allow-lists treat the OS temporary directory as an always-allowed root, so a fixture built with testing.T.TempDir and meant to sit outside every allowed root instead sat inside one. Every assertion that such a path is refused then passed a path that was correctly accepted, and the suite reported that containment worked while testing nothing. The allow-list itself was never wrong.

It cannot be used from a parallel test, because testing.T.Setenv cannot.

func NewOAuthTestClient ¶ added in v3.3.0

func NewOAuthTestClient(tb testing.TB, handler http.Handler) *gitlabclient.Client

NewOAuthTestClient is NewTestClient for an oauth HTTP mode session: the client is the one gitlabclient.NewOAuthClientWithToken builds for every credential that mode admits, so "test-token" travels as "Authorization: Bearer" and never as PRIVATE-TOKEN, and gitlabclient.Client.SendsBearer is true. It is for a handler whose answer depends on which of the two schemes its session sends. The validation and the recording are NewTestClient's; retries are the constructor's own and are not disabled, so a test should not answer it with a status the client retries.

func NewTestClient ¶

func NewTestClient(tb testing.TB, handler http.Handler) *gitlabclient.Client

NewTestClient creates a gitlabclient.Client pointed at a fresh httptest.Server backed by handler. The server is automatically torn down when the test finishes via testing.T.Cleanup, so callers never need to manage its lifecycle.

The client uses a static token ("test-token"), TLS verification disabled, and retries disabled — sufficient for most handler unit tests but not for exercising the transport retry policy. NewTestClient calls testing.T.Helper and testing.T.Fatalf if client construction fails.

Every GraphQL document sent through the returned client is validated against the pinned GitLab schema before handler sees it, so a mock can no longer answer what GitLab would refuse. The request proceeds either way and a refusal is reported with testing.TB.Errorf; AllowInvalidGraphQL is the opt-out for a test that sends a malformed document on purpose.

That validation is the reason to build a test's client here rather than wiring httptest.NewServer to gitlabclient.NewClient by hand. A handful of tests still do the latter, none of them sending GraphQL today, and any GraphQL written against one of those seams would be judged by nobody, which is the state this helper exists to end. The same goes for the recording below: a client built by hand is a request nothing observes.

Every request is also recorded, when InventoryDirEnv names a directory to record into, so the suite can answer what this server actually sends GitLab. Recording is off in an ordinary run.

The returned client is safe for concurrent use; the httptest.Server that backs it is goroutine-safe by construction.

func NewTestClientUnderRoot ¶ added in v3.3.0

func NewTestClientUnderRoot(tb testing.TB, root string, handler http.Handler) *gitlabclient.Client

NewTestClientUnderRoot is NewTestClient for an instance served under a relative URL root such as "/gitlab". The client's base URL carries the root, as GITLAB_URL does on such an instance, so a handler that derives the instance's web URL from the client sees the root; the root is taken off every request before the handler, the validation and the recording see it, so each reads the paths it reads for any other instance and the request inventory gains no row of its own for the root.

func ParseGraphQLVariables ¶

func ParseGraphQLVariables(r *http.Request) (map[string]any, error)

ParseGraphQLVariables reads r's body and returns the Variables map from the GraphQL request, or an error if the body cannot be read or is not valid JSON. The body is restored on r so subsequent handlers can re-read it. The returned map is nil when the request omits a variables field.

ParseGraphQLVariables is intended for assertions inside test handlers — production code should rely on the client-go GraphQL transport.

func ReadMultipartForm ¶ added in v3.1.0

func ReadMultipartForm(r *http.Request, maxMemory int64) (*multipart.Form, error)

ReadMultipartForm parses the multipart body of a request a test handler received and hands back the form, which carries the same Value and File maps that Request.MultipartForm would after Request.ParseMultipartForm.

It reads through Request.MultipartReader rather than ParseMultipartForm on purpose. The two parse the same body to the same form; the difference is that ParseMultipartForm is the call gosec's G120 names as where an unbounded upload exhausts a real handler's memory, and a taint rule cannot tell a fixture body from a client's, so every test handler that called it carried a directive saying so. Reading the form here needs none, and maxMemory still bounds what is held in memory before the rest spills to disk, exactly as it does for ParseMultipartForm.

What a caller loses is Request.FormValue and Request.FormFile, which read the form ParseMultipartForm stored on the request: FormValue and FormFile answer the same questions of the returned form.

func RespondGraphQL ¶

func RespondGraphQL(w http.ResponseWriter, status int, data string)

RespondGraphQL writes a GraphQL JSON envelope response with the given data payload. It wraps data in the standard {"data": ...} envelope expected by the GitLab GraphQL API client. For example:

testutil.RespondGraphQL(w, http.StatusOK, `{"project":{"name":"foo"}}`)

produces the body {"data":{"project":{"name":"foo"}}}. Callers remain responsible for escaping any quotes embedded in data.

func RespondGraphQLError ¶

func RespondGraphQLError(w http.ResponseWriter, status int, message string)

RespondGraphQLError writes a GraphQL error envelope with the given message. It sets data to null and emits a single error entry, mirroring the shape returned by GitLab when a query partially or fully fails. For example:

testutil.RespondGraphQLError(w, http.StatusOK, "not found")

produces {"data":null,"errors":[{"message":"not found"}]}. The message is interpolated directly into JSON — callers must escape any embedded quotes.

func RespondJSON ¶

func RespondJSON(w http.ResponseWriter, status int, body string)

RespondJSON writes a JSON response with the given HTTP status and raw body. It sets Content-Type to "application/json". body is written verbatim — callers are responsible for producing valid JSON. Write errors are intentionally ignored because the only writer in tests is an httptest.ResponseRecorder, which never fails.

func RespondJSONWithPagination ¶

func RespondJSONWithPagination(w http.ResponseWriter, status int, body string, p PaginationHeaders)

RespondJSONWithPagination writes a JSON response with GitLab pagination headers attached. Headers whose PaginationHeaders field is empty are omitted, matching GitLab's behavior on pages without a next/previous pointer.

func ZeroField ¶ added in v3.1.0

func ZeroField(v reflect.Value, path []int) bool

ZeroField returns v with the field at path set to its zero value, walking through pointers, or false when the path crosses a nil pointer the fixture left unallocated.