@opentiny/next-sdk 0.4.0 → 0.4.2

package/test/page-tools/a11y/config.test.ts

@@ -0,0 +1,370 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import {
+  resolveA11yRole,
+  resolveA11yStates,
+  resolveA11yInfo,
+  mergeA11yConfig,
+  mergeA11yConfigs,
+  ensureResolvedA11yConfig,
+  isResolvedA11yConfig,
+  defineA11yConfig,
+  extractSelectors,
+  type A11yConfig,
+} from '../../../page-tools/a11y/config'
+
+function el(html: string): Element {
+  const wrapper = document.createElement('div')
+  wrapper.innerHTML = html.trim()
+  document.body.appendChild(wrapper)
+  return wrapper.firstElementChild as Element
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('resolveA11yRole', () => {
+  it('标签隐式角色：无规则时按 TAG_ROLE_MAP 推断', () => {
+    expect(resolveA11yRole(el('<button>btn</button>'))).toBe('button')
+    expect(resolveA11yRole(el('<a href="#">link</a>'))).toBe('link')
+  })
+
+  it('INPUT_TYPE_ROLE：不同 type 的 input 角色不同', () => {
+    expect(resolveA11yRole(el('<input type="checkbox" />'))).toBe('checkbox')
+    expect(resolveA11yRole(el('<input type="radio" />'))).toBe('radio')
+    expect(resolveA11yRole(el('<input type="text" />'))).toBe('textbox')
+  })
+
+  it('无匹配时兜底为 generic', () => {
+    expect(resolveA11yRole(el('<div></div>'))).toBe('generic')
+  })
+
+  it('显式 role 属性优先，且不会被普通规则覆盖', () => {
+    const target = el('<div role="dialog" class="tab-item"></div>')
+    const config = defineA11yConfig({ roles: [{ role: 'tab', selector: '.tab-item' }] })
+    expect(resolveA11yRole(target, config)).toBe('dialog')
+  })
+
+  it('自定义 selector 规则命中后赋予新角色', () => {
+    const target = el('<div class="tab-item"></div>')
+    const config = defineA11yConfig({ roles: [{ role: 'tab', selector: '.tab-item' }] })
+    expect(resolveA11yRole(target, config)).toBe('tab')
+  })
+
+  it('roles 的 selector 仅匹配自身，不把角色传染给子孙', () => {
+    const wrap = el('<div class="tab-item"><span class="label">总览</span></div>')
+    const config = defineA11yConfig({ roles: [{ role: 'tab', selector: '.tab-item' }] })
+    expect(resolveA11yRole(wrap, config)).toBe('tab')
+    expect(resolveA11yRole(wrap.querySelector('.label')!, config)).toBe('generic')
+  })
+
+  it('自定义 match 函数规则命中后赋予新角色', () => {
+    const target = el('<div data-kind="switcher"></div>')
+    const config = defineA11yConfig({
+      roles: [{ role: 'switch', match: (e) => e.getAttribute('data-kind') === 'switcher' }],
+    })
+    expect(resolveA11yRole(target, config)).toBe('switch')
+  })
+
+  it('force: true 时覆盖元素已有的显式 role', () => {
+    const target = el('<div role="button" class="tab-item"></div>')
+    const config = defineA11yConfig({ roles: [{ role: 'tab', selector: '.tab-item', force: true }] })
+    expect(resolveA11yRole(target, config)).toBe('tab')
+  })
+
+  it('多条规则按数组顺序命中第一条生效', () => {
+    const target = el('<div class="a b"></div>')
+    const config = defineA11yConfig({
+      roles: [
+        { role: 'first', selector: '.a' },
+        { role: 'second', selector: '.b' },
+      ],
+    })
+    expect(resolveA11yRole(target, config)).toBe('first')
+  })
+})
+
+describe('resolveA11yStates - 标准 ARIA 零配置检测', () => {
+  it('checked: aria-checked=true/false', () => {
+    expect(resolveA11yStates(el('<div role="checkbox" aria-checked="true"></div>'))).toContain('checked')
+    expect(resolveA11yStates(el('<div role="checkbox" aria-checked="false"></div>'))).toContain('unchecked')
+  })
+
+  it('checked: aria-checked=mixed 三态', () => {
+    expect(resolveA11yStates(el('<div role="checkbox" aria-checked="mixed"></div>'))).toContain('checked=mixed')
+  })
+
+  it('checked: 原生 checkbox/radio 的 checked 属性', () => {
+    const checkbox = el('<input type="checkbox" />') as HTMLInputElement
+    checkbox.checked = true
+    expect(resolveA11yStates(checkbox)).toContain('checked')
+
+    const radio = el('<input type="radio" />') as HTMLInputElement
+    expect(resolveA11yStates(radio)).toContain('unchecked')
+  })
+
+  it('checked: label[for] 关联的 checkbox 状态', () => {
+    const wrapper = document.createElement('div')
+    wrapper.innerHTML = '<input id="c1" type="checkbox" /><label for="c1">选项</label>'
+    document.body.appendChild(wrapper)
+    const input = wrapper.querySelector('#c1') as HTMLInputElement
+    input.checked = true
+    const label = wrapper.querySelector('label') as Element
+    expect(resolveA11yStates(label)).toContain('checked')
+  })
+
+  it('selected: aria-selected=true', () => {
+    expect(resolveA11yStates(el('<div role="tab" aria-selected="true"></div>'))).toContain('selected')
+  })
+
+  it('selected: 内置 class 启发式（如 is-active）', () => {
+    expect(resolveA11yStates(el('<button class="is-active">Tab1</button>'))).toContain('selected')
+  })
+
+  it('pressed: aria-pressed 三态', () => {
+    expect(resolveA11yStates(el('<button aria-pressed="true"></button>'))).toContain('pressed')
+    expect(resolveA11yStates(el('<button aria-pressed="mixed"></button>'))).toContain('pressed=mixed')
+    expect(resolveA11yStates(el('<button aria-pressed="false"></button>'))).not.toContain('pressed')
+  })
+
+  it('current: aria-current 各种取值', () => {
+    expect(resolveA11yStates(el('<a aria-current="true"></a>'))).toContain('current')
+    expect(resolveA11yStates(el('<a aria-current="page"></a>'))).toContain('current=page')
+    expect(resolveA11yStates(el('<a aria-current="step"></a>'))).toContain('current=step')
+  })
+
+  it('disabled: aria-disabled 与原生 disabled', () => {
+    expect(resolveA11yStates(el('<div aria-disabled="true"></div>'))).toContain('disabled')
+    const btn = el('<button disabled></button>') as HTMLButtonElement
+    expect(resolveA11yStates(btn)).toContain('disabled')
+  })
+
+  it('expanded: aria-expanded=true', () => {
+    expect(resolveA11yStates(el('<button aria-expanded="true"></button>'))).toContain('expanded')
+  })
+
+  it('hasPopup: aria-haspopup 非 false 值', () => {
+    expect(resolveA11yStates(el('<button aria-haspopup="menu"></button>'))).toContain('hasPopup')
+    expect(resolveA11yStates(el('<button aria-haspopup="false"></button>'))).not.toContain('hasPopup')
+  })
+
+  it('invalid: aria-invalid 取值', () => {
+    expect(resolveA11yStates(el('<input aria-invalid="true" />'))).toContain('invalid')
+    expect(resolveA11yStates(el('<input aria-invalid="spelling" />'))).toContain('invalid=spelling')
+  })
+
+  it('readonly: aria-readonly 与原生 readOnly', () => {
+    expect(resolveA11yStates(el('<input aria-readonly="true" />'))).toContain('readonly')
+    const input = el('<input />') as HTMLInputElement
+    input.readOnly = true
+    expect(resolveA11yStates(input)).toContain('readonly')
+  })
+
+  it('required: aria-required 与原生 required', () => {
+    expect(resolveA11yStates(el('<input aria-required="true" />'))).toContain('required')
+    const input = el('<input />') as HTMLInputElement
+    input.required = true
+    expect(resolveA11yStates(input)).toContain('required')
+  })
+
+  it('busy: aria-busy=true', () => {
+    expect(resolveA11yStates(el('<div aria-busy="true"></div>'))).toContain('busy')
+  })
+
+  it('orientation: aria-orientation', () => {
+    expect(resolveA11yStates(el('<div aria-orientation="vertical"></div>'))).toContain('orientation=vertical')
+  })
+
+  it('sort: aria-sort，排除 none', () => {
+    // 用 div + role="columnheader" 代替裸 <th>，避免 innerHTML 解析时因缺少 <table>/<tr> 上下文被浏览器/jsdom 丢弃
+    expect(resolveA11yStates(el('<div role="columnheader" aria-sort="ascending"></div>'))).toContain('sort=ascending')
+    expect(resolveA11yStates(el('<div role="columnheader" aria-sort="none"></div>'))).not.toContain('sort=none')
+  })
+
+  it('multiselectable: aria-multiselectable=true', () => {
+    expect(resolveA11yStates(el('<div aria-multiselectable="true"></div>'))).toContain('multiselectable')
+  })
+
+  it('valuenow/valuetext', () => {
+    const tokens = resolveA11yStates(el('<div aria-valuenow="50" aria-valuetext="中"></div>'))
+    expect(tokens).toContain('valuenow="50"')
+    expect(tokens).toContain('valuetext="中"')
+  })
+
+  it('heading level：h1-h6 与 aria-level', () => {
+    expect(resolveA11yStates(el('<h2>标题</h2>'))).toContain('level=2')
+    expect(resolveA11yStates(el('<div role="heading" aria-level="3"></div>'))).toContain('level=3')
+  })
+
+  it('cursor=pointer', () => {
+    const target = el('<div></div>') as HTMLElement
+    target.style.cursor = 'pointer'
+    expect(resolveA11yStates(target)).toContain('cursor=pointer')
+  })
+
+  it('value=""：input/textarea/select 有值时输出', () => {
+    const input = el('<input />') as HTMLInputElement
+    input.value = 'hello'
+    expect(resolveA11yStates(input)).toContain('value="hello"')
+  })
+
+  it('target：a[target] 输出原生属性值', () => {
+    expect(resolveA11yStates(el('<a target="_blank"></a>'))).toContain('target=_blank')
+    expect(resolveA11yStates(el('<a target="_self"></a>'))).toContain('target=_self')
+    expect(resolveA11yStates(el('<a></a>'))).not.toContain('target=_blank')
+  })
+})
+
+describe('resolveA11yStates - 自定义规则', () => {
+  it('states.<标准名> 用 selector 命中标准状态名', () => {
+    const target = el('<button class="btn is-checked"></button>')
+    const config = defineA11yConfig({ states: { selected: { selector: '.is-checked' } } })
+    expect(resolveA11yStates(target, config)).toContain('selected')
+  })
+
+  it('states 的 selector 用 closest，子孙可继承容器选中态', () => {
+    const wrap = el('<li class="ti3-tab-li ti3-tab-active"><span class="ti3-tabs-text">总览</span></li>')
+    const config = defineA11yConfig({ states: { selected: { selector: 'li.ti3-tab-li.ti3-tab-active' } } })
+    expect(resolveA11yStates(wrap.querySelector('.ti3-tabs-text')!, config)).toContain('selected')
+  })
+
+  it('默认配置：Tiny3 按钮组 ti3-active 在容器上时，内部 button 仍输出 selected', () => {
+    const wrap = el(
+      '<div class="ti3-btn-item-container ti3-active"><button class="ti3-btn-item ti3-btn-item-radio" aria-label="竞价计费">竞价计费</button></div>',
+    )
+    const btn = wrap.querySelector('button')!
+    expect(resolveA11yStates(btn)).toContain('selected')
+    // 未激活的兄弟按钮不应误标 selected
+    const inactive = el(
+      '<div class="ti3-btn-item-container"><button class="ti3-btn-item ti3-btn-item-radio">按需计费</button></div>',
+    )
+    expect(resolveA11yStates(inactive.querySelector('button')!)).not.toContain('selected')
+  })
+
+  it('states.<标准名> 用 match 函数命中', () => {
+    const target = el('<span class="form-tip--warn">警告文本</span>')
+    const config = defineA11yConfig({ states: { warning: { selector: '.form-tip--warn' } } })
+    expect(resolveA11yStates(target, config)).toContain('warning')
+  })
+
+  it('selector 支持字符串数组：命中数组中任意一个 class 均视为选中', () => {
+    const legacy = el('<button class="btn is-active"></button>')
+    const modern = el('<button class="btn is-checked"></button>')
+    const none = el('<button class="btn"></button>')
+    const config = defineA11yConfig({
+      states: { selected: { selector: ['.is-active', '.is-checked'] } },
+    })
+    expect(resolveA11yStates(legacy, config)).toContain('selected')
+    expect(resolveA11yStates(modern, config)).toContain('selected')
+    expect(resolveA11yStates(none, config)).not.toContain('selected')
+  })
+
+  it('error 与 warning 同时命中时只输出 error（优先级）', () => {
+    const target = el('<div class="is-error is-warning">错误</div>')
+    const config = defineA11yConfig({
+      states: {
+        error: { selector: '.is-error' },
+        warning: { selector: '.is-warning' },
+      },
+    })
+    const tokens = resolveA11yStates(target, config)
+    expect(tokens).toContain('error')
+    expect(tokens).not.toContain('warning')
+  })
+
+  it('命中非标准自定义状态名时直接输出同名 token', () => {
+    const target = el('<div class="highlight-row"></div>')
+    const config = defineA11yConfig({ states: { highlighted: { selector: '.highlight-row' } } })
+    expect(resolveA11yStates(target, config)).toContain('highlighted')
+  })
+
+  it('exposedAttributes：属性存在时输出属性 token，不存在时不输出', () => {
+    const withAttr = el('<div data-testid="foo"></div>')
+    const withoutAttr = el('<div></div>')
+    const config = defineA11yConfig({ exposedAttributes: ['data-testid'] })
+    expect(resolveA11yStates(withAttr, config)).toContain('data-testid="foo"')
+    const tokensWithout = resolveA11yStates(withoutAttr, config)
+    expect(tokensWithout.some((t) => t.includes('data-testid'))).toBe(false)
+  })
+})
+
+describe('resolveA11yInfo', () => {
+  it('整合 role 与 tokens 的返回结构', () => {
+    const target = el('<div class="tab-item" aria-selected="true"></div>')
+    const config = defineA11yConfig({ roles: [{ role: 'tab', selector: '.tab-item' }] })
+    const info = resolveA11yInfo(target, config)
+    expect(info.role).toBe('tab')
+    expect(info.tokens).toContain('selected')
+  })
+})
+
+describe('mergeA11yConfig / mergeA11yConfigs', () => {
+  it('默认值与用户配置按数组拼接，不丢默认规则', () => {
+    const merged = mergeA11yConfig({ roles: [{ role: 'tab', selector: '.tab' }] })
+    expect(merged.roles).toEqual([{ role: 'tab', selector: '.tab' }])
+    // 默认 states.error/warning/selected 规则仍然存在
+    expect(merged.states.error?.length).toBeGreaterThan(0)
+    expect(merged.states.warning?.length).toBeGreaterThan(0)
+    expect(merged.states.selected?.length).toBeGreaterThan(0)
+  })
+
+  it('states 按 key 独立合并', () => {
+    const merged = mergeA11yConfig({ states: { current: { selector: '.step-current' } } })
+    expect(merged.states.current).toEqual([{ selector: '.step-current' }])
+    expect(merged.states.error?.length).toBeGreaterThan(0)
+  })
+
+  it('未提供的字段回退默认空数组', () => {
+    const merged = mergeA11yConfig()
+    expect(merged.whitelist).toEqual([])
+    expect(merged.blacklist).toEqual([])
+    expect(merged.exposedAttributes).toEqual([])
+  })
+
+  it('mergeA11yConfigs 对两份任意 A11yConfig 做加法合并', () => {
+    const a: A11yConfig = { whitelist: ['.a'] }
+    const b: A11yConfig = { whitelist: ['.b'] }
+    const merged = mergeA11yConfigs(a, b)
+    expect(merged.whitelist).toEqual(['.a', '.b'])
+  })
+
+  it('已 Resolved 的配置再次 mergeA11yConfig / ensureResolved 保持同引用且规则不翻倍', () => {
+    const once = mergeA11yConfig({ roles: [{ role: 'tab', selector: '.tab' }] })
+    const selectedLen = once.states.selected!.length
+    expect(isResolvedA11yConfig(once)).toBe(true)
+    expect(mergeA11yConfig(once)).toBe(once)
+    expect(ensureResolvedA11yConfig(once)).toBe(once)
+    expect(once.states.selected!.length).toBe(selectedLen)
+    // 未标记的普通 A11yConfig 仍会与默认合并
+    const raw: A11yConfig = { roles: [{ role: 'tab', selector: '.tab' }] }
+    expect(isResolvedA11yConfig(raw)).toBe(false)
+    expect(ensureResolvedA11yConfig(raw)).not.toBe(raw)
+  })
+})
+
+describe('defineA11yConfig', () => {
+  it('恒等返回', () => {
+    const config: A11yConfig = { roles: [{ role: 'tab', selector: '.tab' }] }
+    expect(defineA11yConfig(config)).toBe(config)
+  })
+})
+
+describe('extractSelectors', () => {
+  it('从规则数组中提取纯选择器，忽略只有 match 的规则', () => {
+    const selectors = extractSelectors([{ selector: '.a' }, { match: () => true }, { selector: '.b' }])
+    expect(selectors).toEqual(['.a', '.b'])
+  })
+
+  it('数组类型的 selector 会被展开为独立的选择器字符串', () => {
+    const selectors = extractSelectors([{ selector: ['.a', '.b'] }, { selector: '.c' }])
+    expect(selectors).toEqual(['.a', '.b', '.c'])
+  })
+
+  it('无规则时返回空数组', () => {
+    expect(extractSelectors(undefined)).toEqual([])
+  })
+})

package/test/page-tools/configs/console-cloud.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { resolveA11yInfo } from '../../../page-tools/a11y/config'
+import {
+  consoleCloudPageAgentToolOptions,
+  isConsoleCloudHost,
+} from '../../../page-tools/configs/console-cloud'
+import { buildA11yTree } from '../../../page-tools/a11y-tree'
+import { collectTitleLabel } from '../../../page-tools/a11y/utils'
+
+function el(html: string): Element {
+  const wrapper = document.createElement('div')
+  wrapper.innerHTML = html.trim()
+  document.body.appendChild(wrapper)
+  return wrapper.firstElementChild as Element
+}
+
+function setupRoot(html: string): HTMLElement {
+  const root = document.createElement('div')
+  root.innerHTML = html.trim()
+  document.body.appendChild(root)
+  return root
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+const a11yConfig = consoleCloudPageAgentToolOptions.a11yConfig!
+
+describe('isConsoleCloudHost', () => {
+  it('匹配控制台主域与子控制台，且要求 console 前为域名边界', () => {
+    expect(isConsoleCloudHost('console.huaweicloud.com')).toBe(true)
+    expect(isConsoleCloudHost('ecs.console.huaweicloud.com')).toBe(true)
+    expect(isConsoleCloudHost('www.huaweicloud.com')).toBe(false)
+    expect(isConsoleCloudHost('www.baidu.com')).toBe(false)
+    expect(isConsoleCloudHost('xconsole.huaweicloud.com')).toBe(false)
+  })
+})
+
+describe('consoleCloudPageAgentToolOptions', () => {
+  it('导出完整 PageAgentToolOptions，并暴露 cf-uba / data-qa-id / name', () => {
+    expect(consoleCloudPageAgentToolOptions.enableHighlight).toBe(false)
+    expect(a11yConfig.exposedAttributes).toContain('cf-uba')
+    expect(a11yConfig.exposedAttributes).toContain('data-qa-id')
+    expect(a11yConfig.exposedAttributes).toContain('name')
+  })
+
+  it('data-qa-id 仅输出属性 token，不自动赋予 ref', () => {
+    const root = setupRoot(`
+      <div id="page-root">
+        <div data-qa-id="static-marker">静态文案</div>
+      </div>
+    `)
+    const container = root.querySelector('#page-root') as Element
+    const staticEl = root.querySelector('[data-qa-id="static-marker"]') as Element
+    const info = resolveA11yInfo(staticEl, a11yConfig)
+    expect(info.tokens).toContain('data-qa-id="static-marker"')
+    const { refMap } = buildA11yTree(container, a11yConfig)
+    expect(Array.from(refMap.values())).not.toContain(staticEl)
+  })
+
+  it('Tiny3 Tab：.ti3-tabs-text → tab，选中态随父 li.ti3-tab-active', () => {
+    const wrap = el(
+      '<ul class="ti3-tabs"><li class="ti3-tab-li ti3-tab-active"><span class="ti3-tabs-text" tabindex="0">总览</span></li></ul>',
+    )
+    const tab = wrap.querySelector('.ti3-tabs-text')!
+    const info = resolveA11yInfo(tab, a11yConfig)
+    expect(info.role).toBe('tab')
+    expect(info.tokens).toContain('selected')
+    // li 本身不再标成 tab，避免与内部可聚焦节点双重角色
+    expect(resolveA11yInfo(wrap.querySelector('li')!, a11yConfig).role).toBe('listitem')
+  })
+
+  it('Tiny3 Tablist：ul.ti3-tabs → tablist，且不把角色传染给子节点', () => {
+    const list = el('<ul class="ti3-tabs"><li class="ti3-tab-li"><span class="ti3-tabs-text">A</span></li></ul>')
+    expect(resolveA11yInfo(list, a11yConfig).role).toBe('tablist')
+    const child = list.querySelector('li')!
+    expect(resolveA11yInfo(child, a11yConfig).role).not.toBe('tablist')
+    expect(resolveA11yInfo(list.querySelector('.ti3-tabs-text')!, a11yConfig).role).toBe('tab')
+  })
+
+  it('服务列表图标容器 → button + hasPopup', () => {
+    const btn = el('<div class="modules-service-list-menu-service-icon-container" cf-uba="serviceList..open"></div>')
+    const info = resolveA11yInfo(btn, a11yConfig)
+    expect(info.role).toBe('button')
+    expect(info.tokens).toContain('hasPopup')
+    expect(info.tokens.some((t) => t.includes('cf-uba='))).toBe(true)
+  })
+
+  it(
+    '场景：帮助中心头部 ti-icon / tp-icon（固定/全屏/关闭）\n' +
+      '问题：自定义图标标签无 button 语义，Agent 无法点击固定/全屏/关闭\n' +
+      '期望：识别为 button；有 name 属性的图标输出 name token，正文可为空',
+    () => {
+      const root = el(`
+        <div class="ti-global-help-panel-header-right">
+          <tp-icon name="cloudx-action-fixed" class="ti-global-help-panel-header-icon"></tp-icon>
+          <ti-icon class="ti-global-help-panel-header-icon ti3-icon-full-screen ti3-icon"></ti-icon>
+          <ti-icon name="close" class="ti-global-help-panel-header-icon ti-global-help-panel-close ti3-icon-close ti3-icon"></ti-icon>
+        </div>
+      `)
+
+      const fixed = root.querySelector('tp-icon')!
+      const fullScreen = root.querySelector('ti-icon.ti3-icon-full-screen')!
+      const close = root.querySelector('ti-icon[name="close"]')!
+
+      expect(resolveA11yInfo(fixed, a11yConfig).role).toBe('button')
+      expect(resolveA11yInfo(fullScreen, a11yConfig).role).toBe('button')
+      expect(resolveA11yInfo(close, a11yConfig).role).toBe('button')
+
+      const { yaml, refMap, lines } = buildA11yTree(root, a11yConfig)
+      expect(refMap.size).toBeGreaterThanOrEqual(3)
+      expect(Array.from(refMap.values())).toEqual(expect.arrayContaining([fixed, fullScreen, close]))
+      expect(lines.some((l) => /button.*\[.*name=.*cloudx-action-fixed/.test(l))).toBe(true)
+      expect(lines.some((l) => /button.*\[.*name=.*close/.test(l))).toBe(true)
+      expect(lines.some((l) => /button.*\[.*name=full-screen/.test(l))).toBe(false)
+      expect(lines.some((l) => /button.*"cloudx-action-fixed"/.test(l))).toBe(false)
+      expect(lines.some((l) => /button.*"full-screen"/.test(l))).toBe(false)
+      expect(lines.some((l) => /button.*"close"/.test(l))).toBe(false)
+      expect(yaml).not.toMatch(/@font-face/i)
+    },
+  )
+
+  it('区域选择触发器 → combobox', () => {
+    const box = el('<div class="ti3-select-dominator-container"><span>华北-北京四</span></div>')
+    expect(resolveA11yInfo(box, a11yConfig).role).toBe('combobox')
+  })
+
+  it('服务列表侧栏项 → menuitem + selected', () => {
+    const item = el(
+      '<ul class="components-service-list-left-box-sidebar-visit-panel"><li class="components-service-list-left-box-active">收藏和访问</li></ul>',
+    )
+    const li = item.querySelector('li')!
+    const info = resolveA11yInfo(li, a11yConfig)
+    expect(info.role).toBe('menuitem')
+    expect(info.tokens).toContain('selected')
+  })
+})
+
+describe('collectTitleLabel', () => {
+  it('优先取自身 title，否则取子孙 title', () => {
+    expect(collectTitleLabel(el('<div title="自身"></div>'))).toBe('自身')
+    expect(
+      collectTitleLabel(el('<div class="icon"><span title="打开服务列表"></span></div>')),
+    ).toBe('打开服务列表')
+  })
+})
+
+describe('consoleCloud 图标动作标识', () => {
+  it('ti-icon / tp-icon：name 属性经 exposedAttributes 输出 token', () => {
+    expect(resolveA11yInfo(el('<tp-icon name="cloudx-action-fixed"></tp-icon>'), a11yConfig).tokens).toContain(
+      'name="cloudx-action-fixed"',
+    )
+    expect(resolveA11yInfo(el('<ti-icon name="close" class="ti3-icon-close"></ti-icon>'), a11yConfig).tokens).toContain(
+      'name="close"',
+    )
+    expect(
+      resolveA11yInfo(
+        el('<ti-icon class="ti-global-help-panel-header-icon ti3-icon-full-screen ti3-icon"></ti-icon>'),
+        a11yConfig,
+      ).tokens,
+    ).not.toContain('name=full-screen')
+  })
+})

package/test/page-tools/page-agent-highlight.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { resolveHighlightRect } from '../../page-tools/page-agent-highlight'
+
+const originalGetComputedStyle = window.getComputedStyle
+
+const originalInnerWidth = Object.getOwnPropertyDescriptor(window, 'innerWidth')
+const originalInnerHeight = Object.getOwnPropertyDescriptor(window, 'innerHeight')
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  Object.defineProperty(window, 'getComputedStyle', {
+    configurable: true,
+    value: originalGetComputedStyle,
+  })
+  if (originalInnerWidth) Object.defineProperty(window, 'innerWidth', originalInnerWidth)
+  if (originalInnerHeight) Object.defineProperty(window, 'innerHeight', originalInnerHeight)
+})
+
+describe('resolveHighlightRect', () => {
+  it(
+    '场景：ti-icon 宿主 height=0（字形在 ::before），外包有 28×28 可点父节点\n' +
+      '问题：旧高亮逻辑跳过 width/height 为 0 的节点，帮助中心 full-screen/close 有 ref 却无框\n' +
+      '期望：回退到紧凑父节点矩形',
+    () => {
+      const wrap = document.createElement('div')
+      wrap.style.cssText = 'width:28px;height:28px;position:absolute;left:100px;top:80px;'
+      const icon = document.createElement('ti-icon') as HTMLElement
+      icon.className = 'ti-global-help-panel-header-icon ti3-icon-full-screen ti3-icon'
+      icon.style.cssText = 'width:20px;height:0;display:block;font-size:20px;'
+      wrap.appendChild(icon)
+      document.body.appendChild(wrap)
+
+      // jsdom 对 getBoundingClientRect 支持有限，手动 stub
+      icon.getBoundingClientRect = () =>
+        ({ top: 80.5, left: 964, width: 20, height: 0, bottom: 80.5, right: 984, x: 964, y: 80.5, toJSON() {} }) as DOMRect
+      wrap.getBoundingClientRect = () =>
+        ({ top: 70, left: 960, width: 28, height: 28, bottom: 98, right: 988, x: 960, y: 70, toJSON() {} }) as DOMRect
+
+      const rect = resolveHighlightRect(icon)
+      expect(rect).toEqual({ top: 70, left: 960, width: 28, height: 28 })
+    },
+  )
+
+  it('自身有宽高时直接使用自身矩形，不误用父节点', () => {
+    const el = document.createElement('button')
+    document.body.appendChild(el)
+    el.getBoundingClientRect = () =>
+      ({ top: 10, left: 20, width: 40, height: 24, bottom: 34, right: 60, x: 20, y: 10, toJSON() {} }) as DOMRect
+
+    expect(resolveHighlightRect(el)).toEqual({ top: 10, left: 20, width: 40, height: 24 })
+  })
+
+  it('宿主仅有宽度时用 font-size 补齐高度', () => {
+    const el = document.createElement('ti-icon') as HTMLElement
+    document.body.appendChild(el)
+    el.getBoundingClientRect = () =>
+      ({ top: 80, left: 100, width: 20, height: 0, bottom: 80, right: 120, x: 100, y: 80, toJSON() {} }) as DOMRect
+    Object.defineProperty(window, 'getComputedStyle', {
+      configurable: true,
+      value: () => ({ fontSize: '20px' }) as CSSStyleDeclaration,
+    })
+
+    const rect = resolveHighlightRect(el)
+    expect(rect).not.toBeNull()
+    expect(rect!.width).toBe(20)
+    expect(rect!.height).toBe(20)
+  })
+})
+
+describe('isRectInViewport（通过 highlight 间接验证）', () => {
+  it(
+    '场景：侧栏链接 left 略为负值，旧逻辑要求矩形完全落在视口内会整框跳过\n' +
+      '期望：与视口有交集即绘制高亮',
+    async () => {
+      const { highlight, unhighlight, HIGHLIGHT_CONTAINER_ID } = await import(
+        '../../page-tools/page-agent-highlight'
+      )
+      const el = document.createElement('a')
+      document.body.appendChild(el)
+      el.getBoundingClientRect = () =>
+        ({
+          top: 100,
+          left: -17,
+          width: 259,
+          height: 32,
+          bottom: 132,
+          right: 242,
+          x: -17,
+          y: 100,
+          toJSON() {},
+        }) as DOMRect
+
+      Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1100 })
+      Object.defineProperty(window, 'innerHeight', { configurable: true, value: 962 })
+
+      const refMap = new Map<number, HTMLElement>([[42, el]])
+      highlight(refMap)
+      const overlay = document.querySelector(
+        `#${HIGHLIGHT_CONTAINER_ID} [data-ref-index="42"]`,
+      ) as HTMLElement | null
+      expect(overlay).not.toBeNull()
+      expect(overlay!.style.left).toBe('-17px')
+      unhighlight()
+    },
+  )
+})