@nocobase/app-template-default 1.0.0-beta.79 → 1.0.0-beta.80

package/AGENTS.md

@@ -16,7 +16,7 @@ This file stays at most 32 KB and must not grow without bound, because every age
 
 - Application-specific guidance — including what a change to this application's structure, shell or conventions needs the next agent to know — goes in `.agents/rules/<topic>.md`. Update the relevant file, or add one, and add or update its entry in the [index](#index) below rather than writing the detail here.
 - Framework-wide guidance lives in the synchronized Skills under `.agents/skills/`. Link to it, never copy it here; when it is wrong for every application, correct it upstream in `@nocobase/app-skills`.
-- `tests/logic/agents-md.test.ts` enforces the size limit and checks that the links here and in `.agents/rules/` resolve.
+- `tests/project/agents-md.test.ts` enforces the size limit and checks that the links here and in `.agents/rules/` resolve.
 
 ## Load the development skills
 
@@ -61,7 +61,7 @@ A bare create-app shows Home to signed-in users and System settings → App foun
 
 Declare every page in `client/routes.ts` with `defineAppRoutes()` and keep its component behind a lazy `componentLoader` whose module default-exports it. Never write the deployment base path such as `/main` into a route — the runtime restores it. `auth` controls browser navigation only and is not server security. Declare `navigation` on the route to put it in a menu, and always declare `authz` on the first page of every path; the page id identifies stored page grants, so changing it requires migrating the grants that reference it. Read [pages and routes](.agents/skills/nocobase-app-development/references/frontend/references/page.md), and [overlays](.agents/skills/nocobase-app-development/references/frontend/references/overlay.md) before implementing dialogs, drawers or close guards.
 
-Every route listed as a page permission needs a localized display name: use its existing navigation/breadcrumb title, or add its application route name to `client/pages/settings/page-permission-titles.ts` for an overlay or other page with no title metadata. Do not add breadcrumbs/menus just to label an overlay. Run `tests/logic/page-permission-titles.test.ts`; it requires non-empty English/Chinese labels and rejects missing or stale mappings. Never rename route/permission ids or change `authz` to fix display text.
+Every route listed as a page permission needs a localized display name: use its existing navigation/breadcrumb title, or add its application route name to `client/pages/settings/page-permission-titles.ts` for an overlay or other page with no title metadata. Do not add breadcrumbs/menus just to label an overlay. Run `tests/client/page-permission-titles.test.ts`; it requires non-empty English/Chinese labels and rejects missing or stale mappings. Never rename route/permission ids or change `authz` to fix display text.
 
 ### Components and styling
 
@@ -101,7 +101,7 @@ When reporting or opening this application's address, use the `Local:` URL print
 
 Scope all verification — formatting, lint, type checking, tests, builds and runtime checks — to the affected files, projects, or packages and their affected consumers. Do not run full-application or workspace-wide checks, or an aggregate `pnpm check`, as a routine step after each edit. Documentation-only changes need formatting and link checks for the changed documents, not type checking, runtime tests, or builds. Report which checks ran, their scope, and any unverified behavior.
 
-Add tests for what you changed — a route's authenticated, unauthenticated, and unauthorized responses; a migration's `up` and `down` against a real database; a page's actual behavior — in `tests/`, never beside the source; browser tests go in `tests/playwright/`. Start page tests from `tests/components/page-harness.test.tsx`, which keeps application hooks real and supplies external responses through the test fixture. See [testing and verification](.agents/skills/nocobase-app-development/references/testing.md).
+Add tests for what you changed — a route's authenticated, unauthenticated, and unauthorized responses; a migration's `up` and `down` against a real database; a page's actual behavior — in `tests/`, never beside the source; browser tests go in `tests/playwright/`. Start page tests from `tests/client/page-harness.test.tsx`, which keeps application hooks real and supplies external responses through the test fixture. See [testing and verification](.agents/skills/nocobase-app-development/references/testing.md).
 
 For any UI work, start with [the frontend workflow](.agents/skills/nocobase-app-development/references/frontend/ui-workflow.md), which decides the workflow and routes to the styling rules, the theme token contract and the rest.
 
