🤖 refactor: organize browser UI integration harness

Author: ammar-agent

jest.config.js

@@ -54,10 +54,10 @@ module.exports = {
       displayName: "browser-ui",
       testEnvironment: "jsdom",
       testMatch: ["<rootDir>/tests/browser/**/*.test.tsx"],
-      setupFiles: ["<rootDir>/tests/browser/global-setup.js"],
+      setupFiles: ["<rootDir>/tests/browser/harness/global-setup.js"],
       setupFilesAfterEnv: [
         "<rootDir>/tests/setup.ts",
-        "<rootDir>/tests/browser/jestSetup.ts",
+        "<rootDir>/tests/browser/harness/jestSetup.ts",
       ],
     },
   ],

tests/browser/appLoader.test.tsx

@@ -8,14 +8,15 @@
 import userEvent from "@testing-library/user-event";
 import "@testing-library/jest-dom";
 import { shouldRunIntegrationTests } from "../testUtils";
-import { renderWithBackend } from "./renderWithBackend";
-import { createTempGitRepo, cleanupTempGitRepo } from "./setup";
 import {
+  renderWithBackend,
+  createTempGitRepo,
+  cleanupTempGitRepo,
   waitForAppLoad,
   addProjectViaUI,
   expandProject,
   getProjectName,
-} from "./uiHelpers";
+} from "./harness";
 
 const describeIntegration = shouldRunIntegrationTests() ? describe : describe.skip;
 

tests/browser/setup.ts tests/browser/harness/env.tstests/browser/setup.ts renamed to tests/browser/harness/env.ts

@@ -14,7 +14,7 @@ import type { BrowserWindow, WebContents } from "electron";
 import { Config } from "@/node/config";
 import { ServiceContainer } from "@/node/services/serviceContainer";
 import type { ORPCContext } from "@/node/orpc/context";
-import { createOrpcTestClient, type OrpcTestClient } from "../ipc/orpcTestClient";
+import { createOrpcTestClient, type OrpcTestClient } from "../../ipc/orpcTestClient";
 import type { APIClient } from "@/browser/contexts/API";
 
 const execAsync = promisify(exec);

tests/browser/global-setup.js tests/browser/harness/global-setup.jstests/browser/global-setup.js renamed to tests/browser/harness/global-setup.js

@@ -0,0 +1,10 @@
+/**
+ * Browser UI integration test harness.
+ *
+ * Keep all non-test helpers in this folder so the top-level `tests/browser/`
+ * contains only test entrypoints.
+ */
+
+export * from "./env";
+export * from "./render";
+export * from "./ui";

tests/browser/harness/index.ts

@@ -10,7 +10,7 @@ import React from "react";
 import { act, render, type RenderOptions, type RenderResult } from "@testing-library/react";
 import { AppLoader } from "@/browser/components/AppLoader";
 import type { APIClient } from "@/browser/contexts/API";
