Floating-UI 中 useFocus 钩子导致测试失败的解决方案

问题背景

在使用 Floating-UI 构建工具提示组件时，开发者发现从 0.26.1 版本开始，测试环境中会出现工具提示无法正常显示的问题。这个问题特别出现在通过键盘 Tab 键聚焦触发元素时，工具提示应该显示但实际上没有显示的情况。

技术分析

问题根源

经过深入排查，发现问题出在 useFocus 钩子的实现上。具体来说，在 0.26.1 版本中引入了一个 visibleOnly 选项，该选项会检查元素是否通过 :focus-visible 伪类获得焦点。

在测试环境中，jsdom 使用 nwsapi 库来解析 CSS 选择器。最新版本的 nwsapi (2.2.18) 在处理 :focus-visible 选择器时不会抛出错误，而是返回 false，这导致 onFocus 回调提前返回，最终使得工具提示无法显示。

版本对比

• 0.26.0 及更早版本：在测试环境中工作正常
• 0.26.1 及之后版本：测试环境中出现工具提示显示问题

解决方案

临时解决方案

目前最直接的解决方案是在使用 useFocus 钩子时设置 visibleOnly: false 选项：

useFocus(context, {
  visibleOnly: false,
  // 其他配置...
});

这个设置会绕过 :focus-visible 的检查，确保在测试环境中工具提示能够正常显示。

长期解决方案

对于库的维护者来说，可能需要考虑：

1. 改进测试环境下的 :focus-visible 处理逻辑
2. 提供更明确的测试环境检测机制
3. 在文档中明确说明测试环境下的特殊配置需求

最佳实践建议

对于使用 Floating-UI 的开发者，建议：

1. 在测试环境中明确设置 visibleOnly: false
2. 为工具提示组件编写专门的测试用例
3. 考虑使用 jest-environment-jsdom 的特定版本来控制选择器行为
4. 在 CI/CD 流程中加入针对工具提示功能的端到端测试

总结

Floating-UI 是一个强大的 UI 定位库，但在测试环境中可能会遇到一些特殊的行为差异。理解这些差异的根本原因并采取适当的配置调整，可以帮助开发者构建更可靠的测试套件。通过本文的分析和解决方案，开发者应该能够更好地处理类似测试环境下的交互问题。