Deprecate the MSW v1 `ctx` compat layer in GraphQL mocks, and fix the misleading `ctx` comment in generated cell mocks

[Tobbe]

Two related follow-ups deliberately left out of #2133 (MSW 2 upgrade), because both are docs/DX changes rather than dependency work. They share a root cause: the ctx object Cedar exposes in GraphQL mocks is an MSW v1 API that no longer exists upstream, and its name collides with several unrelated Cedar concepts.

Background

MSW v2 removed the (req, res, ctx) resolver signature. ctx was a bundle of response transformers — ctx.data() constructs a response body, it never reads request state. To avoid breaking every existing app, #2133 reimplements that shape as a Cedar compatibility layer on top of v2's HttpResponse (packages/testing/src/web/mockRequests.ts).

That was the right call for the upgrade, but it leaves Cedar carrying an API that no longer exists in the library it wraps, under a name that means four other things in this codebase. See the THE FIVE CONTEXTS section in docs/implementation-docs/2026-03-26-cedarjs-project-overview.md for the full disambiguation.

---

1. Deprecate the ctx compat layer in favour of returning HttpResponse

Why this is low-risk: across all fixtures, templates, and local-testing-project there are 23 cell mock files and zero use the function-plus-ctx form. There are also zero direct mockGraphQLQuery call sites outside of tests. The entire breaking surface is resolvers that call ctx.status/delay/errors, which in real code is currently nothing.

Suggested approach — additive, not a breaking change. Keep mockGraphQLQuery / mockGraphQLMutation as the registration mechanism; they own the handler queue and the reset-between-tests lifecycle, and they're what makes the auto-wrapped cell mocks work at all. Only the fake ctx goes away. Detecting whether a resolver returned an HttpResponse versus plain data is trivial, so both forms can coexist:

// still works — plain data, the 100% case today
mockGraphQLQuery('GetArticle', { article: { id: 1 } })

// new — return an HttpResponse for anything ctx used to do
mockGraphQLQuery('GetArticle', () =>
  HttpResponse.json({ errors: [{ message: 'Uh oh' }] }, { status: 404 }),
)

Then emit a deprecation warning when a resolver destructures/uses ctx, and remove it in a later major.

Explicitly not proposed: having users write graphql.query(...) and manage server.use() themselves. That would break the cell-mock auto-wrapping in cedarMockCellDataPlugin, which is genuinely load-bearing.

Docs to update (current docs only — docs/versioned_docs/** are frozen snapshots and should be left alone):

File	ctx. mentions
docs/docs/graphql/mocking-graphql-requests.md	8
docs/docs/testing.md	2
docs/docs/tutorial/chapter6/comment-form.md	2
docs/docs/how-to/mocking-graphql-in-storybook.md	1

Naming caution for the write-up: describe this as "MSW's response transformers are replaced by returning an HttpResponse", never as "deprecating ctx". mockCurrentUser() exists on both the web and api sides, and api-side services read a global context — so "we're deprecating ctx" reads to a Cedar developer as "Cedar's context is changing", which is false and alarming.

2. Fix the misleading ctx comment in generated cell mocks

cedar generate cell emits a commented-out signature advertising an MSW-v1-ism:

// packages/cli/src/commands/generate/cell/templates/mock.ts.template
// packages/cli/src/commands/generate/cell/templates/mockList.ts.template
export const standard = (/* vars, { ctx, req } */) => ({
  // ...
})

This is the one place Cedar itself puts ctx in front of users, in a file where they'd reasonably assume it means Cedar's api-side context. It should be fixed regardless of whether item 1 happens, and it's a good first issue on its own.

Open question: vars (the query variables) is still legitimate and useful, so the options are roughly:

• drop the comment entirely — export const standard = () => ({ ... })
• keep only the useful half — export const standard = (/* vars */) => ({ ... })
• update it to whatever signature item 1 settles on

Worth deciding item 1's direction first if both are done together, though item 2 can land independently.

Notes

• Neither is urgent — nothing is broken today. ctx works, and feat(deps)!: Upgrade to MSW 2 #2133 verified the compat layer against the full smoke-test suite.
• Item 2 is small and self-contained. Item 1 needs an API decision plus a docs pass.
• Unrelated to Web-side GraphQL mocks are never applied in ESM/Vitest apps (handlers queue, MSW never starts) #2134 (MSW handlers never applied in ESM/Vitest apps), which is a separate pre-existing gap.

[lisa-assistant]

Implementation Plan

Two items from the issue, ordered by separability.

---

Item 2 (do first — self-contained): Fix the ctx comment in generated cell mocks