@@ -128,4 +128,4 @@ When the built-in mechanism genuinely cannot express what is being asked, changi
 
 Assign application business roles to explicitly identified users through the prepared User management role-assignment UI. Never seed a business permission set onto `authenticated:*`, broaden the inherited platform `member` role, or write startup reconciliation that grants access to everyone merely to make a feature usable. Unchecked actions in one role do not revoke grants inherited from another. If the user explicitly requests a global default role, first deliver a permission-protected administration control that shows its recipients and allows changing or removing the assignment; show inherited roles and their source in user access details. Without that UI, use explicit user assignments and explain the limitation. Keep page access independent from business operations.
 
-Run `pnpm exec vitest run tests/logic/authorization-assignment-safety.test.ts` after permission initialization changes and before delivery. It boots the real application on an isolated database and inspects initialized wildcard assignments and the inherited member role. Keep this test in generated applications. An intentional global default requires explicit user authorization, a working administration surface and corresponding acceptance tests before deliberately updating the expected baseline; do not delete, skip or loosen the guard to make tests pass. Test an ordinary user with only the configured role: inspect all effective grant sources and verify both hidden buttons and rejected direct API calls.
+Run `pnpm exec vitest run tests/server/authorization-assignment-safety.test.ts` after permission initialization changes and before delivery. It boots the real application on an isolated database and inspects initialized wildcard assignments and the inherited member role. Keep this test in generated applications. An intentional global default requires explicit user authorization, a working administration surface and corresponding acceptance tests before deliberately updating the expected baseline; do not delete, skip or loosen the guard to make tests pass. Test an ordinary user with only the configured role: inspect all effective grant sources and verify both hidden buttons and rejected direct API calls.

package/README.MD

@@ -399,9 +399,11 @@ An environment variable a section declares takes precedence over the file, and t
 
 ## Testing
 
-Tests live in `tests/`, never beside the source they cover. Put logic and integration tests under `tests/logic/` and component tests under `tests/components/`. Browser tests belong in `tests/playwright/`, which Vitest skips. Playwright does not start the application: start it first (`pnpm dev`, or `pnpm build` and then the built application), then run `pnpm test:e2e`; each test reads the application URL, including its base path, from `APP_URL`. Tests that only need a real server, real authentication, or a real database run under Vitest with `createAppTest()` from `@nocobase/app-testing/server`.
+Tests live in `tests/`, never beside the source they cover. Group tests by the source they cover: `tests/client/` for pages, components and client logic; `tests/server/` for services and routes; `tests/database/` for migrations and seeds; `tests/cli/` for application commands; and `tests/project/` for package configuration and build artifacts. Create optional directories with their first test. Vitest projects select jsdom for client tests and Node for the other groups, so no per-file environment override is needed. Both projects run files sequentially because client integration tests also provision databases; client setup files apply only to the client project. Keep shared helpers and data in `tests/helpers/` and `tests/fixtures/`, without test files. Browser tests belong in `tests/playwright/`, which Vitest skips. Playwright does not start the application: start it first (`pnpm dev`, or `pnpm build` and then the built application), then run `pnpm test:e2e`; each test reads the application URL, including its base path, from `APP_URL`. Tests that only need a real server, real authentication, or a real database run under Vitest with `createAppTest()` from `@nocobase/app-testing/server`.
 
