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

package/template/tests/unit/files/files.test.ts

@@ -0,0 +1,112 @@
+import {
+  fnDownloadFile,
+  fnParseDownloadFileName,
+  fnSanitizeFileName,
+  fnValidateFiles,
+} from '@/files'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('file validation and filename safety', () => {
+  it('accepts a configured extension when the browser omits MIME', () => {
+    const objFile = new File(['report'], '季度报告.PDF')
+
+    const objResult = fnValidateFiles([objFile], {
+      arrAcceptedExtensions: ['.pdf'],
+      arrAcceptedMimeTypes: ['application/pdf'],
+      nMaxBytes: 1024,
+      nMaxFiles: 1,
+    })
+
+    expect(objResult.arrAcceptedFiles).toEqual([objFile])
+    expect(objResult.arrIssues).toEqual([])
+  })
+
+  it('reports collection, empty, size and type issues without reading content', () => {
+    const objEmptyFile = new File([], 'empty.txt', { type: 'text/plain' })
+    const objLargeFile = new File(['12345'], 'large.txt', {
+      type: 'text/plain',
+    })
+    const objWrongType = new File(['x'], 'avatar.svg', {
+      type: 'image/svg+xml',
+    })
+
+    expect(
+      fnValidateFiles([objEmptyFile, objLargeFile], { nMaxFiles: 1 })
+        .arrIssues[0]?.strCode
+    ).toBe('TOO_MANY_FILES')
+    expect(fnValidateFiles([objEmptyFile]).arrIssues[0]?.strCode).toBe(
+      'EMPTY_FILE'
+    )
+    expect(
+      fnValidateFiles([objLargeFile], { nMaxBytes: 4 }).arrIssues[0]?.strCode
+    ).toBe('FILE_TOO_LARGE')
+    expect(
+      fnValidateFiles([objWrongType], {
+        arrAcceptedMimeTypes: ['image/png'],
+      }).arrIssues[0]?.strCode
+    ).toBe('FILE_TYPE_NOT_ALLOWED')
+  })
+
+  it('prefers encoded filenames and removes header-supplied paths', () => {
+    expect(
+      fnParseDownloadFileName(
+        "attachment; filename=legacy.pdf; filename*=UTF-8''%E6%8A%A5%E5%91%8A.pdf"
+      )
+    ).toBe('报告.pdf')
+    expect(
+      fnParseDownloadFileName('attachment; filename="../secret.csv"')
+    ).toBe('secret.csv')
+    expect(fnSanitizeFileName('..')).toBe('download')
+  })
+})
+
+describe('file download safety', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('rejects JSON error blobs instead of saving them as files', async () => {
+    await expect(
+      fnDownloadFile({
+        fnRequest: async () => ({
+          objBlob: new Blob(['{"message":"denied"}'], {
+            type: 'application/json',
+          }),
+        }),
+      })
+    ).rejects.toMatchObject({ strCode: 'DOWNLOAD_ERROR_CONTENT' })
+  })
+
+  it('allows an explicitly attached JSON document', async () => {
+    vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:download')
+    vi.spyOn(URL, 'revokeObjectURL')
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(
+      () => undefined
+    )
+
+    await expect(
+      fnDownloadFile({
+        fnRequest: async () => ({
+          objBlob: new Blob(['{"version":1}'], {
+            type: 'application/json',
+          }),
+          strContentDisposition: 'attachment; filename=data.json',
+        }),
+      })
+    ).resolves.toBe('data.json')
+  })
+
+  it('enforces the memory cap before creating an object URL', async () => {
+    const fnCreateObjectUrl = vi.spyOn(URL, 'createObjectURL')
+
+    await expect(
+      fnDownloadFile({
+        fnRequest: async () => ({
+          objBlob: new Blob(['12345'], { type: 'application/octet-stream' }),
+        }),
+        nMaxBytes: 4,
+      })
+    ).rejects.toMatchObject({ strCode: 'DOWNLOAD_TOO_LARGE_FOR_MEMORY' })
+    expect(fnCreateObjectUrl).not.toHaveBeenCalled()
+  })
+})

