test(web): add frontend unit test baseline (#5451)

.circleci/config.yml

@@ -7,14 +7,15 @@ jobs:
     steps:
     - checkout
     - run:
-        name: Build web assets (frps)
+        name: Test and build web assets
-        command: make install build
+        command: make web-ci
-        working_directory: web/frps
     - run:
-        name: Build web assets (frpc)
+        name: Check Go formatting and build binaries
-        command: make install build
+        command: |
-        working_directory: web/frpc
+          set -e
-    - run: make
+          make env fmt
+          git diff --exit-code
+          make build
     - run: make alltest
 
 workflows:

.github/workflows/golangci-lint.yml

@@ -22,12 +22,8 @@ jobs:
     - uses: actions/setup-node@v6
       with:
         node-version: '22'
-    - name: Build web assets (frps)
+    - name: Test and build web assets
-      run: make build
+      run: make web-ci
-      working-directory: web/frps
-    - name: Build web assets (frpc)
-      run: make build
-      working-directory: web/frpc
     - name: golangci-lint
       uses: golangci/golangci-lint-action@v9
       with:

Makefile

@@ -5,7 +5,7 @@ NOWEB_TAG = $(shell [ ! -d web/frps/dist ] || [ ! -d web/frpc/dist ] && echo ',n
 FRP_COMPAT_BASELINE_COUNT ?= 8
 FRP_COMPAT_FLOOR_VERSION ?= 0.61.0
 
-.PHONY: web frps-web frpc-web frps frpc e2e-compatibility-smoke e2e-compatibility e2e-compatibility-floor
+.PHONY: web web-ci frps-web frpc-web frps frpc e2e-compatibility-smoke e2e-compatibility e2e-compatibility-floor
 
 all: env fmt web build
 
@@ -16,6 +16,9 @@ env:
 
 web: frps-web frpc-web
 
+web-ci:
+	cd web && npm ci && npm run test:unit && npm run build --workspace frps && npm run build --workspace frpc
+
 frps-web:
 	$(MAKE) -C web/frps build
 

web/frpc/test/config-field.test.ts

@@ -0,0 +1,73 @@
+import { defineComponent } from 'vue'
+import { describe, expect, it } from 'vitest'
+import { mount } from '@vue/test-utils'
+import ConfigField from '../src/components/ConfigField.vue'
+
+const InputStub = defineComponent({
+  props: ['modelValue', 'disabled', 'placeholder', 'type'],
+  emits: ['update:modelValue'],
+  template:
+    '<input :value="modelValue ?? \'\'" :disabled="disabled" :placeholder="placeholder" :type="type === \'password\' ? \'password\' : \'text\'" @input="$emit(\'update:modelValue\', $event.target.value)" />',
+})
+
+const FormItemStub = defineComponent({
+  template: '<div class="form-item-stub"><slot /></div>',
+})
+
+const stubs = {
+  'el-form-item': FormItemStub,
+  'el-input': InputStub,
+  'el-switch': defineComponent({
+    props: ['modelValue', 'disabled'],
+    emits: ['update:modelValue'],
+    template: '<button :disabled="disabled" @click="$emit(\'update:modelValue\', !modelValue)">switch</button>',
+  }),
+  KeyValueEditor: defineComponent({ template: '<div class="key-value-stub" />' }),
+  StringListEditor: defineComponent({ template: '<div class="string-list-stub" />' }),
+  PopoverMenu: defineComponent({ template: '<div class="popover-stub"><slot /></div>' }),
+  PopoverMenuItem: defineComponent({ template: '<div><slot /></div>' }),
+}
+
+describe('ConfigField', () => {
+  it('clamps numeric input and emits the public model update', async () => {
+    const wrapper = mount(ConfigField, {
+      props: { label: 'Port', type: 'number', modelValue: 100, min: 1, max: 65535 },
+      global: { stubs },
+    })
+
+    const input = wrapper.find('input')
+    await input.setValue('70000')
+
+    expect(wrapper.emitted('update:modelValue')).toContainEqual([65535])
+    expect((input.element as HTMLInputElement).value).toBe('65535')
+  })
+
+  it('keeps a leading sign as an editable draft until it becomes numeric', async () => {
+    const wrapper = mount(ConfigField, {
+      props: { label: 'Port', type: 'number', modelValue: 100 },
+      global: { stubs },
+    })
+
+    const input = wrapper.find('input')
+    await wrapper.setProps({ modelValue: 200 })
+    expect((input.element as HTMLInputElement).value).toBe('200')
+
+    await input.setValue('-')
+
+    expect(wrapper.emitted('update:modelValue')).toContainEqual([undefined])
+    await wrapper.setProps({ modelValue: undefined })
+    expect((input.element as HTMLInputElement).value).toBe('-')
+  })
+
+  it('renders an empty readonly field as a disabled placeholder', () => {
+    const wrapper = mount(ConfigField, {
+      props: { label: 'Secret', readonly: true, modelValue: '' },
+      global: { stubs },
+    })
+
+    const input = wrapper.find('input').element as HTMLInputElement
+    expect(wrapper.find('.config-field-label').text()).toBe('Secret')
+    expect(input.disabled).toBe(true)
+    expect(input.value).toBe('—')
+  })
+})

web/frpc/test/proxy-converters.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import {
+  createDefaultProxyForm,
+  createDefaultVisitorForm,
+} from '../src/types/proxy-form'
+import {
+  formToStoreProxy,
+  formToStoreVisitor,
+  storeProxyToForm,
+} from '../src/types/proxy-converters'
+
+describe('proxy converters', () => {
+  it('serializes only configured proxy fields into the typed store block', () => {
+    const form = createDefaultProxyForm()
+    Object.assign(form, {
+      name: 'web',
+      type: 'http',
+      enabled: false,
+      localIP: '10.0.0.8',
+      localPort: 8080,
+      useEncryption: true,
+      customDomains: ['example.com', ''],
+      locations: ['/api', ''],
+      metadatas: [{ key: 'team', value: 'edge' }],
+    })
+
+    expect(formToStoreProxy(form)).toEqual({
+      name: 'web',
+      type: 'http',
+      http: {
+        enabled: false,
+        localIP: '10.0.0.8',
+        localPort: 8080,
+        transport: { useEncryption: true },
+        metadatas: { team: 'edge' },
+        customDomains: ['example.com'],
+        locations: ['/api'],
+      },
+    })
+  })
+
+  it('round-trips store values while applying form defaults', () => {
+    const form = storeProxyToForm({
+      name: 'tcp-proxy',
+      type: 'tcp',
+      tcp: {
+        localPort: 9000,
+        customDomains: 'unused-for-tcp',
+        enabled: false,
+        metadatas: { owner: 'platform' },
+      },
+    })
+
+    expect(form).toMatchObject({
+      name: 'tcp-proxy',
+      type: 'tcp',
+      enabled: false,
+      localIP: '127.0.0.1',
+      localPort: 9000,
+      metadatas: [{ key: 'owner', value: 'platform' }],
+      multiplexer: 'httpconnect',
+    })
+  })
+
+  it.each(['stcp', 'xtcp'] as const)(
+    'serializes virtual_net for %s visitors',
+    (type) => {
+      const form = createDefaultVisitorForm()
+      Object.assign(form, {
+        name: 'visitor',
+        type,
+        pluginType: 'virtual_net',
+        pluginDestinationIP: ' 192.0.2.10 ',
+        bindPort: 6000,
+      })
+
+      expect(formToStoreVisitor(form)[type]).toMatchObject({
+        plugin: { type: 'virtual_net', destinationIP: '192.0.2.10' },
+        bindPort: 6000,
+      })
+    },
+  )
+
+  it('does not serialize virtual_net for SUDP visitors', () => {
+    const form = createDefaultVisitorForm()
+    Object.assign(form, {
+      name: 'visitor',
+      type: 'sudp',
+      pluginType: 'virtual_net',
+      pluginDestinationIP: '192.0.2.10',
+      bindPort: 6000,
+    })
+
+    expect(formToStoreVisitor(form).sudp).toEqual({ bindPort: 6000 })
+  })
+})

web/frps/test/stat-card.test.ts

@@ -0,0 +1,48 @@
+import { defineComponent } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+
+const router = vi.hoisted(() => ({ push: vi.fn() }))
+vi.mock('vue-router', () => ({ useRouter: () => router }))
+
+import StatCard from '../src/components/StatCard.vue'
+
+const stubs = {
+  'el-card': defineComponent({
+    template: '<div class="el-card-stub" @click="$emit(\'click\', $event)"><slot /></div>',
+    emits: ['click'],
+  }),
+  'el-icon': defineComponent({ template: '<span class="el-icon-stub"><slot /></span>' }),
+}
+
+describe('StatCard', () => {
+  it('shows its content and does not navigate without a destination', async () => {
+    router.push.mockClear()
+    const wrapper = mount(StatCard, {
+      props: { label: 'Clients', value: 3, subtitle: 'active' },
+      global: { stubs },
+    })
+
+    expect(wrapper.find('.stat-value').text()).toBe('3')
+    expect(wrapper.find('.stat-label').text()).toBe('Clients')
+    expect(wrapper.find('.stat-subtitle').text()).toBe('active')
+    expect(wrapper.find('.arrow-icon').exists()).toBe(false)
+
+    await wrapper.find('.stat-card').trigger('click')
+
+    expect(router.push).not.toHaveBeenCalled()
+  })
+
+  it('navigates only when a destination is provided', async () => {
+    router.push.mockClear()
+    const wrapper = mount(StatCard, {
+      props: { label: 'Proxies', value: '12', type: 'proxies', to: '/proxies' },
+      global: { stubs },
+    })
+
+    await wrapper.find('.stat-card').trigger('click')
+
+    expect(router.push).toHaveBeenCalledWith('/proxies')
+    expect(wrapper.find('.arrow-icon').exists()).toBe(true)
+  })
+})

web/package.json

@@ -1,5 +1,14 @@
 {
   "name": "frp-web",
   "private": true,
-  "workspaces": ["shared", "frpc", "frps"]
+  "workspaces": ["shared", "frpc", "frps"],
+  "scripts": {
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
+  "devDependencies": {
+    "@vue/test-utils": "2.4.11",
+    "jsdom": "29.1.1",
+    "vitest": "4.1.10"
+  }
 }

web/shared/test/action-button.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { mount } from '@vue/test-utils'
+import ActionButton from '../components/ActionButton.vue'
+
+describe('ActionButton', () => {
+  it('emits click events for an enabled button', async () => {
+    const wrapper = mount(ActionButton, { slots: { default: 'Save' } })
+
+    await wrapper.trigger('click')
+
+    expect(wrapper.emitted('click')).toHaveLength(1)
+    expect(wrapper.text()).toBe('Save')
+  })
+
+  it('disables itself and shows loading text while loading', async () => {
+    const wrapper = mount(ActionButton, {
+      props: { loading: true, loadingText: 'Saving...' },
+      slots: { default: 'Save' },
+    })
+
+    await wrapper.trigger('click')
+
+    expect((wrapper.element as HTMLButtonElement).disabled).toBe(true)
+    expect(wrapper.classes()).toContain('is-loading')
+    expect(wrapper.find('.spinner').exists()).toBe(true)
+    expect(wrapper.text()).toBe('Saving...')
+    expect(wrapper.emitted('click')).toBeUndefined()
+  })
+})

web/test/setup.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from 'vitest'
+
+const capturedFetch = globalThis.fetch
+
+describe('unit-test environment', () => {
+  it('blocks real network requests before test modules are evaluated', async () => {
+    await expect(capturedFetch('https://example.invalid/')).rejects.toThrow(
+      'Real network requests are disabled in unit tests',
+    )
+  })
+
+  it('allows a test to replace fetch explicitly', async () => {
+    const replacement = vi.fn(async () => new Response('ok'))
+    vi.stubGlobal('fetch', replacement)
+
+    await expect(fetch('/test-endpoint')).resolves.toBeInstanceOf(Response)
+    expect(replacement).toHaveBeenCalledWith('/test-endpoint')
+  })
+
+  it('restores the network guard after a test replacement', async () => {
+    await expect(fetch('/must-remain-isolated')).rejects.toThrow(
+      'Real network requests are disabled in unit tests',
+    )
+  })
+})

web/test/setup.ts

@@ -0,0 +1,25 @@
+import { enableAutoUnmount } from '@vue/test-utils'
+import { afterAll, afterEach, vi } from 'vitest'
+
+const originalFetch = globalThis.fetch
+const blockedFetch = vi.fn(async () => {
+  throw new Error('Real network requests are disabled in unit tests')
+})
+
+globalThis.fetch = blockedFetch as typeof fetch
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  vi.clearAllMocks()
+  globalThis.fetch = blockedFetch as typeof fetch
+  document.body.innerHTML = ''
+})
+
+// Vitest runs afterEach hooks in reverse registration order, so wrappers are
+// unmounted before the cleanup hook above clears the DOM.
+enableAutoUnmount(afterEach)
+
+afterAll(() => {
+  globalThis.fetch = originalFetch
+})

web/vitest.config.mts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        extends: './frpc/vite.config.mts',
+        root: './frpc',
+        test: {
+          name: 'frpc',
+          environment: 'jsdom',
+          css: true,
+          server: {
+            deps: { inline: ['element-plus', '@element-plus/icons-vue'] },
+          },
+          setupFiles: ['../test/setup.ts'],
+          include: [
+            '../test/**/*.test.ts',
+            'test/**/*.test.ts',
+            '../shared/**/*.test.ts',
+          ],
+        },
+      },
+      {
+        extends: './frps/vite.config.mts',
+        root: './frps',
+        test: {
+          name: 'frps',
+          environment: 'jsdom',
+          css: true,
+          server: {
+            deps: { inline: ['element-plus', '@element-plus/icons-vue'] },
+          },
+          setupFiles: ['../test/setup.ts'],
+          include: ['test/**/*.test.ts'],
+        },
+      },
+    ],
+  },
+})