## Background The work item tests in `workitems_test.go` validate GraphQL queries against the full GitLab schema (`schema/gitlab.graphql`) using two helpers: - `loadSchema(t)` — opens `schema/gitlab.graphql`, parses it, and returns a `*graphql.Schema`. If the file is absent, the test is **skipped** (not failed), making validation opt-in and easy to miss. - `validateSchema(schema, query)` — calls `schema.ValidateWithVariables` on each incoming GraphQL request in the mock HTTP handler. This approach has two significant problems: 1. **Fragility**: The full schema is a snapshot of GitLab's live API. Any upstream change to the schema (field renames, type changes, additions of required arguments) can break tests even when the client code itself is correct and unchanged. 2. **Opt-in by default**: Because `loadSchema` skips rather than fails when the file is missing, most CI runs and local developer environments silently skip validation entirely. The schema must be manually regenerated with an external tool (`get-graphql-schema`), which is not part of the standard `make` workflow. ## Proposed Solution Replace schema validation with **exact query string matching** using golden files stored in `testdata/`. Each file contains the exact GraphQL query string that the client is expected to produce for a given operation. This makes query validation: - **Always active** — the files are committed to the repo, so validation never silently skips. - **Intentional** — changes to a golden file are a deliberate, reviewable diff alongside the query change that necessitated it. - **Simple** — no external schema tooling, no SDL authoring, no GraphQL library dependency for validation. - **Directly useful** — the client's job is to send the right query; golden files verify exactly that. The existing `TestBuildListWorkItemsQuery_*` tests already use `assert.Contains` to check that specific fields appear in the query string. This proposal extends that pattern to full golden-file comparison for every query and mutation the client produces. ## Implementation Plan ### 1. Create example query files in `testdata/` For each query or mutation the client produces, create a `.graphql` file containing the exact expected query string, e.g.: ``` testdata/query_get_work_item.graphql testdata/query_get_work_item_id.graphql testdata/query_list_work_items.graphql testdata/query_list_work_item_types.graphql testdata/mutation_create_work_item.graphql testdata/mutation_update_work_item.graphql testdata/mutation_delete_work_item.graphql ``` ### 2. Add a `assertQueryMatches` helper Add a test helper that reads the exact query file and compares it to the query received by the mock handler: ```go func assertQueryMatches(t *testing.T, got, goldenFile string) { t.Helper() data, err := os.ReadFile(goldenFile) require.NoError(t, err, "reading golden file %s", goldenFile) assert.Equal(t, strings.TrimSpace(string(data)), strings.TrimSpace(got)) } ``` ### 3. Update each test's mock handler to assert the query In each test's `/api/graphql` handler, replace the `validateSchema` call with a call to `assertQueryMatches`, keyed on the operation name (detectable via `strings.Contains(q.Query, "OperationName")`): ```go // Before if err := validateSchema(schema, q); err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } // After assertQueryMatches(t, q.Query, "testdata/query_get_work_item.graphql") ``` ### 4. Remove `loadSchema`, `validateSchema`, and the schema dependency - Delete `loadSchema` and `validateSchema` from `workitems_test.go`. - Remove the `github.com/graph-gophers/graphql-go` import from the test file (and from `go.mod`/`go.sum` if it is no longer used elsewhere). - Delete `schema/gitlab.graphql` and the `schema/` directory. - Update `.gitignore` if it references this path. ### 5. Update documentation / comments - Remove the `t.Skipf` message referencing `get-graphql-schema` from any comments. - Update any references in `workitems_test.go` or `CONTRIBUTING.md` that describe the old schema generation workflow. ## Acceptance Criteria - [ ] `schema/gitlab.graphql` and the `schema/` directory are deleted. - [ ] A golden `.graphql` file exists in `testdata/` for each query or mutation the client produces. - [ ] Each test's mock handler asserts the received query matches the corresponding golden file. - [ ] `loadSchema` and `validateSchema` are removed from `workitems_test.go`. - [ ] The `github.com/graph-gophers/graphql-go` dependency is removed if it is no longer used elsewhere. - [ ] All work item tests pass with `mise exec -- make test` without requiring any external tool or manually generated file. - [ ] Query validation is no longer opt-in — it runs in every environment including CI. - [ ] When a client query changes, the corresponding golden file is updated in the same MR as a deliberate, reviewable change.