-Application tests use the `/server`, `/client` and `/cli` entries of `@nocobase/app-testing`. Start page tests from `tests/components/page-harness.test.tsx`: it uses `renderWithApp()` with real application hooks, strict translations, permission checks and a test toaster. Answer requests through `answerApi()` and replace external services through `services`, without also registering their owning plugins. The template's Vitest configuration includes client plugins in custom package scopes so their contexts and service tokens remain shared. See `.agents/skills/nocobase-app-development/references/testing.md` for fixture ownership and complete server, migration and CLI examples.
+Application tests use the `/server`, `/client` and `/cli` entries of `@nocobase/app-testing`. Start page tests from `tests/client/page-harness.test.tsx`: it uses `renderWithApp()` with real application hooks, strict translations, permission checks and a test toaster. Prefer an actual test server for application requests. Use `answerApi()` for cases that require controlled protocol responses, and replace an external service through `services` only when the real boundary cannot be exercised, without also registering its owning plugin. The template's Vitest configuration includes client plugins in custom package scopes so their contexts and service tokens remain shared. See `.agents/skills/nocobase-app-development/references/testing.md` for fixture ownership and complete server, migration and CLI examples.
+
+For authentication, permissions and persisted page behavior, use `tests/helpers/authenticated-client.tsx`. It starts the real application on isolated databases, signs in through its API, and forwards requests with a cookie jar to the in-process server. `tests/setup/application-environment.ts` keeps the DOM in jsdom and loads server dependencies through Vite's server environment so Node workers are not rewritten as browser workers. Prefer real components, hooks and services; inject a transport failure or delay only when the scenario requires it. Verify the final UI and server state after retries and permission reloads, not just that a request was called.
 
 ### Notification verification
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nocobase/app-template-default",
   "displayName": "Default Template",
-  "version": "1.0.0-beta.79",
+  "version": "1.0.0-beta.80",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -9,7 +9,7 @@
   },
   "nocobase": {
     "templateKind": "app",
-    "defaultTemplateVersion": "1.0.0-beta.79"
+    "defaultTemplateVersion": "1.0.0-beta.80"
   },
   "devDependencies": {
     "@ai-sdk/react": "4.0.131",
@@ -72,9 +72,10 @@
     "tar": "^7.5.22",
     "@xyflow/react": "^12.11.5",
     "elkjs": "^0.10.2",
+    "@types/jsdom": "^30.0.0",
     "@nocobase/app-client": "^4.0.0-beta.3",
     "@nocobase/app-plugin-template-print": "0.0.2-beta.2",
-    "@nocobase/app-skills": "0.1.0-beta.49",
+    "@nocobase/app-skills": "0.1.0-beta.50",
     "@nocobase/app-testing": "0.1.0-beta.6",
     "@nocobase/app-websocket": "^0.1.0-beta.1",
     "@nocobase/dev-config": "0.1.0-beta.25",
@@ -144,9 +145,9 @@
     "@nocobase/app-plugin-authentication": "^2.0.0-beta.14",
     "@nocobase/app-plugin-authorization": "^1.0.0-beta.31",
     "@nocobase/app-plugin-database-explorer": "^1.0.0-beta.16",
-    "@nocobase/app-plugin-file": "^1.0.0-beta.26",
-    "@nocobase/app-plugin-foundation": "^0.1.0-beta.6",
+    "@nocobase/app-plugin-foundation": "^0.1.0-beta.7",
     "@nocobase/app-plugin-i18n": "^1.0.0-beta.18",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.26",
     "@nocobase/app-plugin-knowledge": "^0.1.0-beta.12",
     "@nocobase/app-plugin-mail": "^1.0.0-beta.17",
     "@nocobase/app-plugin-notification": "^2.0.0-beta.0",
@@ -160,16 +161,16 @@
     "@nocobase/db-sqlite": "^0.1.0-beta.6",
     "@nocobase/service-provider": "^0.0.2-beta.2",
     "@nocobase/snowflake": "^1.0.0-beta.4",
-    "@nocobase/app-plugin-authz-default-access": "^1.0.0-beta.15",
     "@nocobase/app-plugin-authz-sharing-rules": "^1.0.0-beta.15",
+    "@nocobase/app-plugin-authz-default-access": "^1.0.0-beta.15",
     "@nocobase/app-plugin-authz-restriction-rules": "^1.0.0-beta.14",
     "@nocobase/authorization": "^1.0.0-beta.15",
     "@nocobase/queue": "^0.1.0-beta.9",
     "@nocobase/jobs": "^0.1.0-beta.4",
     "@nocobase/lifecycle": "^0.1.0-beta.3",
     "@nocobase/i18n": "^2.0.0-beta.1",
-    "@nocobase/caching": "^0.1.0-beta.3",
     "@nocobase/repository-input": "^0.1.0-beta.3",
+    "@nocobase/caching": "^0.1.0-beta.3",
     "@nocobase/app-cli": "^1.0.0-beta.27",
     "@nocobase/realtime": "^0.1.0-beta.3"
   },

