Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
9.6 KB
Raw Blame
/**
 * Test render helpers.
 *
 * ── The problem this solves ─────────────────────────────────────────────────
 * `app/layout.tsx` wraps the app in eight nested contexts, and every one of
 * their hooks throws `"useX must be used within a XProvider"` when absent.
 * 69 of the 124 client components consume at least one of them, so without a
 * shared harness each component test opens by hand-rolling a provider stack —
 * which is why the suite has so far only reached pure helpers in `lib/`.
 *
 * ── The approach ────────────────────────────────────────────────────────────
 * These are the REAL providers, not fake context values. State is driven by
 * MSW payloads, the same way the app drives it, so `AuthProvider`'s mode
 * precedence and permission resolution stay under test in every test that
 * mounts it — consistent with the repo's rule about not mocking away
 * `app/api/queries/`. A component test failing because a provider is broken is
 * the intended behaviour: that is a bug the user would have hit.
 *
 * Deliberately does NOT use `app/providers.tsx` or
 * `app/api/get-query-client.ts`:
 *
 *   - `app/providers.tsx` monkey-patches `window.fetch` to intercept 401s and
 *     redirect. MSW's Node interceptor also patches `globalThis.fetch`, and the
 *     ordering between the two is unpredictable.
 *   - `getQueryClient()` memoizes a single client in browser environments, so
 *     cache would leak between tests in the same file.
 *
 * ── Usage ───────────────────────────────────────────────────────────────────
 *   renderWithProviders(<ConnectorCard />, {
 *     providers: ["auth", "brand", "task"],
 *     auth: authPresets.viewer,
 *     brand: "ibm",
 *   });
 *
 * Provider state resolves asynchronously (auth alone is three fetches), so the
 * first paint is always the loading state. Assert with `await screen.findBy…`
 * or `await waitFor(...)`, never a bare `getBy…` on the first tick.
 */
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { type RenderOptions, render } from "@testing-library/react";
import type { RequestHandler } from "msw";
import type { ComponentType, ReactElement, ReactNode } from "react";
import { TooltipProvider } from "@/components/ui/tooltip";
import { AuthProvider } from "@/contexts/auth-context";
import { BrandProvider } from "@/contexts/brand-context";
import { ChatProvider } from "@/contexts/chat-context";
import { ConsoleStatusProvider } from "@/contexts/console-status-context";
import { KnowledgeFilterProvider } from "@/contexts/knowledge-filter-context";
import { TaskProvider } from "@/contexts/task-context";
import { UnsavedChangesProvider } from "@/contexts/unsaved-changes-context";
import type { Brand } from "@/lib/brand";
import type { AuthScenario } from "@/test-utils/fixtures/auth";
import { authHandlers } from "@/test-utils/msw/auth";
import { server } from "@/test-utils/msw/server";

export function createTestQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
        staleTime: 0,
        gcTime: 0,
        refetchOnWindowFocus: false,
      },
      mutations: { retry: false },
    },
  });
}

export type ProviderName =
  | "tooltip"
  | "auth"
  | "brand"
  | "task"
  | "knowledgeFilter"
  | "consoleStatus"
  | "chat"
  | "unsavedChanges";

/**
 * Which providers each one needs beneath it.
 *
 * Listing a provider pulls its dependencies in automatically, so a test names
 * what the component uses rather than what the tree happens to require —
 * `providers: ["consoleStatus"]` is enough, even though it reads `useAuth`,
 * `useTask`, and `useKnowledgeFilter`.
 */
const PROVIDER_DEPENDENCIES: Record<ProviderName, ProviderName[]> = {
  tooltip: [],
  auth: [],
  brand: ["auth"],
  task: ["auth"],
  knowledgeFilter: [],
  consoleStatus: ["auth", "knowledgeFilter", "task"],
  chat: [],
  unsavedChanges: [],
};

/**
 * Nesting order, outermost first. Matches `app/layout.tsx` exactly — every
 * dependency above happens to be satisfied by that order, and keeping the two
 * in step means a test tree behaves like the real one.
 */
const PROVIDER_ORDER: ProviderName[] = [
  "tooltip",
  "auth",
  "brand",
  "task",
  "knowledgeFilter",
  "consoleStatus",
  "chat",
  "unsavedChanges",
];

const PROVIDER_COMPONENTS: Record<
  ProviderName,
  ComponentType<{ children: ReactNode }>
> = {
  tooltip: TooltipProvider,
  auth: AuthProvider,
  brand: BrandProvider,
  task: TaskProvider,
  knowledgeFilter: KnowledgeFilterProvider,
  consoleStatus: ConsoleStatusProvider,
  chat: ChatProvider,
  unsavedChanges: UnsavedChangesProvider,
};