-import { createBrowserTestEnv, type BrowserTestEnv } from "./setup";
+import { createBrowserTestEnv, type BrowserTestEnv } from "./env";
 
 export interface RenderWithBackendResult extends RenderResult {
   /** Test environment with real backend */

tests/browser/jestSetup.ts tests/browser/harness/jestSetup.tstests/browser/jestSetup.ts renamed to tests/browser/harness/jestSetup.ts

@@ -8,13 +8,14 @@
  * Use these instead of direct oRPC calls to keep tests UI-driven.
  */
 
-import { waitFor, type RenderResult } from "@testing-library/react";
+import { waitFor, within, type RenderResult } from "@testing-library/react";
 import type { UserEvent } from "@testing-library/user-event";
 
 type Queries = Pick<
   RenderResult,
   | "findByRole"
   | "findByText"
+  | "findByTestId"
   | "findByPlaceholderText"
   | "queryByRole"
   | "queryByText"
@@ -27,12 +28,51 @@ type Queries = Pick<
 export async function waitForAppLoad(queries: Pick<Queries, "queryByText">) {
   await waitFor(
     () => {
-      expect(queries.queryByText(/loading workspaces/i)).not.toBeInTheDocument();
+      expect(queries.queryByText(/loading workspaces/i)).toBeNull();
     },
     { timeout: 5000 }
   );
 }
 
+/**
+ * Open the Settings modal.
+ *
+ * Note: the Dialog is rendered in a portal; queries must search `document.body`.
+ * RTL's render() uses `document.body` as baseElement by default, so RenderResult
+ * queries work fine.
+ */
+export async function openSettingsModal(
+  user: UserEvent,
+  queries: Pick<Queries, "findByTestId" | "findByRole">
+): Promise<HTMLElement> {
+  const settingsButton = await queries.findByTestId("settings-button");
+  await user.click(settingsButton);
+
+  const modal = await queries.findByRole("dialog");
+  expect(modal).toBeTruthy();
+  return modal;
+}
+
+/**
+ * Open the Settings modal and navigate to a particular section.
+ */
+export async function openSettingsToSection(
+  user: UserEvent,
+  queries: Pick<Queries, "findByTestId" | "findByRole">,
+  sectionLabel: "General" | "Providers" | "Projects" | "Models"
+): Promise<HTMLElement> {
+  const modal = await openSettingsModal(user, queries);
+
+  if (sectionLabel !== "General") {
+    const sectionButton = within(modal).getByRole("button", {
+      name: new RegExp(`^${sectionLabel}$`, "i"),
+    });
+    await user.click(sectionButton);
+  }
+
+  return modal;
+}
+
 /**
  * Add a project via the UI.
  *
@@ -56,7 +96,7 @@ export async function addProjectViaUI(
 
   // Wait for modal to open
   const modal = await queries.findByRole("dialog");
-  expect(modal).toBeInTheDocument();
+  expect(modal).toBeTruthy();
 
   // Type the project path in the input
   const pathInput = await queries.findByPlaceholderText(/home.*project|path/i);
@@ -71,7 +111,7 @@ export async function addProjectViaUI(
   await waitFor(
     () => {
       // Modal should close on success
-      expect(queries.queryByRole("dialog")).not.toBeInTheDocument();
+      expect(queries.queryByRole("dialog")).toBeNull();
     },
     { timeout: 5000 }
   );
@@ -142,7 +182,7 @@ export async function removeProjectViaUI(
   await waitFor(() => {
     expect(
       queries.queryByRole("button", { name: new RegExp(`project ${projectName}`, "i") })
-    ).not.toBeInTheDocument();
+    ).toBeNull();
   });
 }
 
@@ -210,7 +250,7 @@ export async function removeWorkspaceViaUI(
   await waitFor(() => {
     expect(
       queries.queryByRole("button", { name: `Select workspace ${workspaceName}` })
-    ).not.toBeInTheDocument();
+    ).toBeNull();
   });
 }
 

tests/browser/renderWithBackend.tsx tests/browser/harness/render.tsxtests/browser/renderWithBackend.tsx renamed to tests/browser/harness/render.tsx

@@ -11,9 +11,10 @@ import { waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import "@testing-library/jest-dom";
 import { shouldRunIntegrationTests } from "../testUtils";
-import { renderWithBackend } from "./renderWithBackend";
-import { createTempGitRepo, cleanupTempGitRepo } from "./setup";
 import {
+  renderWithBackend,
+  createTempGitRepo,
+  cleanupTempGitRepo,
   waitForAppLoad,
   addProjectViaUI,
   expandProject,
@@ -23,7 +24,7 @@ import {
   removeWorkspaceViaUI,
   clickNewChat,
   getProjectName,
-} from "./uiHelpers";
+} from "./harness";
 
 const describeIntegration = shouldRunIntegrationTests() ? describe : describe.skip;