Panther启动失败主因是环境不匹配：需确保ChromeDriver与Chrome版本一致、显式指定非标路径、Linux/Docker下添加headless参数及共享内存。
Panther 启动浏览器失败：找不到 ChromeDriver 或浏览器路径
默认情况下 Panther 会尝试调用系统 PATH 中的 chromedriver，并自动查找本地安装的 Chrome/Chromium。但多数人遇到的「启动失败」其实不是代码问题，而是环境没对齐。
- 先确认
chromedriver版本与本地 Chrome 版本兼容（例如 Chrome 124 需要chromedriver124.x，不匹配会直接报session not created） - 如果 Chrome 不在标准路径（如 macOS 的
/Applications/Google Chrome.app，Linux 的/usr/bin/google-chrome），必须显式传入：new ChromeBrowserKit(['binary' => '/path/to/chrome']) - Linux 服务器无图形界面时，必须加
--headless=new和--no-sandbox；Docker 环境还需挂载/dev/shm，否则页面加载卡死或报Failed to move to new namespace
waitForElementVisible 一直超时：Selector 写错 or 渲染时机不对
waitForElementVisible 是 Panther 最常被误用的方法之一——它只等元素存在且可见，但不保证内容已渲染完成，也不处理 Vue/React 的异步数据流。
- 别用
id或class直接写死 selector，尤其当组件动态生成 class 名（比如App__button___abc123），优先选[data-testid="submit-btn"]这类稳定属性 - 如果目标是表单提交后的结果页，别在 click 后立刻
waitForElementVisible，先wait(2000)或用waitForText等具体文案更可靠 - Vue Router 的懒加载页面可能触发两次导航，
waitForElementVisible可能命中前一个路由的旧 DOM，建议配合$client->getCurrentURL()校验最终地址
测试中 session 丢失：Panther 默认不共享 Symfony 的 dev cookie
你在浏览器里登录了后台，但用 Panther 访问 /admin/dashboard 却跳转到登录页——这不是认证逻辑问题，而是 Panther 启动的是全新浏览器实例，压根没继承你开发环境的 session cookie。
- 开发阶段最简单的解法：用
$client->setServerParameter('HTTP_COOKIE', $_SERVER['HTTP_COOKIE'] ?? '')把当前请求的 cookie 注入 Panther 客户端（仅限 CLI 启动测试时可用） - 更稳妥的做法是用
$client->request('GET', '/login')模拟登录流程，再提取Set-Cookie响应头手动 setCookie，避免依赖浏览器存储 - 切记不要在测试里硬编码
PHPSESSID，不同环境 session_name 可能不同，应通过ini_get('session.name')动态获取
截图空白 or 元素位置偏移：headless 模式下 viewport 尺寸未设
本地跑得好好的截图，CI 上全是白图或按钮点不到——大概率是 headless Chrome 默认 viewport 太小（800×600），导致响应式布局折叠、JS 判断 window.innerWidth 后隐藏了关键区域。
- 初始化 client 时强制指定尺寸：
new ChromeBrowserKit(['args' => ['--window-size=1920,1080']]') - 截图前加一句
$client->executeScript('window.scrollTo(0, 0)')，防止页面初始滚动位置影响可见性判断 - 若需验证弹窗或 tooltip，记得等
document.body.classList.contains('modal-open')为 true 再操作，纯靠 class 名或display: block容易误判
真正麻烦的从来不是写几行 $client->click()，而是搞清哪一层在拦截事件、哪条 JS 在改 DOM、哪个 cookie 被跨域策略吃了——这些细节不打日志、不看 Network 面板根本绕不过去。