function resolveProviders(requested: ProviderName[]): ProviderName[] {
  const selected = new Set<ProviderName>();

  const visit = (name: ProviderName) => {
    if (selected.has(name)) return;
    selected.add(name);
    for (const dep of PROVIDER_DEPENDENCIES[name]) visit(dep);
  };
  for (const name of requested) visit(name);

  return PROVIDER_ORDER.filter((name) => selected.has(name));
}

export interface ProviderOptions {
  /**
   * Contexts the component under test needs. Dependencies are added
   * automatically. `"all"` mounts the full `app/layout.tsx` stack — use it for
   * page-level tests; naming the two or three a component actually uses keeps
   * failures readable.
   */
  providers?: ProviderName[] | "all";
  /**
   * Auth scenario, installed as MSW handlers for `/api/auth/me`,
   * `/api/users/me`, and `/api/onboarding-status`. Defaults to whatever
   * `handlers.ts` ships (an admin with RBAC on). See
   * `test-utils/fixtures/auth.ts` for the presets.
   */
  auth?: AuthScenario;
  /**
   * Seeds the brand `BrandProvider` reads from localStorage. Note IBM auth
   * mode forces `"ibm"` regardless — set the auth scenario, not this, when
   * testing that path.
   */
  brand?: Brand;
  /**
   * Extra MSW handlers for this render, applied AFTER the auth scenario so
   * they win over it.
   *
   * Use this rather than calling `server.use()` in the test body: the harness
   * installs the auth scenario at render time, which would otherwise be
   * prepended over an override the test set up earlier. Handlers that have
   * nothing to do with the provider stack can still go through `server.use()`
   * directly.
   */
  handlers?: RequestHandler[];
  queryClient?: QueryClient;
}

interface RenderWithProvidersOptions
  extends Omit<RenderOptions, "wrapper">,
    ProviderOptions {}

function applyProviderOptions({ auth, brand, handlers }: ProviderOptions) {
  // Prepended, so it wins over the defaults in handlers.ts. setup.ts calls
  // server.resetHandlers() after every test, so this does not leak.
  if (auth) server.use(...authHandlers(auth));
  // After the scenario, so a per-render override beats it. MSW resolves with
  // the most recently prepended matching handler.
  if (handlers?.length) server.use(...handlers);
  // Written before render because BrandProvider reads localStorage in its
  // mount effect.
  if (brand) localStorage.setItem("brand", brand);
}

function buildWrapper(
  queryClient: QueryClient,
  providers: ProviderName[] | "all",
) {
  const active = resolveProviders(
    providers === "all" ? PROVIDER_ORDER : providers,
  );

  return function Wrapper({ children }: { children: ReactNode }) {
    // Reduced from the innermost outwards, so `active`'s order is the nesting
    // order in the rendered tree.
    const tree = active.reduceRight<ReactNode>((acc, name) => {
      const Provider = PROVIDER_COMPONENTS[name];
      // Keyed by provider name: these nest rather than sit as siblings, but a
      // stable key keeps React from remounting the whole stack if the set of
      // active providers ever changes between renders.
      return <Provider key={name}>{acc}</Provider>;
    }, children);

    return (
      <QueryClientProvider client={queryClient}>{tree}</QueryClientProvider>
    );
  };
}

/**
 * Renders `ui` inside a fresh react-query provider and the requested contexts.
 *
 * Returns the QueryClient alongside RTL's usual result so a test can seed or
 * inspect the cache directly when it needs to.
 */
export function renderWithProviders(
  ui: ReactElement,
  {
    queryClient = createTestQueryClient(),
    providers = [],
    auth,
    brand,
    handlers,
    ...options
  }: RenderWithProvidersOptions = {},
) {
  applyProviderOptions({ auth, brand, handlers });

  return {
    queryClient,
    ...render(ui, {
      wrapper: buildWrapper(queryClient, providers),
      ...options,
    }),
  };
}

/**
 * Wrapper for `renderHook`, which takes a component rather than a render call.
 *
 * Each call builds its own QueryClient, so hooks under test never share cache.
 * Takes the same provider options as `renderWithProviders`:
 *
 *   renderHook(() => usePermissions(), {
 *     wrapper: createQueryWrapper({ providers: ["auth"], auth: authPresets.viewer }),
 *   });
 */
export function createQueryWrapper(
  options: ProviderOptions | QueryClient = {},
) {
  // Historically this took a QueryClient positionally; keep that working.
  const opts: ProviderOptions =
    options instanceof QueryClient ? { queryClient: options } : options;

  applyProviderOptions(opts);

  return buildWrapper(
    opts.queryClient ?? createTestQueryClient(),
    opts.providers ?? [],
  );
}

export * from "@testing-library/react";
export { default as userEvent } from "@testing-library/user-event";