Laravel Dusk安装与运行需严格匹配版本：Laravel 9用^7.0，10.0–10.28用^7.5，10.29+可用默认v8；ChromeDriver须与Chrome主版本一致；CI需配置headless参数及图形环境。
composer require laravel/dusk 安装失败或报错
直接运行 composer require laravel/dusk 在 Laravel 10+ 或 PHP 8.2+ 环境下容易失败，常见错误是 illuminate/support 版本冲突或 php-webdriver/webdriver 依赖解析失败。
根本原因不是 Dusk 本身有问题，而是 Composer 默认会尝试安装最新版 Dusk（如 v8.x），而它要求 Laravel 10.29+ 和 PHP 8.1+；若你用的是 Laravel 9 或旧版，必须指定兼容版本。
- 查清当前 Laravel 版本：
php artisan --version - Laravel 9 → 用
composer require laravel/dusk:^7.0 - Laravel 10.0–10.28 → 用
composer require laravel/dusk:^7.5 - Laravel 10.29+ → 可用
composer require laravel/dusk（默认装 v8） - 安装后务必运行
php artisan dusk:install，否则DuskServiceProvider不会注册，测试类无法识别$this->browse()
php artisan dusk 找不到 ChromeDriver 或启动失败
Dusk 默认依赖本地 Chrome + ChromeDriver，但不自动下载或管理驱动版本。常见现象是报错 Facebook\WebDriver\Exception\WebDriverException: unknown error: cannot find Chrome binary 或 session not created: This version of ChromeDriver only supports Chrome version XX。
关键点：Dusk 的 ChromeDriver 版本必须与系统已安装的 Chrome 主版本严格匹配（如 Chrome 124 → 需 ChromeDriver 124.x）。
- 先确认 Chrome 路径：
which google-chrome（Linux/macOS）或where chrome.exe（Windows） - 检查 Chrome 版本：
google-chrome --version - 手动下载对应 ChromeDriver：chromedriver.chromium.org，解压后放到
tests/Browser/Drivers/目录（需自行创建） - 在
tests/DuskTestCase.php中强制指定路径：protected function driver() { return RemoteWebDriver::create( 'http://localhost:9515', DesiredCapabilities::chrome()->setCapability( 'chromeOptions', ['binary' => '/usr/bin/google-chrome'] ) ); } - 更省事的做法：改用
laravel/dusk内置的ChromeDriver::install()（v7.5+ 支持），在tests/DuskTestCase.php的prepare()方法里调用一次即可
测试中 $this->browse() 闭包内元素找不到或点击无效
典型表现是 $browser->click('@login-button') 报 Facebook\WebDriver\Exception\NoSuchElementException，或点击后无反应——不是选择器写错，而是页面没加载完、JS 还没挂载、或元素被 Vue/React 异步渲染延迟。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
Dusk 的等待机制默认只等 DOM 存在，不等 JS 渲染完成或组件就绪。
- 别只靠
->waitFor('@selector')，优先用更稳的条件：->waitForText('欢迎回来')或->waitForLocation('/dashboard') - Vue 场景下，加
->pause(500)比盲目->waitFor('.vue-component')更可靠（尤其开发环境未启用 SSR） - 避免用 CSS 类名做断言（易变），改用
data-testid属性：<button data-testid="submit-btn">→$browser->click('[data-testid="submit-btn"]') - 表单提交后立即断言 URL，比断言页面文本更快：
->assertPathIs('/success')
Dusk 测试在 CI（GitHub Actions / GitLab CI）上跑不起来
本地能过，CI 报 Failed to connect to localhost port 9515 或 no DISPLAY variable，本质是缺少图形环境和 Chrome 二进制。
CI 不是“没装 Chrome”，而是没装带 sandbox 权限的稳定版 Chrome，也常忽略 --headless=new 参数变更。
- GitHub Actions 推荐用
shymean/laravel-dusk-action或显式安装：- uses: browser-actions/setup-chrome@v1 with: chrome-version: 'stable' - GitLab CI 需在
.gitlab-ci.yml中加：before_script: - apt-get update && apt-get install -y google-chrome-stable - export CHROME_BIN=/usr/bin/google-chrome
- 所有 CI 必须加 Chrome 启动参数：
ChromeOptions::class中添加--no-sandbox --disable-dev-shm-usage --headless=new --disable-gpu - 别信“Dusk 自动适配 headless”——Laravel 10.25+ 才默认用
--headless=new，旧版仍用--headless，CI 上会静默失败
Dusk 的坑不在语法，而在环境链路太长：Composer 版本、Chrome 主版本、ChromeDriver 小版本、PHP 运行时、CI 的图形栈、前端框架的渲染节奏——任意一环错位，错误信息都指向“元素没找到”，实际得倒查三层。