Files:

• packages/cli/src/commands/generate/cell/templates/mock.ts.template
• packages/cli/src/commands/generate/cell/templates/mockList.ts.template

Current:

export const standard = (/* vars, { ctx, req } */) => ({

Change to (keep vars, drop the ctx, req hint since ctx is the compat object and req isn't the right name either — the current public API is { req, ctx } but the meaningful shape going forward is just vars):

export const standard = (/* vars */) => ({

This is safe to land independently of item 1. It removes the only place Cedar puts ctx in front of users as if it were Cedar's request context.

Also update the existing tests for cell generation that snapshot the mock template output (grep for standard = (/* vars in packages/cli/src/__tests__/) to reflect the new signature.

---

Item 1: Deprecate ctx and add HttpResponse support in mockGraphQL

File: packages/testing/src/web/mockRequests.ts

Step 1 — Detect HttpResponse returns

In the resolver function inside mockGraphQL, after calling data(variables, { req, ctx }), check if the return value is a Response/HttpResponse instance and pass it through:

d = await data(variables, { req, ctx })

// If the mock function returned an HttpResponse directly, pass it through
if (d instanceof Response) {
  if (responseEnhancer === 'networkError') {
    return HttpResponse.error()
  }
  if (typeof delayDurationMs !== 'undefined') {
    await delay(delayDurationMs)
  }
  return d
}

This allows the new HttpResponse form:

mockGraphQLQuery('GetArticle', () =>
  HttpResponse.json({ errors: [{ message: 'Uh oh' }] }, { status: 404 }),
)

Step 2 — Emit a deprecation warning when ctx is used

The ctx object's methods are already plain closures. Add a used flag that is set when any method is called:

let ctxWasUsed = false

const ctx: MockGraphQLContext = {
  status: (code, text) => {
    ctxWasUsed = true
    status = code
    statusText = text
  },
  // ... same for delay, errors, set, cookie, extensions, field, data, fetch
}

d = await data(variables, { req, ctx })

if (ctxWasUsed) {
  console.warn(
    '[CedarJS] The `ctx` object in GraphQL mocks is deprecated. ' +
    'Return an `HttpResponse` from `msw` instead. ' +
    'See: https://docs.cedarjs.com/docs/graphql/mocking-graphql-requests',
  )
}

Step 3 — Update docs

Per the issue, update the four doc files listed:

• docs/docs/graphql/mocking-graphql-requests.md (8 ctx. mentions)
• docs/docs/testing.md (2 mentions)
• docs/docs/tutorial/chapter6/comment-form.md (2 mentions)
• docs/docs/how-to/mocking-graphql-in-storybook.md (1 mention)

In each, replace (req, res, ctx) patterns with the direct-return HttpResponse form. Follow the issue's framing: "MSW's response transformers are replaced by returning an HttpResponse", not "we're deprecating ctx" (which reads as Cedar's context changing).

Step 4 — Export HttpResponse from @cedarjs/testing

HttpResponse is already imported in mockRequests.ts from msw. Re-export it from the package index so users don't need a separate import { HttpResponse } from 'msw':

// packages/testing/src/web/index.ts (or wherever the web exports live)
export { HttpResponse } from 'msw'

---

What NOT to do

• Don't change mockGraphQLQuery / mockGraphQLMutation's registration API — they own the handler queue and the reset-between-tests lifecycle.
• Don't remove ctx yet — only deprecate (warn). The ctx compat object continues to work exactly as before; the warning is additive.
• Don't update docs/versioned_docs/** — those are frozen snapshots.

---

Testing

• Add a test asserting HttpResponse is passed through directly (check response.status, response.headers, parsed body).
• Add a test asserting console.warn is called when ctx.status() (or any ctx method) is invoked.
• Add a test asserting NO warning fires when ctx is present in the signature but none of its methods are called (the function ignores ctx).

[lisa-assistant]

Confidence: 8/10

Item 2 (template fix) is a 1-line change plus snapshot updates — 10/10 on its own. Item 1 (HttpResponse support + deprecation warning) is also well-scoped: the ctx object is a local closure bundle, detecting instanceof Response is reliable in the browser/Node environments MSW targets, and the warning approach is additive with no breaking risk. Two-point deduction for the docs pass: I need to read four doc files and rewrite examples without accidentally misrepresenting Cedar's context object, and I haven't verified whether HttpResponse from msw is already re-exported from @cedarjs/testing/web (if it is, step 4 is a no-op).

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[Tobbe]

This isn't really stale. I just want to wait until after v6 is out