Ensure variables are kept when refetching with a suspense hook that uses skipToken

.changeset/eleven-bikes-flash.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+Fix an issue where switching from options with `variables` to `skipToken` with `useSuspenseQuery` and `useBackgroundQuery` would create a new `ObservableQuery`. This could cause unintended refetches where `variables` were absent in the request when the query was referenced with `refetchQueries`.

.size-limits.json

@@ -1,6 +1,6 @@
 {
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43812,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38745,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33456,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27523
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 43882,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 38754,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33430,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27518
 }

ROADMAP.md

@@ -18,6 +18,7 @@ For up to date release notes, refer to the project's [Changelog](https://github.
 ### Apollo Client
 
 #### 4.1.0
+
 _Release candidate - November 14th, 2025_
 
 - Support for `@stream`

config/jest.config.ts

@@ -39,17 +39,23 @@ const ignoreDTSFiles = ".d.ts$";
 const ignoreTSFiles = ".ts$";
 const ignoreTSXFiles = ".tsx$";
 
-const react19TestFileIgnoreList = [ignoreDTSFiles, ignoreTSFiles];
-
-const react17TestFileIgnoreList = [
+const reactSharedTestFileIgnoreList = [
   ignoreDTSFiles,
   ignoreTSFiles,
+  "src/react/hooks/__tests__/useBackgroundQuery/testUtils.tsx",
+  "src/react/hooks/__tests__/useSuspenseQuery/testUtils.tsx",
+];
+
+const react17TestFileIgnoreList = [
+  ...reactSharedTestFileIgnoreList,
   // We only support Suspense with React 18, so don't test suspense hooks with
   // React 17
   "src/testing/experimental/__tests__/createTestSchema.test.tsx",
   "src/react/hooks/__tests__/useSuspenseFragment.test.tsx",
   "src/react/hooks/__tests__/useSuspenseQuery.test.tsx",
+  "src/react/hooks/__tests__/useSuspenseQuery/*",
   "src/react/hooks/__tests__/useBackgroundQuery.test.tsx",
+  "src/react/hooks/__tests__/useBackgroundQuery/*",
   "src/react/hooks/__tests__/useLoadableQuery.test.tsx",
   "src/react/hooks/__tests__/useQueryRefHandlers.test.tsx",
   "src/react/query-preloader/__tests__/createQueryPreloader.test.tsx",
@@ -81,15 +87,14 @@ const tsRxJSMinConfig = {
 const standardReact19Config = {
   ...defaults,
   displayName: "ReactDOM 19",
-  testPathIgnorePatterns: react19TestFileIgnoreList,
+  testPathIgnorePatterns: reactSharedTestFileIgnoreList,
 };
 
 const standardReact18Config = {
   ...defaults,
   displayName: "ReactDOM 18",
   testPathIgnorePatterns: [
-    ignoreDTSFiles,
-    ignoreTSFiles,
+    ...reactSharedTestFileIgnoreList,
     "src/react/ssr/__tests__/prerenderStatic.test.tsx",
   ],
   moduleNameMapper: {

package.json

@@ -180,7 +180,7 @@
     "@testing-library/dom": "10.4.0",
     "@testing-library/jest-dom": "6.6.3",
     "@testing-library/react": "16.1.0",
-    "@testing-library/react-render-stream": "2.0.0",
+    "@testing-library/react-render-stream": "2.0.2",
     "@testing-library/user-event": "14.5.2",
     "@types/babel__preset-env": "^7.10.0",
     "@types/bytes": "3.1.4",

src/react/hooks/__tests__/useBackgroundQuery/skipToken.test.tsx

@@ -0,0 +1,293 @@
+import { disableActEnvironment } from "@testing-library/react-render-stream";
+import React from "react";
+import { delay, of } from "rxjs";
+
+import {
+  ApolloClient,
+  ApolloLink,
+  InMemoryCache,
+  NetworkStatus,
+} from "@apollo/client";
+import { skipToken, useBackgroundQuery } from "@apollo/client/react";
+import {
+  createClientWrapper,
+  createMockWrapper,
+  setupVariablesCase,
+} from "@apollo/client/testing/internal";
+
+import { renderUseBackgroundQuery } from "./testUtils.js";
+
+// https://github.com/apollographql/apollo-client/issues/12989
+test("maintains variables when switching to `skipToken` and calling `refetchQueries` while skipped after initial request", async () => {
+  const { query } = setupVariablesCase();
+
+  const client = new ApolloClient({
+    link: new ApolloLink((operation) => {
+      return of(
+        operation.variables.id === "1" ?
+          {
+            data: {
+              character: {
+                __typename: "Character",
+                id: "1",
+                name: "Spider-Man",
+              },
+            },
+          }
+        : {
+            data: null,
+            errors: [
+              { message: `Fetched wrong id: ${operation.variables.id}` },
+            ],
+          }
+      ).pipe(delay(10));
+    }),
+    cache: new InMemoryCache(),
+  });
+
+  using _disabledAct = disableActEnvironment();
+  const { rerender, takeRender } = await renderUseBackgroundQuery(
+    ({ id }) =>
+      useBackgroundQuery(
+        query,
+        id === undefined ? skipToken : { variables: { id } }
+      ),
+    {
+      initialProps: { id: "1" as string | undefined },
+      wrapper: createClientWrapper(client),
+    }
+  );
+
+  {
+    const { renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "<Suspense />",
+    ]);
+  }
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual(["useReadQuery"]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await rerender({ id: undefined });
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "useReadQuery",
+    ]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await expect(takeRender).not.toRerender();
+
+  await expect(
+    client.refetchQueries({ include: [query] })
+  ).resolves.toStrictEqualTyped([
+    {
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+    },
+  ]);
+
+  await expect(takeRender).not.toRerender();
+});
+
+test("suspends and fetches when changing variables when no longer using skipToken", async () => {
+  const { query, mocks } = setupVariablesCase({
+    delay: React.version.startsWith("18") ? 200 : 20,
+  });
+
+  using _disabledAct = disableActEnvironment();
+  const { rerender, takeRender } = await renderUseBackgroundQuery(
+    ({ id }) =>
+      useBackgroundQuery(
+        query,
+        id === undefined ? skipToken : { variables: { id } }
+      ),
+    {
+      initialProps: { id: "1" as string | undefined },
+      wrapper: createMockWrapper({ mocks }),
+    }
+  );
+
+  {
+    const { renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "<Suspense />",
+    ]);
+  }
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual(["useReadQuery"]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await rerender({ id: undefined });
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "useReadQuery",
+    ]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await rerender({ id: "2" });
+
+  {
+    const { renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "<Suspense />",
+    ]);
+  }
+
+  {
+    const { snapshot } = await takeRender();
+
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "2", name: "Black Widow" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await expect(takeRender).not.toRerender();
+});
+
+test("does not suspend for data in the cache when changing variables when no longer using skipToken", async () => {
+  const { query, mocks } = setupVariablesCase();
+
+  const cache = new InMemoryCache();
+
+  cache.writeQuery({
+    query,
+    data: {
+      character: { __typename: "Character", id: "2", name: "Cached Widow" },
+    },
+    variables: { id: "2" },
+  });
+
+  using _disabledAct = disableActEnvironment();
+  const { rerender, takeRender } = await renderUseBackgroundQuery(
+    ({ id }) =>
+      useBackgroundQuery(
+        query,
+        id === undefined ? skipToken : { variables: { id } }
+      ),
+    {
+      initialProps: { id: "1" as string | undefined },
+      wrapper: createMockWrapper({ cache, mocks }),
+    }
+  );
+
+  {
+    const { renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "<Suspense />",
+    ]);
+  }
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual(["useReadQuery"]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await rerender({ id: undefined });
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "useReadQuery",
+    ]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "1", name: "Spider-Man" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await rerender({ id: "2" });
+
+  {
+    const { snapshot, renderedComponents } = await takeRender();
+
+    expect(renderedComponents).toStrictEqual([
+      "useBackgroundQuery",
+      "useReadQuery",
+    ]);
+    expect(snapshot).toStrictEqualTyped({
+      data: {
+        character: { __typename: "Character", id: "2", name: "Cached Widow" },
+      },
+      dataState: "complete",
+      error: undefined,
+      networkStatus: NetworkStatus.ready,
+    });
+  }
+
+  await expect(takeRender).not.toRerender();
+});