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

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: {

patches/@testing-library+react-render-stream+2.0.0.patch

@@ -0,0 +1,20 @@
+diff --git a/node_modules/@testing-library/react-render-stream/dist/pure.d.cts b/node_modules/@testing-library/react-render-stream/dist/pure.d.cts
+index 8964c27..8875af7 100644
+--- a/node_modules/@testing-library/react-render-stream/dist/pure.d.cts
++++ b/node_modules/@testing-library/react-render-stream/dist/pure.d.cts
+@@ -306,4 +306,4 @@ declare namespace disableActEnvironment {
+     var defaultOptions: Required<DisableActEnvironmentOptions>;
+ }
+
+-export { type Assertable, type RenderWithoutActAsync as AsyncRenderFn, type DisableActEnvironmentOptions, type NextRenderOptions, type RenderStream, type RenderStreamOptions, type RenderStreamWithRenderFn, type SnapshotStream, type SyncScreen, WaitForRenderTimeoutError, cleanup, createRenderStream, disableActEnvironment, renderHookToSnapshotStream, useTrackRenders };
++export { type Assertable, type RenderWithoutActAsync as AsyncRenderFn, type DisableActEnvironmentOptions, type NextRenderOptions, type Render, type RenderStream, type RenderStreamOptions, type RenderStreamWithRenderFn, type SnapshotStream, type SyncScreen, WaitForRenderTimeoutError, cleanup, createRenderStream, disableActEnvironment, renderHookToSnapshotStream, useTrackRenders };
+diff --git a/node_modules/@testing-library/react-render-stream/dist/pure.d.ts b/node_modules/@testing-library/react-render-stream/dist/pure.d.ts
+index 8964c27..8875af7 100644
+--- a/node_modules/@testing-library/react-render-stream/dist/pure.d.ts
++++ b/node_modules/@testing-library/react-render-stream/dist/pure.d.ts
+@@ -306,4 +306,4 @@ declare namespace disableActEnvironment {
+     var defaultOptions: Required<DisableActEnvironmentOptions>;
+ }
+
+-export { type Assertable, type RenderWithoutActAsync as AsyncRenderFn, type DisableActEnvironmentOptions, type NextRenderOptions, type RenderStream, type RenderStreamOptions, type RenderStreamWithRenderFn, type SnapshotStream, type SyncScreen, WaitForRenderTimeoutError, cleanup, createRenderStream, disableActEnvironment, renderHookToSnapshotStream, useTrackRenders };
++export { type Assertable, type RenderWithoutActAsync as AsyncRenderFn, type DisableActEnvironmentOptions, type NextRenderOptions, type Render, type RenderStream, type RenderStreamOptions, type RenderStreamWithRenderFn, type SnapshotStream, type SyncScreen, WaitForRenderTimeoutError, cleanup, createRenderStream, disableActEnvironment, renderHookToSnapshotStream, useTrackRenders };

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();
+});