Vue3 SPA在GitHub Actions CI中使用Cypress测试路由跳转异常

问题背景 #

测试Vue3单页应用路由时，普通<a>标签跳转在GitHub Actions CI环境中正常，但<router-link>点击后无任何跳转行为，本地（含无头模式）测试完全正常。两种标签最终生成的DOM结构一致，仅路由处理逻辑依赖Vue Router的客户端路由机制不同。

排查方向与解决办法 #

1. 替换硬等待为断言式等待 #

当前使用的cy.wait(10000)是硬等待，完全依赖固定时间，CI环境资源波动时可靠性极低。直接改用Cypress的断言自动等待机制，它会轮询直到条件满足：

cy.get('#id_example_v2').click();
// 删除硬等待，直接断言路由变化
cy.location('pathname').should('include', 'example/example2');
cy.get('a.bg-info').should('be.visible');

2. 确保Vue Router初始化完成后再测试 #

CI环境中应用启动速度较慢，可能点击router-link时Vue Router还未完成初始化。可以在测试前等待Router就绪：

// 在测试开头或beforeEach钩子中添加
cy.window().then(window => {
  // 假设Vue实例挂载在window.app上
  return window.app._instance.setupState.router.isReady();
});

如果无法直接获取Router实例，也可以在App.vue中添加就绪标识：

<template>
  <div v-if="routerReady" data-testid="router-ready"></div>
  <!-- 其他页面内容 -->
</template>

<script setup>
import { onMounted, ref } from 'vue';
import { useRouter } from 'vue-router';

const router = useRouter();
const routerReady = ref(false);

onMounted(async () => {
  await router.isReady();
  routerReady.value = true;
});
</script>

测试中等待该标识出现：

cy.get('[data-testid="router-ready"]').should('exist');

3. 强制触发click事件（绕过事件拦截） #

CI环境的Firefox可能对事件触发的处理逻辑与本地不同，router-link依赖Vue自定义事件处理跳转，试试强制触发事件：

cy.get('#id_example_v2').trigger('click', { force: true });

或者直接调用Router的push方法，跳过DOM点击环节：

cy.window().then(window => {
  window.app._instance.setupState.router.push('/en/example/example2');
});

4. 检查CI环境的路由配置一致性 #

CI环境使用NODE_ENV=test，需确认Vue Router在测试环境下的base路径与本地一致。例如Router配置：

const router = createRouter({
  history: createWebHistory(import.meta.env.VITE_BASE_URL || '/'),
  routes: [...],
});

确保CI环境中VITE_BASE_URL（或你使用的环境变量）与本地配置相同，避免router-link的to路径解析错误。

5. 更换浏览器排查兼容性 #

当前使用firefox-esr，可能与本地Firefox版本差异较大导致兼容性问题，试试换Chrome运行测试：
修改GitHub Actions工作流中的browser: chrome，若问题消失，则是Firefox ESR的兼容性问题，可考虑更换为Firefox正式版，或针对Firefox调整测试逻辑。

6. 利用CI调试工具定位问题 #

Cypress在GitHub Actions中默认会录制测试视频、失败时自动截图，可前往Actions的Artifacts中下载这些文件，查看点击router-link后的页面状态。也可在测试中添加日志：

cy.get('#id_example_v2').then(el => {
  console.log('router-link生成的href:', el.attr('href'));
}).click();
cy.location().then(loc => {
  console.log('当前路径:', loc.pathname);
});

这些日志会出现在Actions的测试输出中，帮助定位具体问题。

内容的提问来源于stack exchange，提问作者glbst