create-react-admin-template 0.0.0-stage → 0.1.0

package/template/tests/integration/layout/AppHeader.test.tsx

@@ -0,0 +1,182 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  RouterProvider,
+  createMemoryHistory,
+  createRouter,
+} from '@tanstack/react-router'
+import { LocaleProvider } from '@/locale'
+import { objRouteTree } from '@/router/config'
+import '@/styles/index.css'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { page, userEvent } from 'vitest/browser'
+import { useUiPreferenceStore } from '@/stores/uiPreferenceStore'
+import { ThemeProvider } from '@/context/ThemeProvider'
+
+const nOriginalViewportWidth = window.innerWidth
+const nOriginalViewportHeight = window.innerHeight
+
+beforeEach(() => {
+  localStorage.removeItem('enterprise-admin.ui-preferences')
+  useUiPreferenceStore.setState({
+    bIsSidebarOpen: true,
+    nSidebarWidth: 256,
+  })
+})
+
+afterEach(async () => {
+  await page.viewport(nOriginalViewportWidth, nOriginalViewportHeight)
+})
+
+function fnCreateTestRouter() {
+  const objQueryClient = new QueryClient()
+  const objRouter = createRouter({
+    routeTree: objRouteTree,
+    history: createMemoryHistory({ initialEntries: ['/dashboard'] }),
+    context: {
+      objQueryClient,
+      objAuth: {
+        fnHasPermission: () => true,
+        fnIsAuthenticated: () => true,
+      },
+    },
+  })
+
+  return { objQueryClient, objRouter }
+}
+
+describe('AppHeader command search', () => {
+  it('exposes one theme entry and one user entry', async () => {
+    const { objQueryClient, objRouter } = fnCreateTestRouter()
+
+    await objRouter.load()
+
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <ThemeProvider>
+          <RouterProvider router={objRouter} />
+        </ThemeProvider>
+      </QueryClientProvider>
+    )
+
+    await expect
+      .element(objScreen.getByRole('button', { name: '切换主题' }))
+      .toBeVisible()
+    await expect
+      .element(objScreen.getByRole('button', { name: '用户菜单' }))
+      .toBeVisible()
+    expect(document.querySelectorAll('[aria-label="用户菜单"]')).toHaveLength(1)
+    expect(document.querySelector('[aria-label="界面设置"]')).toBeNull()
+  })
+
+  it('hides the duplicate header trigger when the desktop sidebar collapses', async () => {
+    await page.viewport(1280, nOriginalViewportHeight)
+
+    const { objQueryClient, objRouter } = fnCreateTestRouter()
+
+    await objRouter.load()
+
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <ThemeProvider>
+          <RouterProvider router={objRouter} />
+        </ThemeProvider>
+      </QueryClientProvider>
+    )
+    const objHeaderTrigger = document.querySelector<HTMLButtonElement>(
+      'header [data-slot="sidebar-trigger"]'
+    )
+    const objDesktopSidebar = document.querySelector<HTMLElement>(
+      '[data-slot="sidebar"][data-state]'
+    )
+    const objSidebarContainer = document.querySelector<HTMLElement>(
+      '[data-slot="sidebar-container"]'
+    )
+
+    expect(objHeaderTrigger).not.toBeNull()
+    expect(objDesktopSidebar).not.toBeNull()
+    expect(objSidebarContainer).not.toBeNull()
+    expect(getComputedStyle(objDesktopSidebar!).display).toBe('block')
+    expect(getComputedStyle(objSidebarContainer!).display).toBe('flex')
+
+    await userEvent.click(objHeaderTrigger!)
+
+    await expect
+      .poll(() =>
+        document.querySelector('header [data-slot="sidebar-trigger"]')
+      )
+      .toBeNull()
+    expect(document.querySelector('header [data-slot="separator"]')).toBeNull()
+    expect(objDesktopSidebar!.dataset.state).toBe('collapsed')
+    expect(getComputedStyle(objDesktopSidebar!).display).toBe('block')
+    expect(getComputedStyle(objSidebarContainer!).display).toBe('flex')
+    expect(objSidebarContainer!.getBoundingClientRect().width).toBeGreaterThan(
+      0
+    )
+    await expect
+      .element(objScreen.getByRole('button', { name: '展开侧边栏' }))
+      .toBeVisible()
+  })
+
+  it('opens a command dialog, filters routes, and navigates', async () => {
+    const { objQueryClient, objRouter } = fnCreateTestRouter()
+
+    await objRouter.load()
+
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <ThemeProvider>
+          <RouterProvider router={objRouter} />
+        </ThemeProvider>
+      </QueryClientProvider>
+    )
+
+    await userEvent.click(objScreen.getByRole('button', { name: '搜索菜单' }))
+
+    const objDialog = objScreen.getByRole('dialog')
+    const objSearchInput = objScreen.getByRole('combobox', {
+      name: '搜索页面或命令',
+    })
+
+    await expect.element(objDialog).toBeVisible()
+    await expect.element(objDialog).toHaveTextContent('工作台')
+    await expect.element(objDialog).not.toHaveTextContent('系统页面')
+    await expect.element(objSearchInput).toHaveFocus()
+
+    await userEvent.type(objSearchInput, '首页')
+
+    await expect.element(objDialog).toHaveTextContent('首页')
+
+    await userEvent.click(objScreen.getByRole('option', { name: /首页/ }))
+
+    await expect
+      .poll(() => objRouter.state.location.pathname)
+      .toBe('/dashboard')
+  })
+
+  it('resolves route metadata through the active locale', async () => {
+    const { objQueryClient, objRouter } = fnCreateTestRouter()
+
+    await objRouter.load()
+
+    const objScreen = await render(
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <QueryClientProvider client={objQueryClient}>
+          <ThemeProvider>
+            <RouterProvider router={objRouter} />
+          </ThemeProvider>
+        </QueryClientProvider>
+      </LocaleProvider>
+    )
+
+    await userEvent.click(
+      objScreen.getByRole('button', { name: 'Search menu' })
+    )
+    const objDialog = objScreen.getByRole('dialog')
+
+    await expect.element(objDialog).toHaveTextContent('Workspace')
+    await expect.element(objDialog).toHaveTextContent('Home')
+    await expect.element(objDialog).toHaveTextContent('Live demos')
+    await expect.element(objDialog).toHaveTextContent('Table scenarios')
+  })
+})

