Files
PaperClipAI/ui/src/lib/query-client.test.ts
T
Devin FoleyandClaude Opus 5.5 5570debc5b fix(ui): stop reporting cancelled queries to Sentry (#20430)
React Query's CancelledError keeps the default Error name, so the
name-based abort check never matched it. A query cancelled with
revert: false (for example by the persisted cache when an issue read
is denied or the account changes) reached the query cache onError as
an "unknown" error and was sent to Sentry. Recognize it by class.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 17:43:34 -08:00

331 lines
14 KiB
TypeScript

import { onlineManager, QueryObserver, MutationObserver, type QueryClient } from "@tanstack/react-query";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ApiError } from "@/api/client";
import { ApiUnavailableError } from "@/api/response";
import { createConnectivityStore, type ConnectivityStore, type ProbeResult } from "./connectivity";
import {
bindConnectivity,
createAppQueryClient,
reconnectDelayFor,
retryDelayFor,
shouldReportQueryError,
QueryNotReadyError,
shouldRetryRequest,
TRANSIENT_RETRY_DELAYS_MS,
type MutationErrorToast,
} from "./query-client";
const gatewayDown = () => new ApiError("Paperclip is restarting", 503, { error: "tenant_app_unavailable" });
describe("retry policy", () => {
it("retries transient errors for about 30 seconds", () => {
const error = new ApiUnavailableError(502);
const retries = TRANSIENT_RETRY_DELAYS_MS.length;
expect(shouldRetryRequest(retries - 1, error)).toBe(true);
expect(shouldRetryRequest(retries, error)).toBe(false);
const total = TRANSIENT_RETRY_DELAYS_MS.reduce((sum, delay) => sum + delay, 0);
expect(total).toBeGreaterThanOrEqual(25_000);
expect(total).toBeLessThanOrEqual(35_000);
});
it.each([400, 401, 403, 404, 409, 422])("never retries a %s", (status) => {
expect(shouldRetryRequest(0, new ApiError("No", status, null))).toBe(false);
});
it("retries the gateway code even when it arrives with a 4xx", () => {
expect(shouldRetryRequest(0, new ApiError("x", 404, { error: "tenant_app_unavailable" }))).toBe(true);
});
it("retries unexpected failures briefly and aborts never", () => {
expect(shouldRetryRequest(0, new ApiError("boom", 500, null))).toBe(true);
expect(shouldRetryRequest(2, new ApiError("boom", 500, null))).toBe(false);
expect(shouldRetryRequest(0, new DOMException("Aborted", "AbortError"))).toBe(false);
});
it("backs off and honors Retry-After", () => {
const error = new ApiUnavailableError(503);
expect(retryDelayFor(0, error)).toBe(1_000);
expect(retryDelayFor(4, error)).toBe(15_000);
expect(retryDelayFor(9, error)).toBe(15_000);
const throttled = new ApiError("Slow down", 429, null, { retryAfterMs: 6_000 });
expect(retryDelayFor(0, throttled)).toBe(6_000);
// A rate-limit window longer than the normal backoff is waited out in full.
const minuteWindow = new ApiError("Slow down", 429, null, { retryAfterMs: 55_000 });
expect(retryDelayFor(0, minuteWindow)).toBe(55_000);
expect(retryDelayFor(0, new ApiUnavailableError(503, 20_000))).toBe(20_000);
expect(reconnectDelayFor(0, throttled)).toBe(6_000);
expect(reconnectDelayFor(3, new ApiUnavailableError(503))).toBe(10_000);
});
it("reports only unexpected query errors to Sentry", () => {
expect(shouldReportQueryError(new ApiError("boom", 500, null))).toBe(true);
expect(shouldReportQueryError(new Error("parse failure"))).toBe(true);
expect(shouldReportQueryError(new QueryNotReadyError("Not ready"))).toBe(false);
expect(shouldReportQueryError(gatewayDown())).toBe(false);
expect(shouldReportQueryError(new TypeError("Failed to fetch"))).toBe(false);
expect(shouldReportQueryError(new ApiError("Not found", 404, null))).toBe(false);
});
});
describe("createAppQueryClient", () => {
let store: ConnectivityStore;
let probe: ReturnType<typeof vi.fn<() => Promise<ProbeResult>>>;
let client: QueryClient;
let unbind: () => void;
let notifyMutationError: ReturnType<typeof vi.fn<(toast: MutationErrorToast) => void>>;
let reportError: ReturnType<typeof vi.fn<(error: unknown) => void>>;
beforeEach(() => {
vi.useFakeTimers();
probe = vi.fn<() => Promise<ProbeResult>>().mockResolvedValue({ reachable: false, retryAfterMs: null });
store = createConnectivityStore({ probe, browserOnline: true });
notifyMutationError = vi.fn<(toast: MutationErrorToast) => void>();
reportError = vi.fn<(error: unknown) => void>();
client = createAppQueryClient({ connectivity: store, notifyMutationError, reportError });
client.mount();
unbind = bindConnectivity(client, store);
});
afterEach(() => {
unbind();
store.dispose();
client.unmount();
client.clear();
onlineManager.setOnline(true);
vi.useRealTimers();
});
it("pauses a failing query during an outage and refreshes it on recovery", async () => {
let down = true;
const queryFn = vi.fn(async () => {
if (down) throw gatewayDown();
return "fresh";
});
const observer = new QueryObserver(client, { queryKey: ["issue", "1"], queryFn });
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
expect(store.getSnapshot().status).toBe("reconnecting");
expect(onlineManager.isOnline()).toBe(false);
await vi.advanceTimersByTimeAsync(30_000);
// Paused, not failed, and not hammering the server.
expect(observer.getCurrentResult()).toMatchObject({ status: "pending", fetchStatus: "paused" });
expect(queryFn).toHaveBeenCalledTimes(1);
down = false;
probe.mockResolvedValue({ reachable: true });
await vi.advanceTimersByTimeAsync(15_000);
expect(store.getSnapshot().status).toBe("online");
expect(observer.getCurrentResult()).toMatchObject({ status: "success", data: "fresh" });
unsubscribe();
});
it("keeps cached data when a background refetch hits an outage", async () => {
let down = false;
const observer = new QueryObserver(client, {
queryKey: ["issue", "2"],
queryFn: async () => {
if (down) throw gatewayDown();
return "loaded";
},
});
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
down = true;
void observer.refetch();
await vi.advanceTimersByTimeAsync(5_000);
expect(observer.getCurrentResult()).toMatchObject({ data: "loaded", error: null });
unsubscribe();
});
it("refreshes active queries once on recovery", async () => {
const queryFn = vi.fn(async () => "ok");
const observer = new QueryObserver(client, { queryKey: ["list"], queryFn, staleTime: Infinity });
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
expect(queryFn).toHaveBeenCalledTimes(1);
store.reportError(gatewayDown());
await vi.advanceTimersByTimeAsync(0);
probe.mockResolvedValue({ reachable: true });
await vi.advanceTimersByTimeAsync(1_000);
expect(queryFn).toHaveBeenCalledTimes(2);
unsubscribe();
});
it("does not treat setQueryData as proof the server is back", async () => {
store.reportError(gatewayDown());
await vi.advanceTimersByTimeAsync(0);
client.setQueryData(["optimistic"], "local");
expect(store.getSnapshot().status).toBe("reconnecting");
});
it("does not infer server recovery from an unrelated in-flight query", async () => {
let finish!: (value: null) => void;
const pending = new Promise<null>(resolve => { finish = resolve; });
const observer = new QueryObserver(client, { queryKey: ["npm-registry"], queryFn: () => pending });
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
store.reportError(gatewayDown());
await vi.advanceTimersByTimeAsync(0);
expect(store.getSnapshot().status).toBe("reconnecting");
finish(null);
await vi.advanceTimersByTimeAsync(0);
expect(store.getSnapshot().status).toBe("reconnecting");
expect(onlineManager.isOnline()).toBe(false);
probe.mockResolvedValue({ reachable: true });
await vi.advanceTimersByTimeAsync(1_000);
expect(store.getSnapshot().status).toBe("online");
unsubscribe();
});
it("does not infer server recovery from an unrelated mutation", async () => {
store.reportError(gatewayDown());
await vi.advanceTimersByTimeAsync(0);
const observer = new MutationObserver(client, { mutationFn: async () => "external success" });
await observer.mutate();
expect(store.getSnapshot().status).toBe("reconnecting");
expect(onlineManager.isOnline()).toBe(false);
});
it("fails an ordinary mutation fast during an outage", async () => {
const mutationFn = vi.fn(async () => {
throw gatewayDown();
});
const observer = new MutationObserver(client, { mutationFn });
await expect(observer.mutate()).rejects.toBeInstanceOf(ApiError);
expect(mutationFn).toHaveBeenCalledTimes(1);
});
it("pauses an idempotent mutation across an outage and resends it on reconnect", async () => {
let down = true;
const mutationFn = vi.fn(async (value: string) => {
if (down) throw gatewayDown();
return value;
});
const observer = new MutationObserver(client, { mutationFn, meta: { replay: "idempotent" } });
const result = observer.mutate("title");
await vi.advanceTimersByTimeAsync(60_000);
expect(observer.getCurrentResult()).toMatchObject({ status: "pending", isPaused: true });
expect(mutationFn).toHaveBeenCalledTimes(1);
expect(store.getSnapshot().pendingWrites).toBe(1);
down = false;
probe.mockResolvedValue({ reachable: true });
await vi.advanceTimersByTimeAsync(15_000);
await expect(result).resolves.toBe("title");
expect(mutationFn).toHaveBeenCalledTimes(2);
expect(store.getSnapshot().pendingWrites).toBe(0);
});
it("toasts readable copy for a failed opted-in mutation without its own handler", async () => {
const observer = new MutationObserver(client, {
mutationFn: async () => {
throw new ApiError("Title is required", 422, { error: "Title is required" });
},
meta: { errorToast: true },
});
await observer.mutate().catch(() => undefined);
expect(notifyMutationError).toHaveBeenCalledWith({ title: "Check your input", body: "Title is required" });
});
it("toasts a transient failure the banner does not cover", async () => {
const observer = new MutationObserver(client, {
mutationFn: async () => {
throw new ApiError("Slow down", 429, null);
},
meta: { errorToast: true },
});
await observer.mutate().catch(() => undefined);
expect(notifyMutationError).toHaveBeenCalledWith({
title: "Connection interrupted",
body: "Paperclip is temporarily unavailable. Please try again in a moment.",
});
});
it("does not toast covered transient failures, handled mutations, or mutations that did not opt in", async () => {
const fail = (error: unknown) => async () => {
throw error;
};
store.reportError(gatewayDown());
await vi.advanceTimersByTimeAsync(0);
expect(store.getSnapshot().status).toBe("reconnecting");
await new MutationObserver(client, {
mutationFn: fail(gatewayDown()),
meta: { errorToast: true },
}).mutate().catch(() => undefined);
await new MutationObserver(client, {
mutationFn: fail(new ApiError("No", 403, null)),
onError: () => undefined,
meta: { errorToast: true },
}).mutate().catch(() => undefined);
// Surfaces that render `mutation.error` inline must not get a second copy.
await new MutationObserver(client, {
mutationFn: fail(new ApiError("No", 403, null)),
}).mutate().catch(() => undefined);
expect(notifyMutationError).not.toHaveBeenCalled();
});
it("reports an unexpected query error to Sentry once per query", async () => {
const queryFn = vi.fn(async () => {
throw new ApiError("boom", 500, { error: "boom" });
});
const observer = new QueryObserver(client, { queryKey: ["broken"], queryFn, retry: false });
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
await observer.refetch();
expect(queryFn).toHaveBeenCalledTimes(2);
expect(reportError).toHaveBeenCalledTimes(1);
unsubscribe();
});
it("does not report a query that was cancelled without reverting", async () => {
const queryFn = vi.fn(() => new Promise<string>(() => {}));
const observer = new QueryObserver(client, { queryKey: ["issues", "detail", "PAP-1"], queryFn });
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
await client.cancelQueries({ queryKey: ["issues", "detail"] }, { revert: false });
expect(observer.getCurrentResult().error?.message).toBe("CancelledError");
expect(reportError).not.toHaveBeenCalled();
unsubscribe();
});
it("leaves a cache-only alias stale instead of refetching it without a queryFn", async () => {
client.setQueryData(["issues", "detail", "issue-uuid"], { id: "issue-uuid", title: "Seeded" });
const queryFn = vi.fn(async () => "fetched");
client.setQueryData(["issues", "detail", "PAP-1"], "seeded");
await client.prefetchQuery({ queryKey: ["issues", "detail", "PAP-1"], queryFn, staleTime: 0 });
queryFn.mockClear();
void client.invalidateQueries({ queryKey: ["issues", "detail"], refetchType: "inactive" });
void client.refetchQueries({ queryKey: ["issues", "detail"], type: "all" });
await vi.advanceTimersByTimeAsync(60_000);
const alias = client.getQueryCache().find({ queryKey: ["issues", "detail", "issue-uuid"], exact: true });
expect(alias?.state.status).toBe("success");
expect(alias?.state.isInvalidated).toBe(true);
expect(alias?.state.data).toEqual({ id: "issue-uuid", title: "Seeded" });
expect(queryFn).toHaveBeenCalledTimes(2);
expect(reportError).not.toHaveBeenCalled();
const aliasQueryFn = vi.fn(async () => ({ id: "issue-uuid", title: "Fresh" }));
const observer = new QueryObserver(client, { queryKey: ["issues", "detail", "issue-uuid"], queryFn: aliasQueryFn });
const unsubscribe = observer.subscribe(() => {});
await vi.advanceTimersByTimeAsync(0);
expect(aliasQueryFn).toHaveBeenCalledTimes(1);
expect(observer.getCurrentResult().data).toEqual({ id: "issue-uuid", title: "Fresh" });
unsubscribe();
});
it("keeps the caller's refetch predicate", async () => {
const keep = vi.fn(async () => "keep");
const skip = vi.fn(async () => "skip");
await client.prefetchQuery({ queryKey: ["keep"], queryFn: keep });
await client.prefetchQuery({ queryKey: ["skip"], queryFn: skip });
await client.refetchQueries({ predicate: (query) => query.queryKey[0] === "keep" });
expect(keep).toHaveBeenCalledTimes(2);
expect(skip).toHaveBeenCalledTimes(1);
});
});