laravel dusk 本质是封装 facebook webdriver 的 php 客户端，后台启动真实浏览器进行端到端测试，需处理加载延迟、元素可见性等真实环境问题；启动失败主因是 chromedriver 与 chrome 版本不匹配或缺少 gui 环境，ci 中须启用 headless 模式；visit() 后应使用 waitfor() 等显式等待而非直接 see()；动态交互需注意 select/attach 限制，优先用 script() 调用 js；测试间会话共享，需 teardown 时清理 cookies 或 quit 浏览器。
直接说结论：Laravel Dusk 本质是封装了 Facebook WebDriver 的 PHP 客户端，它不运行在浏览器里，而是在后台启动 Chrome 或 Firefox 实例，通过 HTTP 协议控制真实浏览器完成交互和断言——这意味着你写的测试代码必须考虑页面加载延迟、元素可见性、路由跳转时机等真实环境问题，而不是像单元测试那样“秒执行”。
如何正确启动 Dusk 并避免 Facebook\WebDriver\Exception\SessionNotCreatedException
Dusk 启动失败最常见的原因是 ChromeDriver 版本与系统 Chrome 不匹配，或未配置好 DISPLAY（Linux/macOS）或缺少 GUI 环境（CI 场景）。
- 本地开发：确保
chromedriver在$PATH中，且版本与 Chrome 一致（可通过chrome --version和chromedriver --version核对） - CI 环境（如 GitHub Actions）：必须显式安装匹配的 Chrome + ChromeDriver，并启用 headless 模式。Dusk 默认会尝试启动 GUI 浏览器，CI 上会失败
- 在
tests/DuskTestCase.php中修改driver()方法，强制使用 headless 模式：
protected function driver()
{
$options = (new ChromeOptions)->addArguments([
'--disable-gpu',
'--headless',
'--no-sandbox',
'--window-size=1920,1080',
]);
return RemoteWebDriver::create(
'http://localhost:9515',
DesiredCapabilities::chrome()->setCapability(
ChromeOptions::CAPABILITY, $options
)
);
}
注意：http://localhost:9515 是 ChromeDriver 默认监听地址；若用 php artisan dusk:install 下载的驱动未自动启动，需手动运行 chromedriver --port=9515。
visit() 后为什么 see() 总失败？
visit() 只触发导航，不等待页面 DOM 加载完成或 Vue/React 渲染完毕。常见现象是页面已跳转，但元素还没出现，导致 see()、assertSee() 报错 “Element not found”。
- 不要依赖
see()判断文字是否在页面上——它只检查 DOM 文本节点，不处理 CSSdisplay: none或 Vuev-if动态隐藏 - 优先用
waitForText()或waitFor()显式等待关键元素出现：
$browser->visit('/login')
->type('email', 'test@example.com')
->type('password', 'secret')
->press('Login')
->waitFor('#dashboard', 10) // 等待 ID 为 dashboard 的元素在 10 秒内出现
->assertSee('Welcome back');
如果页面由 JS 渲染（如 Inertia / Livewire），还要加 ->pause(500) 或 ->waitUntilMissing('.loading') 避免竞态。
如何对动态表单、下拉选择、文件上传做可靠交互？
Dusk 提供的 select()、attach()、check() 等方法底层靠 CSS 选择器定位，一旦 HTML 结构变化（比如加了 class="form-control" 或用了 Shadow DOM），就会失效。
-
select()要求<select></select>元素必须是原生标签，不能是第三方组件（如 Select2、Vue Multiselect）包裹后的伪下拉 - 文件上传必须用绝对路径：
$browser->attach('avatar', '/absolute/path/to/image.jpg');—— 相对路径会报File not found - 对 JS 组件交互，绕过 Dusk 封装，直接执行 JS 获取状态或触发事件：
$browser->script("document.querySelector('[data-testid=\"submit-btn\"]').click();");
// 或读取 Vue 实例数据（假设挂载在 window.app）
$browser->script("return window.app.$data.form.email"); // 返回当前邮箱值
注意：script() 返回值会被序列化为 JSON，复杂对象可能丢失方法或原型链。
最常被忽略的一点：Dusk 测试默认共享同一个浏览器会话（Session），多个 Browser 实例之间 cookie 和 localStorage 是互通的。如果你在某个测试里登录了用户，下一个测试没显式退出或清理，就可能因缓存状态导致断言误判。务必在 tearDown() 或 afterEach() 中调用 $this->browse(function (Browser $browser) { $browser->driver->manage()->deleteAllCookies(); });，或更彻底地用 $browser->quit() 销毁实例。