package/template/tests/integration/layout/AppSidebar.test.tsx

@@ -0,0 +1,121 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  RouterProvider,
+  createMemoryHistory,
+  createRouter,
+} from '@tanstack/react-router'
+import { objRouteTree } from '@/router/config'
+import '@/styles/index.css'
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { page } from 'vitest/browser'
+import { useUiPreferenceStore } from '@/stores/uiPreferenceStore'
+import { ThemeProvider } from '@/context/ThemeProvider'
+
+const nOriginalInnerWidth = window.innerWidth
+const nOriginalInnerHeight = window.innerHeight
+
+beforeAll(async () => {
+  await page.viewport(1024, nOriginalInnerHeight)
+  Object.defineProperty(window, 'innerWidth', {
+    configurable: true,
+    value: 1024,
+  })
+})
+
+beforeEach(() => {
+  localStorage.removeItem('enterprise-admin.ui-preferences')
+  useUiPreferenceStore.setState({
+    bIsSidebarOpen: true,
+    nSidebarWidth: 256,
+  })
+})
+
+afterAll(async () => {
+  Object.defineProperty(window, 'innerWidth', {
+    configurable: true,
+    value: nOriginalInnerWidth,
+  })
+  await page.viewport(nOriginalInnerWidth, nOriginalInnerHeight)
+})
+
+function fnCreateTestRouter() {
+  const objQueryClient = new QueryClient()
+  const objRouter = createRouter({
+    routeTree: objRouteTree,
+    history: createMemoryHistory({ initialEntries: ['/dashboard'] }),
+    context: {
+      objQueryClient,
+      objAuth: {
+        fnHasPermission: () => true,
+        fnIsAuthenticated: () => true,
+      },
+    },
+  })
+
+  return { objQueryClient, objRouter }
+}
+
+describe('AppSidebar resize handle', () => {
+  it('resizes with the keyboard without collapsing the sidebar', async () => {
+    const { objQueryClient, objRouter } = fnCreateTestRouter()
+
+    await objRouter.load()
+
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <ThemeProvider>
+          <RouterProvider router={objRouter} />
+        </ThemeProvider>
+      </QueryClientProvider>
+    )
+    const objResizeHandle = objScreen.getByRole('separator', {
+      name: '调整侧边栏宽度',
+    })
+    const objResizeHandleElement = document.querySelector<HTMLElement>(
+      "[data-slot='sidebar-rail']"
+    )!
+    const objSidebarContainer = document.querySelector<HTMLElement>(
+      "[data-slot='sidebar-container']"
+    )!
+    const objHeader = document.querySelector<HTMLElement>('header')!
+
+    expect(
+      Number.parseInt(getComputedStyle(objSidebarContainer).zIndex, 10)
+    ).toBeGreaterThan(Number.parseInt(getComputedStyle(objHeader).zIndex, 10))
+
+    await expect
+      .element(objResizeHandle)
+      .toHaveAttribute('aria-valuenow', '256')
+
+    objResizeHandleElement.dispatchEvent(
+      new MouseEvent('click', { bubbles: true })
+    )
+
+    expect(
+      document.querySelector<HTMLElement>("[data-slot='sidebar'][data-state]")
+        ?.dataset.state
+    ).toBe('expanded')
+
+    objResizeHandleElement.dispatchEvent(
+      new KeyboardEvent('keydown', { bubbles: true, key: 'ArrowRight' })
+    )
+    await expect
+      .element(objResizeHandle)
+      .toHaveAttribute('aria-valuenow', '264')
+
+    objResizeHandleElement.dispatchEvent(
+      new KeyboardEvent('keydown', { bubbles: true, key: 'End' })
+    )
+    await expect
+      .element(objResizeHandle)
+      .toHaveAttribute('aria-valuenow', '384')
+
+    objResizeHandleElement.dispatchEvent(
+      new KeyboardEvent('keydown', { bubbles: true, key: 'Home' })
+    )
+    await expect
+      .element(objResizeHandle)
+      .toHaveAttribute('aria-valuenow', '208')
+  })
+})