package/template/tests/unit/lib/accessControl.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import type { IAuthUser } from '@/stores/types'
+import { fnHasPermission, fnHasPermissions } from '@/lib/accessControl'
+
+const objUser: IAuthUser = {
+  arrPermissions: ['feature:item:read'],
+  arrRoleCodes: ['auditor'],
+  strAccount: 'auditor@example.com',
+  strDisplayName: '审计员',
+  strId: 'user-1',
+  strRole: 'auditor',
+}
+
+describe('fnHasPermission', () => {
+  it('allows public capabilities without an authenticated user', () => {
+    expect(fnHasPermission(null)).toBe(true)
+  })
+
+  it('requires authentication for protected capabilities', () => {
+    expect(fnHasPermission(null, 'feature:item:read')).toBe(false)
+  })
+
+  it('matches explicit permissions and rejects missing permissions', () => {
+    expect(fnHasPermission(objUser, 'feature:item:read')).toBe(true)
+    expect(fnHasPermission(objUser, 'feature:item:write')).toBe(false)
+  })
+
+  it('supports the demo administrator wildcard', () => {
+    expect(
+      fnHasPermission(
+        { ...objUser, arrPermissions: ['*'] },
+        'feature:item:write'
+      )
+    ).toBe(true)
+  })
+})
+
+describe('fnHasPermissions', () => {
+  const objUserWithMultiplePermissions: IAuthUser = {
+    ...objUser,
+    arrPermissions: ['feature:item:read', 'feature:item:export'],
+  }
+
+  it('requires all permissions by default', () => {
+    expect(
+      fnHasPermissions(objUserWithMultiplePermissions, [
+        'feature:item:read',
+        'feature:item:export',
+      ])
+    ).toBe(true)
+    expect(
+      fnHasPermissions(objUserWithMultiplePermissions, [
+        'feature:item:read',
+        'feature:item:write',
+      ])
+    ).toBe(false)
+  })
+
+  it('supports any-match and an empty public requirement', () => {
+    expect(
+      fnHasPermissions(
+        objUserWithMultiplePermissions,
+        ['feature:item:write', 'feature:item:export'],
+        'any'
+      )
+    ).toBe(true)
+    expect(fnHasPermissions(null, [])).toBe(true)
+  })
+})

package/template/tests/unit/locale/locale.test.tsx

@@ -0,0 +1,90 @@
+import {
+  fnCreateLocaleFormatter,
+  fnDefineLocaleMessages,
+  LocaleProvider,
+  useLocale,
+  useLocaleMessages,
+} from '@/locale'
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+
+const objFeatureMessages = fnDefineLocaleMessages({
+  'en-US': { greeting: 'Welcome' },
+  'zh-CN': { greeting: '欢迎' },
+})
+
+function LocaleHarness() {
+  const objLocale = useLocale()
+  const objMessages = useLocaleMessages(objFeatureMessages)
+  return (
+    <div>
+      <span>{objMessages.fnTranslate('greeting')}</span>
+      <span>{objLocale.fnTranslateShared('common.retry')}</span>
+      <span>{objLocale.fnFormatPercent(0.125)}</span>
+    </div>
+  )
+}
+
+describe('locale formatter', () => {
+  it('formats date, time, number, percent and currency from one locale source', () => {
+    const objFormatter = fnCreateLocaleFormatter({
+      strLocale: 'en-US',
+      strTimeZone: 'UTC',
+    })
+    const nInstant = Date.UTC(2026, 0, 2, 15, 4, 5)
+
+    expect(objFormatter.fnFormatDate(nInstant)).toBe('01/02/2026')
+    expect(
+      objFormatter.fnFormatTime(nInstant, {
+        hour: '2-digit',
+        hourCycle: 'h23',
+        minute: '2-digit',
+      })
+    ).toBe('15:04')
+    expect(objFormatter.fnFormatNumber(1234.5)).toBe('1,234.5')
+    expect(objFormatter.fnFormatPercent(0.125)).toBe('13%')
+    expect(
+      objFormatter.fnFormatCurrency(1234.5, 'USD', {
+        minimumFractionDigits: 2,
+      })
+    ).toBe('$1,234.50')
+    expect(objFormatter.fnFormatNumber(Number.NaN)).toBe('-')
+    expect(objFormatter.fnCompare('2', '10')).toBeLessThan(0)
+  })
+
+  it('applies the configured IANA timezone to the same instant', () => {
+    const nInstant = Date.UTC(2026, 0, 1, 16)
+    const objUtcFormatter = fnCreateLocaleFormatter({
+      strLocale: 'zh-CN',
+      strTimeZone: 'UTC',
+    })
+    const objShanghaiFormatter = fnCreateLocaleFormatter({
+      strLocale: 'zh-CN',
+      strTimeZone: 'Asia/Shanghai',
+    })
+
+    expect(objUtcFormatter.fnFormatDate(nInstant)).toBe('2026/01/01')
+    expect(objShanghaiFormatter.fnFormatDate(nInstant)).toBe('2026/01/02')
+  })
+})
+
+describe('LocaleProvider', () => {
+  it('drives shared messages, Feature messages, formatting and document language', async () => {
+    const objScreen = await render(
+      <LocaleProvider
+        objSharedMessages={{
+          'en-US': { 'common.retry': 'Try again' },
+        }}
+        strLocale='en-US'
+        strTimeZone='UTC'
+      >
+        <LocaleHarness />
+      </LocaleProvider>
+    )
+
+    await expect.element(objScreen.getByText('Welcome')).toBeVisible()
+    await expect.element(objScreen.getByText('Try again')).toBeVisible()
+    await expect.element(objScreen.getByText('13%')).toBeVisible()
+    expect(document.documentElement.lang).toBe('en-US')
+  })
+})

package/template/tests/unit/observability/browser.test.ts

