Laravel Dusk自动化测试教程详解

本文深入剖析了 Laravel Dusk 自动化测试中高频报错的根本原因——并非测试代码逻辑有误，而是环境配置三大关键点未对齐：ChromeDriver 与 Chrome 主版本必须严格一致（尤其注意 M 系列芯片需 arm64 架构）、APP_URL 必须完整包含协议和端口且严禁尾部斜杠（Dusk 完全忽略 php artisan serve 地址）、以及 visit() 后必须用 waitFor 等待 JS 渲染完成而非直接 assertSee；同时补充了 CI 环境下的 headless 新参数配置、Chrome 预装要点及测试间状态残留（cookie/localStorage/浏览器实例）的清理方案，帮你从“跑不通”一步到位走向“稳准快”的端到端测试实践。

跑 php artisan dusk 报错、页面白屏、元素点不了、断言总超时——这些问题基本都卡在 ChromeDriver 版本、APP_URL 配置、JS 渲染时机这三处，不是测试逻辑写错了，而是环境没对齐。

ChromeDriver 与 Chrome 主版本必须严格匹配

报 SessionNotCreatedException 或 unknown error: cannot find Chrome binary，90% 是版本不一致。Chrome 124 就得配 chromedriver 124.x，小版本号（如 124.0.6367.78）不同可接受，主版本号必须一致。

• 查 Chrome 版本：google-chrome --version（Linux/macOS）或 chrome.exe --version（Windows）
• 查 chromedriver 版本：chromedriver --version；若提示 command not found，说明没装或不在 $PATH
• php artisan dusk:install 默认把驱动放进 tests/Browser/Drivers/，但 Dusk 只认 $PATH 里的，除非你手动指定路径
• Mac M 系列用户务必下载 arm64 架构的 chromedriver，x86_64 会静默失败
• 临时验证：进 tests/Browser/Drivers/ 目录，给 chromedriver 加执行权限：chmod +x chromedriver

APP_URL 必须带协议、端口，且不能以斜杠结尾

Dusk 完全不读 php artisan serve 的地址，只认 .env 里的 APP_URL。写成 APP_URL=http://localhost 就会跳到 http://localhost/login，而你的服务实际跑在 :8000，必然 404。

• 本地开发推荐写：APP_URL=http://127.0.0.1:8000（避免 DNS 解析延迟）
• Valet 用户必须写完整域名：APP_URL=https://yourapp.test，并确保该域名能被 Chrome 正常访问（valet secure 后还要信任证书）
• 改完立刻清缓存：php artisan config:clear，否则底层 HTTP 客户端可能读旧值
• 不要加末尾斜杠：APP_URL=http://127.0.0.1:8000/ → 错误

visit() 后不能直接 assertSee()，必须显式等待

visit() 只发导航请求，不等 DOMContentLoaded，更不等 Vue/React 挂载、AJAX 返回、CSS 动画结束。此时 assertSee() 查的是空壳 DOM，必败。

• 优先用 ->waitForText('登录') 或 ->waitFor('.submit-btn', 10)（单位秒），而不是 assertSee()
• assertSee() 区分大小写，且过滤 display: none、visibility: hidden 的文本；若文字在 modal 或 tooltip 里，得先触发再断言
• 异步内容（如 Inertia 页面）建议加 ->script('return window.appReady || false') 等前端就绪信号
• 调试时加 ->dump()->pause()，看真实 DOM 快照，比猜快得多

CI 环境必须启用 --headless=new 并预装 Chrome

GitHub Actions / GitLab CI 默认无图形界面，Dusk 尝试启动 GUI Chrome 必然卡死或报 UnknownErrorException。光加 --headless 不够，Chrome 112+ 已废弃旧参数。

• 必须用 --headless=new（Chrome 116+ 推荐），同时加 --no-sandbox、--disable-dev-shm-usage
• CI 中需显式安装 Chrome：uses: browser-actions/setup-chrome@latest（GitHub Actions）或 apt-get install chromium-browser（Ubuntu）
• Linux 上若 Chrome 路径不是默认，要在 tests/DuskTestCase.php 的 driver() 方法里用 $options->setBinary('/usr/bin/chromium-browser') 指定
• 别依赖 php artisan dusk:install 自动拉驱动——CI 里最好用 ChromeDriver::install()（v7.5+ 支持）在 prepare() 里调用一次

最易忽略的其实是“测试间状态残留”：cookie、localStorage、浏览器实例没清理，会导致后续测试行为异常。Dusk 默认不自动 quit 浏览器，tearDown() 里得自己处理，或者用 ->driver()->quit() 显式关闭。

今天关于《Laravel Dusk自动化测试教程详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！