package/template/tests/integration/router/config.test.ts

@@ -0,0 +1,123 @@
+import { QueryClient } from '@tanstack/react-query'
+import { createMemoryHistory, createRouter } from '@tanstack/react-router'
+import { objRouteTree } from '@/router/config'
+import { describe, expect, it } from 'vitest'
+
+function fnCreateTestRouter(strPath: string, bIsAuthenticated: boolean) {
+  return createRouter({
+    routeTree: objRouteTree,
+    history: createMemoryHistory({ initialEntries: [strPath] }),
+    context: {
+      objQueryClient: new QueryClient(),
+      objAuth: {
+        fnHasPermission: () => true,
+        fnIsAuthenticated: () => bIsAuthenticated,
+      },
+    },
+  })
+}
+
+describe('route tree authentication boundaries', () => {
+  it('separates browser rendering errors from the explicit HTTP 500 page', () => {
+    const objRouter = fnCreateTestRouter('/dashboard', true)
+
+    expect(objRouter.routesById.__root__.options.errorComponent).not.toBe(
+      objRouter.routesById['/errors/500'].options.component
+    )
+  })
+
+  it('exposes the scaffold home and live demo navigation metadata', () => {
+    const objRouter = fnCreateTestRouter('/dashboard', true)
+    const objHomeStaticData =
+      objRouter.routesById['/_app/dashboard'].options.staticData
+    const objErrorsStaticData =
+      objRouter.routesById['/errors'].options.staticData
+    const objShowcaseStaticData =
+      objRouter.routesById['/_app/showcase'].options.staticData
+
+    expect(objHomeStaticData).toMatchObject({
+      strTitle: 'route.home.title',
+      strNavigationGroup: 'route.group.workspace',
+      nNavigationGroupOrder: 10,
+      nNavigationOrder: 10,
+    })
+    expect(objHomeStaticData?.Icon).toBeDefined()
+    expect(objShowcaseStaticData).toMatchObject({
+      strTitle: 'route.showcase.title',
+      strNavigationGroup: 'route.group.showcase',
+      nNavigationGroupOrder: 20,
+    })
+    expect(objShowcaseStaticData?.Icon).toBeDefined()
+    expect(
+      Object.keys(objRouter.routesById)
+        .filter((strRouteId) => strRouteId.startsWith('/_app/'))
+        .sort()
+    ).toEqual([
+      '/_app/dashboard',
+      '/_app/showcase',
+      '/_app/showcase/',
+      '/_app/showcase/access',
+      '/_app/showcase/feedback',
+      '/_app/showcase/files',
+      '/_app/showcase/form',
+      '/_app/showcase/metadata',
+      '/_app/showcase/table',
+    ])
+    expect(objErrorsStaticData).toMatchObject({
+      strTitle: 'route.error.title',
+      bShowInSidebar: false,
+    })
+    expect(objErrorsStaticData?.Icon).toBeDefined()
+  })
+
+  it('sends anonymous users to sign-in and preserves the target', async () => {
+    const objRouter = fnCreateTestRouter('/dashboard?view=compact', false)
+
+    await objRouter.load()
+
+    expect(objRouter.state.location.pathname).toBe('/sign-in')
+    expect(objRouter.state.location.search).toEqual({
+      redirect: '/dashboard?view=compact',
+    })
+  })
+
+  it('also protects system error routes from anonymous access', async () => {
+    const objRouter = fnCreateTestRouter('/errors/403', false)
+
+    await objRouter.load()
+
+    expect(objRouter.state.location.pathname).toBe('/sign-in')
+    expect(objRouter.state.location.search).toEqual({
+      redirect: '/errors/403',
+    })
+  })
+
+  it('sends authenticated users away from guest routes', async () => {
+    const objRouter = fnCreateTestRouter('/sign-in', true)
+
+    await objRouter.load()
+
+    expect(objRouter.state.location.pathname).toBe('/dashboard')
+  })
+
+  it('does not expose the registration page in the admin application', async () => {
+    const objRouter = fnCreateTestRouter('/sign-up', false)
+
+    await objRouter.load()
+
+    expect(objRouter.state.location.pathname).toBe('/sign-in')
+  })
+
+  it('uses authentication state for the root entry route', async () => {
+    const objAnonymousRouter = fnCreateTestRouter('/', false)
+    const objAuthenticatedRouter = fnCreateTestRouter('/', true)
+
+    await Promise.all([
+      objAnonymousRouter.load(),
+      objAuthenticatedRouter.load(),
+    ])
+
+    expect(objAnonymousRouter.state.location.pathname).toBe('/sign-in')
+    expect(objAuthenticatedRouter.state.location.pathname).toBe('/dashboard')
+  })
+})

