MSW is a tool that intercepts http requests, but since convex uses websockets I'm not sure which mocking methods to use.
#will a tool like mock service worker work with useQuery mocking? What mocking tools will work?
distant wagon
vague folioBOT
Hi @distant wagon. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
You are correct: Mock Service Worker (MSW) is designed to intercept HTTP requests, but Convex’s useQuery (and other client hooks) communicate with the backend over WebSockets, not HTTP. This means that MSW will not be able to intercept or mock the data flow for useQuery or useMutation, since those do not use fetch or XHR under the hood, but instead use a persistent WebSocket connection for real-time updates Convex React: Under the hood.
For mocking Convex hooks like useQuery in your tests, the recommended approaches are:
-
Mocking the Convex React hooks directly: You can use your test runner’s mocking capabilities (e.g., Vitest’s vi.mock) to replace useQuery and useMutation with your own implementations that return the desired test data. This is a common and effective approach for unit testing React components that use Convex Testing React Components with Convex: Mocking the convex import.
-
Dependency injection with a fake Convex client: You can use a fake implementation of the Convex client (such as ConvexReactClientFake) and inject it into your components via the ConvexProvider. This allows you to control the data returned by queries and mutations in your tests Testing React Components with Convex: Dependency injection.
In summary: MSW will not work for mocking useQuery because it only intercepts HTTP, not WebSocket traffic. Instead, mock the Convex hooks or use a fake client for your tests. These are the approaches recommended in the Convex community and documentation.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
distant wagon
@vague folio what would a useFakeQuery function look like?
vague folioBOT
Let me check the knowledge base for you again. One moment! :books:
Based on the knowledge sources, there is no official useFakeQuery function provided by Convex. However, the recommended approach for mocking useQuery in tests is to use your test runner’s mocking capabilities (such as Vitest’s vi.mock) to replace the internal useQuery implementation with your own function that returns the desired test data.
Here’s an example from the Convex documentation that shows how you might mock useQuery using Vitest. This is functionally similar to what a useFakeQuery would do:
import * as convexReact from "convex/react";
import { vi } from "vitest";
// Example fake implementation for useQuery
vi.mock("convex/react", async () => {
const actual = await vi.importActual<typeof convexReact>("convex/react");
return {
...actual,
// useQueryGeneric is called under the hood by useQuery
useQueryGeneric: (queryName: string, args: Record<string, any>) => {
if (queryName !== "counter:getCounter") {
throw new Error("Unexpected query call!");
}
// Return your fake data here
return 42; // Example fake value
},
};
});
In this example, the mocked useQueryGeneric function acts as a "fake" query hook, returning whatever data you specify for your tests. You can adapt this pattern to return different values or simulate loading/error states as needed Testing React Components with Convex: Mocking the convex import.
If you want a reusable function in your own codebase (outside of the test mocking context), you would typically just create a custom hook that returns static or mock data, but this is not shown in the official Convex documentation.
Summary:
There is no official useFakeQuery, but you can mock useQuery in your tests using your test runner’s mocking tools as shown above. This is the recommended and documented approach.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
distant wagon
@vague folio what about outside unit testing? I'm looking for something I can check on dev by dogfooding, but that will break any production build.
vague folioBOT
Let me check the knowledge base for you again. One moment! :books:
The knowledge sources do not explicitly mention an official or recommended way to use a "fake" query hook (like a useFakeQuery) for local development or "dogfooding" that is automatically disabled or breaks in production builds.
The documented approaches for mocking Convex queries—such as mocking useQuery with your test runner or using a fake Convex client—are focused on unit testing and test environments, not on runtime behavior in development vs. production builds Testing React Components with Convex: Mocking the convex import Dependency injection to replace the Convex client.
If you want to "dogfood" with fake data in development but ensure this never runs in production, you would need to implement your own environment checks and conditional logic. However, there is no official pattern or API for this in the Convex documentation or community sources provided.