package/tests/client/account-permissions.test.tsx

@@ -0,0 +1,174 @@
+import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
+import { authorizationClientToken } from '@nocobase/app-plugin-authorization/client';
+import { authorizationToken } from '@nocobase/app-plugin-authorization/server';
+import { DEFAULT_ADMIN_CREDENTIALS } from '@nocobase/app-plugin-authentication/testing';
+import { act, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { ClientRoute } from '../../client/routing/client-route.js';
+import { useRouteNavigation } from '../../client/routing/route-navigation.js';
+import { renderAuthenticatedClient } from '../helpers/authenticated-client.js';
+
+const member = {
+  email: 'member@example.test',
+  password: 'test-member-password',
+};
+const routes: AppClientRegisteredRoute[] = ['apps', 'users'].map((name) => ({
+  id: name,
+  name,
+  path: `/${name}`,
+  auth: 'required',
+  authz: { resource: { type: 'page', id: name }, action: 'access' },
+  packageName: 'test',
+  source: 'application',
+  navigation: { title: name },
+  componentLoader: async () => ({ default: () => <div>{name} content</div> }),
+}));
+const grants = (full: boolean) =>
+  (full ? ['apps', 'users'] : ['apps']).map((id) => ({
+    resource: { type: 'page', id },
+    actions: [{ action: 'access' }],
+  }));
+function Menu() {
+  const { items, loading } = useRouteNavigation(routes);
+  return (
+    <nav aria-label='Pages'>
+      {loading
+        ? 'Checking'
+        : items.map(({ route }) => <span key={route.id}>{route.name}</span>)}
+    </nav>
+  );
+}
+function setup(options: Parameters<typeof renderAuthenticatedClient>[1] = {}) {
+  return renderAuthenticatedClient(
+    <>
+      <Menu />
+      <ClientRoute route={routes[1]} />
+    </>,
+    {
+      member: true,
+      grants: grants(true),
+      namespaces: { test: { apps: 'apps', users: 'users' } },
+      ...options,
+    },
+  );
+}
+async function expectMenu(full: boolean) {
+  // Realtime permission events may invalidate the snapshot again during a refresh.
+  // Read and assert both surfaces together, rather than retaining a detached node from findByText().
+  await waitFor(() => {
+    expect(screen.getByRole('navigation', { name: 'Pages' }).textContent).toBe(
+      full ? 'appsusers' : 'apps',
+    );
+    if (full) expect(screen.getByText('users content')).toBeVisible();
+    else {
+      expect(screen.getByText('Access denied')).toBeVisible();
+      expect(screen.queryByText('users content')).not.toBeInTheDocument();
+    }
+  });
+}
+async function changePermissions(
+  view: Awaited<ReturnType<typeof setup>>,
+  full: boolean,
+) {
+  await view.server.application.container
+    .resolve(authorizationToken)
+    .permissionSets.update('test-access', {
+      key: 'test-access',
+      grants: grants(full),
+    });
+}
+function invalidate(view: Awaited<ReturnType<typeof setup>>) {
+  act(() => view.app.container.resolve(authorizationClientToken).invalidate());
+}
+
+describe('account permission changes without a browser reload', () => {
+  it('updates menus and route guards when signing in as admin, member and admin again', async () => {
+    const view = await setup({ grants: grants(false) });
+    await expectMenu(false);
+    await view.signInAs(DEFAULT_ADMIN_CREDENTIALS);
+    await expectMenu(true);
+    await view.signInAs(member);
+    await expectMenu(false);
+    await view.signInAs(DEFAULT_ADMIN_CREDENTIALS);
+    await expectMenu(true);
+  });
+  it('clears permissions on logout and same-user re-login with a new session', async () => {
+    const view = await setup();
+    await expectMenu(true);
+    const firstSession = view.identity().session!.session.id;
+    await act(async () => {
+      await view.identity().client.signOut();
+      await view.identity().refresh();
+    });
+    await waitFor(() => expect(view.identity().session).toBeNull());
+    expect(await screen.findByText('Access denied')).toBeVisible();
+    expect(
+      screen.getByRole('navigation', { name: 'Pages' }),
+    ).toBeEmptyDOMElement();
+    await changePermissions(view, false);
+    await view.signInAs(member);
+    expect(view.identity().session!.session.id).not.toBe(firstSession);
+    await expectMenu(false);
+  });
+  it('revokes and restores a mounted menu and page after persisted permission changes', async () => {
+    const view = await setup();
+    await expectMenu(true);
+    await changePermissions(view, false);
+    invalidate(view);
+    expect(screen.queryByText('users content')).not.toBeInTheDocument();
+    await expectMenu(false);
+    await changePermissions(view, true);
+    invalidate(view);
+    await expectMenu(true);
+  });
+  it('hides previously allowed pages on network failure and recovers on retry', async () => {
+    let offline = false;
+    const view = await setup({
+      beforeRequest(request) {
+        if (offline && request.url.endsWith('/authorization/permissions'))
+          throw new TypeError('Failed to fetch');
+      },
+    });
+    await expectMenu(true);
+    offline = true;
+    invalidate(view);
+    await waitFor(() =>
+      expect(
+        screen.getByRole('navigation', { name: 'Pages' }),
+      ).toBeEmptyDOMElement(),
+    );
+    expect(await screen.findByText('Access denied')).toBeVisible();
+    expect(screen.queryByText('users content')).not.toBeInTheDocument();
+    offline = false;
+    invalidate(view);
+    await expectMenu(true);
+  });
+  it('ignores an old permissive response after a new session has fewer permissions', async () => {
+    const old = Promise.withResolvers<void>();
+    const received = Promise.withResolvers<void>();
+    let held = false;
+    const view = await setup({
+      afterResponse(request) {
+        // Only delay delivery: the response itself is produced by the real permission service.
+        if (!held && request.url.endsWith('/authorization/permissions')) {
+          held = true;
+          received.resolve();
+          return old.promise;
+        }
+      },
+    });
+    try {
+      await received.promise;
+      await changePermissions(view, false);
+      await view.signInAs(member);
+      await expectMenu(false);
+      await act(async () => {
+        old.resolve();
+        await old.promise;
+      });
+      await expectMenu(false);
+    } finally {
+      old.resolve();
+    }
+  });
+});

package/tests/{components → client}/app-layout-routes.test.tsx

@@ -1,12 +1,9 @@
 import { usePageBreadcrumb } from '@nocobase/app-client';
 import type { AppClientRegisteredRoute } from '@nocobase/app-client/plugins';
-import {
-  TestI18nProvider,
-  createTestI18nRuntime,
-} from '@nocobase/i18n/testing';
-import { render, screen, within } from '@testing-library/react';
-import type { ReactElement, ReactNode } from 'react';
-import { MemoryRouter, Route, Routes } from 'react-router';
+import { renderWithApp, answerApi } from '@nocobase/app-testing/client';
+import { screen, within } from '@testing-library/react';
+import type { ReactElement } from 'react';
+import { Route, Routes } from 'react-router';
 import { afterEach, beforeEach, expect, it, vi } from 'vitest';
 
 import { AppLayout } from '../../client/layouts/app-layout.js';
@@ -15,28 +12,8 @@ import {
   SidebarPreferenceProvider,
 } from '../../client/layouts/use-sidebar-preference.js';
 import enUS from '../../client/locales/en-US.js';
+import packageMetadata from '../../package.json' with { type: 'json' };
 
-// Breadcrumb titles are route data, not keys any namespace owns: the trail translates each through its package's
-// namespace with the title itself as `defaultValue`, so the runtime is not strict.
-const runtime = await createTestI18nRuntime({
-  application: { namespace: '@nocobase/app-template-default', resources: enUS },
-  strict: false,
-});
-
-function I18n({ children }: { readonly children: ReactNode }) {
-  return <TestI18nProvider runtime={runtime}>{children}</TestI18nProvider>;
-}
-
-vi.mock('@nocobase/app-plugin-i18n/client', async (importOriginal) => ({
-  ...(await importOriginal<
-    typeof import('@nocobase/app-plugin-i18n/client')
-  >()),
-  useSyncServerLocale: () => {},
-}));
-vi.mock('@nocobase/app-client', async (original) => ({
-  ...(await original<typeof import('@nocobase/app-client')>()),
-  useClientApplication: () => ({ runtime: {} }),
-}));
 vi.mock('../../client/routing/route-navigation.js', async (original) => ({
   ...(await original<
     typeof import('../../client/routing/route-navigation.js')
@@ -90,25 +67,31 @@ function OrderPage(): ReactElement {
   return <h1>Order #42</h1>;
 }
 
-function renderLayout(page: ReactElement): HTMLElement {
+async function renderLayout(page: ReactElement): Promise<HTMLElement> {
   const sidebarPreference = createAppSidebarPreferenceStore('/test-app');
-  render(
+  await renderWithApp(
     <SidebarPreferenceProvider value={sidebarPreference}>
-      <MemoryRouter initialEntries={['/orders/42']}>
-        <Routes>
-          <Route element={<AppLayout routes={routes} />}>
-            <Route path='/orders/:id' element={page} />
-          </Route>
-        </Routes>
-      </MemoryRouter>
+      <Routes>
+        <Route element={<AppLayout routes={routes} />}>
+          <Route path='/orders/:id' element={page} />
+        </Route>
+      </Routes>
     </SidebarPreferenceProvider>,
-    { wrapper: I18n },
+    {
+      route: '/orders/42',
+      namespace: packageMetadata.name,
+      namespaces: {
+        [packageMetadata.name]: enUS,
+        test: { Orders: 'Orders', Detail: 'Detail' },
+      },
+      fetch: answerApi(() => ({ data: {} })),
+    },
   );
   return screen.getByRole('banner');
 }
 
-it('shows the route trail of a nested page in its header', () => {
-  const header = renderLayout(<h1>Detail page</h1>);
+it('shows the route trail of a nested page in its header', async () => {
+  const header = await renderLayout(<h1>Detail page</h1>);
   const trail = within(header).getByRole('navigation', { name: 'Breadcrumb' });
   expect(within(trail).getByRole('link', { name: 'Orders' })).toHaveAttribute(
     'href',
@@ -124,8 +107,8 @@ it('shows the route trail of a nested page in its header', () => {
   ).toHaveLength(1);
 });
 
-it('shows the trail a page declares, with its record names, in place of the route trail', () => {
-  const header = renderLayout(<OrderPage />);
+it('shows the trail a page declares, with its record names, in place of the route trail', async () => {
+  const header = await renderLayout(<OrderPage />);
   const trail = within(header).getByRole('navigation', { name: 'Breadcrumb' });
   expect(within(trail).getByRole('link', { name: 'Orders' })).toHaveAttribute(
     'href',

package/tests/{logic → client}/app-locale-coverage.test.ts

@@ -1,15 +1,12 @@
-// @vitest-environment node
-
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { describe, expect, it } from 'vitest';
 
 import enUS from '../../client/locales/en-US.ts';
 import zhCN from '../../client/locales/zh-CN.ts';
 
-const clientDirectory = fileURLToPath(new URL('../../client', import.meta.url));
+const clientDirectory = path.resolve(import.meta.dirname, '../../client');
 
 /** Every addressable key of a locale, as the dot-separated path `t()` is called with. */
 function translationKeys(

package/tests/{logic → client}/client-plugin-registry.test.ts

@@ -1,14 +1,11 @@
-// @vitest-environment node
-
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { describe, expect, it } from 'vitest';
 
 import clientPlugins from '../../client/plugins.js';
 
-const appRoot = fileURLToPath(new URL('../..', import.meta.url));
+const appRoot = path.resolve(import.meta.dirname, '../..');
 
 interface AppPackageJson {
   readonly dependencies?: Record<string, string>;

package/tests/{logic → client}/client-route-recovery.test.tsx

@@ -2,14 +2,30 @@ import type {
   AppClientRegisteredRoute,
   AppClientRouteComponentModule,
 } from '@nocobase/app-client/plugins';
-import { act, render, screen } from '@testing-library/react';
-import { describe, expect, it, vi } from 'vitest';
+import { act, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
 
 import { ClientRoute } from '../../client/routing/client-route.tsx';
 
-vi.mock('@nocobase/app-plugin-authorization/client', () => ({
-  useCan: () => ({ can: true, isPending: false }),
-}));
+import { renderWithApp } from '@nocobase/app-testing/client';
+import { apiClientToken } from '@nocobase/app-client';
+import {
+  AuthorizationClient,
+  authorizationClientToken,
+} from '@nocobase/app-plugin-authorization/client';
+import packageMetadata from '../../package.json' with { type: 'json' };
+import enUS from '../../client/locales/en-US.js';
+
+const options = {
+  namespace: packageMetadata.name,
+  namespaces: { [packageMetadata.name]: enUS },
+  services(app: import('@nocobase/app-client').ClientApplication) {
+    app.container.singleton(
+      authorizationClientToken,
+      (resolver) => new AuthorizationClient(resolver.resolve(apiClientToken)),
+    );
+  },
+};
 
 const route: AppClientRegisteredRoute = {
   id: 'recoverable',
@@ -34,7 +50,10 @@ const healthyModule: AppClientRouteComponentModule = {
 
 describe('client route loading recovery', () => {
   it('clears a previous failure when the same mounted route loads successfully', async () => {
-    const { rerender } = render(<ClientRoute route={route} />);
+    const { rerender } = await renderWithApp(
+      <ClientRoute route={route} />,
+      options,
+    );
     expect(
       await screen.findByText('Unable to load page', {}, ROUTE_LOAD_TIMEOUT),
     ).toBeVisible();
@@ -58,8 +77,9 @@ describe('client route loading recovery', () => {
         rejectLoad = reject;
       },
     );
-    const { rerender } = render(
+    const { rerender } = await renderWithApp(
       <ClientRoute route={{ ...route, componentLoader: () => pending }} />,
+      options,
     );
     rerender(
       <ClientRoute

package/tests/{components → client}/header-hover.test.tsx

@@ -1,21 +1,11 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { afterEach, beforeEach, expect, it, vi } from 'vitest';
 import { AppThemeProvider } from '../../client/theme/theme-provider';
 import { ThemeSettings } from '../../client/theme/theme-settings';
 import { UserMenu } from '../../client/layouts/components/user-menu';
 
-// Session requests belong to the authentication tests.
-vi.mock('@nocobase/app-plugin-authentication/client', () => ({
-  useAuthentication: () => ({
-    session: { user: { id: 'operator', name: 'Operator' } },
-    isPending: false,
-  }),
-}));
-// Language selection has its own integration tests with the real i18n runtime.
-vi.mock('../../client/layouts/components/language-switcher.js', () => ({
-  LanguageSwitcher: () => null,
-}));
+import { renderAuthenticatedClient } from '../helpers/authenticated-client.js';
 
 beforeEach(() => {
   // jsdom does not implement the media queries used by the real theme provider.
@@ -43,7 +33,7 @@ it.each(panels)(
   'opens and closes %s on hover',
   async (label, Component, role) => {
     const user = userEvent.setup();
-    render(
+    await renderAuthenticatedClient(
       <AppThemeProvider>
         <Component />
       </AppThemeProvider>,
@@ -70,7 +60,7 @@ it.each(panels)(
   'opens %s by keyboard and closes with Escape',
   async (label, Component, role) => {
     const user = userEvent.setup();
-    render(
+    await renderAuthenticatedClient(
       <AppThemeProvider>
         <Component />
       </AppThemeProvider>,