package/template/tests/integration/router/interceptors.test.ts

@@ -0,0 +1,100 @@
+import { isRedirect } from '@tanstack/react-router'
+import { fnInterceptRoute } from '@/router/interceptors'
+import { describe, expect, it } from 'vitest'
+import { strDefaultAuthenticatedPath } from '@/lib/navigationRedirect'
+
+function fnCreateRouteOptions(
+  bIsAuthenticated: boolean,
+  strHref = '/',
+  bHasPermission = true
+) {
+  return {
+    context: {
+      objAuth: {
+        fnHasPermission: () => bHasPermission,
+        fnIsAuthenticated: () => bIsAuthenticated,
+      },
+    },
+    location: { href: strHref },
+  }
+}
+
+function fnCaptureRedirect(fnAction: () => void) {
+  try {
+    fnAction()
+  } catch (objError) {
+    if (isRedirect(objError)) {
+      return objError
+    }
+
+    throw objError
+  }
+
+  throw new Error('Expected the interceptor to redirect')
+}
+
+describe('route interceptor', () => {
+  it('redirects anonymous users to sign-in with their current location', () => {
+    const objResult = fnCaptureRedirect(() =>
+      fnInterceptRoute(
+        fnCreateRouteOptions(false, '/users?page=2#results'),
+        'authenticated'
+      )
+    )
+
+    expect(objResult.options).toMatchObject({
+      to: '/sign-in',
+      search: { redirect: '/users?page=2#results' },
+      replace: true,
+    })
+  })
+
+  it('allows authenticated users into protected routes', () => {
+    expect(() =>
+      fnInterceptRoute(
+        fnCreateRouteOptions(true, '/dashboard'),
+        'authenticated'
+      )
+    ).not.toThrow()
+  })
+
+  it('redirects authenticated users without the required permission', () => {
+    const objResult = fnCaptureRedirect(() =>
+      fnInterceptRoute(
+        fnCreateRouteOptions(true, '/feature/items', false),
+        'authenticated',
+        'feature:read'
+      )
+    )
+
+    expect(objResult.options).toMatchObject({
+      to: '/errors/403',
+      replace: true,
+    })
+  })
+
+  it('redirects authenticated users away from guest routes', () => {
+    const objResult = fnCaptureRedirect(() =>
+      fnInterceptRoute(fnCreateRouteOptions(true, '/sign-in'), 'guest')
+    )
+
+    expect(objResult.options).toMatchObject({
+      to: strDefaultAuthenticatedPath,
+      replace: true,
+    })
+  })
+
+  it('uses authentication state for the entry route', () => {
+    const objAnonymousResult = fnCaptureRedirect(() =>
+      fnInterceptRoute(fnCreateRouteOptions(false), 'entry')
+    )
+    const objAuthenticatedResult = fnCaptureRedirect(() =>
+      fnInterceptRoute(fnCreateRouteOptions(true), 'entry')
+    )
+
+    expect(objAnonymousResult.options).toMatchObject({ to: '/sign-in' })
+    expect(objAuthenticatedResult.options).toMatchObject({
+      to: strDefaultAuthenticatedPath,
+    })
+  })
+})