@@ -0,0 +1,48 @@
+import {
+  fnConfigureObservability,
+  fnStartGlobalErrorObservation,
+} from '@/observability'
+import { expect, it, vi } from 'vitest'
+
+it('observes browser errors until its lifecycle is stopped', () => {
+  const fnCaptureEvent = vi.fn()
+  fnConfigureObservability({
+    bEnabled: true,
+    objAdapter: { fnCaptureEvent },
+    objRelease: {
+      strVersion: '1.2.3',
+      strCommit: 'abc123',
+      strBuildTime: '2026-08-26T08:00:00.000Z',
+      strEnvironment: 'test',
+    },
+  })
+  const objFrame = document.createElement('iframe')
+  document.body.append(objFrame)
+  const objIsolatedWindow = objFrame.contentWindow
+  if (!objIsolatedWindow) throw new Error('Expected iframe window')
+  const fnStop = fnStartGlobalErrorObservation(objIsolatedWindow)
+
+  objIsolatedWindow.dispatchEvent(
+    new ErrorEvent('error', {
+      error: new Error('window failed'),
+      message: 'window failed',
+    })
+  )
+  expect(fnCaptureEvent).toHaveBeenCalledOnce()
+  expect(fnCaptureEvent).toHaveBeenCalledWith(
+    expect.objectContaining({
+      strName: 'browser.unhandled_error',
+      strSource: 'global',
+    })
+  )
+
+  fnStop()
+  objIsolatedWindow.dispatchEvent(
+    new ErrorEvent('error', {
+      error: new Error('after cleanup'),
+      message: 'after cleanup',
+    })
+  )
+  expect(fnCaptureEvent).toHaveBeenCalledOnce()
+  objFrame.remove()
+})

package/template/tests/unit/observability/observer.test.ts

@@ -0,0 +1,115 @@
+import {
+  fnCaptureError,
+  fnCaptureObservabilityEvent,
+  fnConfigureObservability,
+  type IObservabilityAdapter,
+  type IReleaseInfo,
+} from '@/observability'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const objRelease: IReleaseInfo = {
+  strVersion: '1.2.3',
+  strCommit: 'abc123',
+  strBuildTime: '2026-08-26T08:00:00.000Z',
+  strEnvironment: 'test',
+}
+
+beforeEach(() => {
+  fnConfigureObservability({ bEnabled: false, objRelease })
+})
+
+describe('observability adapter', () => {
+  it('sends only redacted allowlisted attributes with release context', () => {
+    const fnCaptureEvent = vi.fn()
+    const objAdapter: IObservabilityAdapter = { fnCaptureEvent }
+    fnConfigureObservability({
+      bEnabled: true,
+      objAdapter,
+      objRelease,
+    })
+
+    const objEvent = fnCaptureError(
+      new Error(
+        'Bearer secret-token user@example.com 13800138000 password=hunter2'
+      ),
+      {
+        strName: 'api.request_failed',
+        strSource: 'api',
+        objAttributes: {
+          nStatus: 500,
+          strRequestId: 'request-1',
+          strToken: 'must-not-leave-browser',
+          objBody: { strPassword: 'must-not-leave-browser' },
+        },
+      }
+    )
+
+    expect(objEvent).toMatchObject({
+      strName: 'api.request_failed',
+      strLevel: 'error',
+      strSource: 'api',
+      objAttributes: {
+        nStatus: 500,
+        strRequestId: 'request-1',
+      },
+      objRelease,
+    })
+    expect(objEvent?.objException?.strMessage).toBe(
+      'Bearer [REDACTED] [REDACTED_EMAIL] [REDACTED_PHONE] password=[REDACTED]'
+    )
+    expect(JSON.stringify(objEvent)).not.toContain('must-not-leave-browser')
+    expect(fnCaptureEvent).toHaveBeenCalledOnce()
+  })
+
+  it('does not dispatch when disabled and isolates adapter failures', () => {
+    const fnCaptureEvent = vi.fn(() => {
+      throw new Error('provider unavailable')
+    })
+    fnConfigureObservability({
+      bEnabled: false,
+      objAdapter: { fnCaptureEvent },
+      objRelease,
+    })
+
+    expect(
+      fnCaptureObservabilityEvent({
+        strName: 'application.ready',
+        strSource: 'bootstrap',
+      })
+    ).toBeUndefined()
+    expect(fnCaptureEvent).not.toHaveBeenCalled()
+
+    fnConfigureObservability({
+      bEnabled: true,
+      objAdapter: { fnCaptureEvent },
+      objRelease,
+    })
+    expect(() =>
+      fnCaptureObservabilityEvent({
+        strName: 'application.ready',
+        strSource: 'bootstrap',
+      })
+    ).not.toThrow()
+  })
+
+  it('deduplicates the same error object across reporting boundaries', () => {
+    const fnCaptureEvent = vi.fn()
+    fnConfigureObservability({
+      bEnabled: true,
+      objAdapter: { fnCaptureEvent },
+      objRelease,
+    })
+    const objError = new Error('render failed')
+
+    fnCaptureError(objError, {
+      strName: 'route.render_failed',
+      strSource: 'route',
+    })
+    fnCaptureError(objError, {
+      strName: 'browser.unhandled_error',
+      strSource: 'global',
+    })
+
+    expect(fnCaptureEvent).toHaveBeenCalledOnce()
+  })
+})