package/template/tests/setup/accessibility.ts

@@ -0,0 +1,25 @@
+import axe from 'axe-core'
+import { expect } from 'vitest'
+
+function fnFormatAccessibilityViolations(arrViolations: axe.Result[]): string {
+  return arrViolations
+    .map((objViolation) => {
+      const strTargets = objViolation.nodes
+        .flatMap((objNode) => objNode.target)
+        .join(', ')
+
+      return `${objViolation.id}: ${objViolation.help}\n${strTargets}`
+    })
+    .join('\n\n')
+}
+
+/** 在真实浏览器中执行 axe，并输出可定位到具体节点的失败信息。 */
+export async function fnExpectNoAccessibilityViolations(
+  objContext: axe.ElementContext
+) {
+  const { violations: arrViolations } = await axe.run(objContext)
+
+  expect(arrViolations, fnFormatAccessibilityViolations(arrViolations)).toEqual(
+    []
+  )
+}

package/template/tests/setup/runtimeConfig.ts

@@ -0,0 +1,3 @@
+import { fnLoadRuntimeConfig } from '@/config/runtimeConfig'
+
+await fnLoadRuntimeConfig()

package/template/tests/unit/api/ApiError.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { ApiError, fnIsApiError } from '@/api/ApiError'
+
+describe('ApiError', () => {
+  it('exposes only the stable application error contract', () => {
+    const objError = new ApiError({
+      bRetriable: true,
+      nStatus: 503,
+      strCode: 'SERVICE_UNAVAILABLE',
+      strKind: 'http',
+      strMessage: '服务暂不可用',
+      strRequestId: 'request-1',
+    })
+
+    expect(fnIsApiError(objError)).toBe(true)
+    expect(objError).toMatchObject({
+      bRetriable: true,
+      message: '服务暂不可用',
+      nStatus: 503,
+      strCode: 'SERVICE_UNAVAILABLE',
+      strKind: 'http',
+      strRequestId: 'request-1',
+    })
+  })
+})