e2e 测试框架入门避坑指南新手最常遇到的 6 个初始化问题【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e是一个面向 Web 与移动应用的下一代端到端测试框架你用一句自然语言描述目标AI 智能体就会驱动你的应用完成操作再用定位器和断言在同一个测试里检查结果。但很多新手卡在初始化这一步——装完依赖、写好配置e2e run却报了一串看不懂的错误码。这篇 e2e 测试框架入门避坑指南带你一次绕开新手最常踩的6 个初始化坑从 Node.js 版本到模型登录、从应用启动到 Next.js 16 跨域每个问题都给出快速定位方法和解法。想动手试试把仓库拉到本地即可git clone https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 初始化能自动做什么在应用目录下执行下面一条命令就是 e2e 安装初始化的入口npx e2e init # npmpnpm 用户用 pnpm dlx e2e initbun 用户用 bunx e2e init向导会问你两件事引擎Web 还是 Mobile和模型提供方订阅、API key或不带 AI 的 None。完成后它会自动写入 e2e.config.ts 风格的配置文件与示例测试 tests/example.e2e.ts、在package.json里加上test:e2e脚本并把.e2e/目录加入.gitignore——已有文件不会被破坏。两个引擎的定位引擎驱动方式目标应用配置WebPlaywrightChromium / Firefox / WebKit 浏览器必填app.urlMobileiOS/Android模拟器 / 模拟器上的真机agent-device必填app.bundleId或app.appPathWeb 测试里你还可以在配置里声明app.command让 e2e 自动拉起开发服务器、等它就绪、跑完自动停掉省得手动开终端。下面进入正题新手 e2e 初始化时最容易翻车的 6 个坑。坑 1Node.js 版本不达标CLI 直接罢工症状刚运行npx e2e init或npx e2e run就报NODE_UNSUPPORTED进程以退出码 2/3 结束。原因e2e 用内置 TypeScript loader 运行你的.ts配置和测试要求Node.js 24.8Node 22 分支需22.22.3Bun、Deno 目前不支持。版本不满足时CLI 在启动前就会检查并终止。解决用node -v查看版本用 nvm 升级到 24.xWindows 用户请在WSL里运行不要在原生 PowerShell 里硬跑移动端测试还有额外要求macOS 装 Xcode 并含 iOS 模拟器运行时或 Android SDK 加模拟器先跑一次npx agent-device doctor自检。坑 2引擎选错或配置字段对不上报 INVALID_CONFIG症状配置一加载就报INVALID_CONFIG消息里点出某个键名。原因e2e 的配置是严格键——配置工厂拒绝不认识的键目标里app的字段也各归各Web 目标必须写app.url写成app.baseUrl、把 url 塞进web({ url })这类旧式写法都会被拒绝移动端目标必须写app.bundleId包名/应用名或app.appPath.app/.apk目前不支持app.url没有services键数据库、mock 等依赖进程需要在运行前自己拉起或写进app.command的启动脚本里。解决照着向导生成的 e2e.config.ts 改只改值、不造键改完看报错消息里最近似键名的提示它会告诉你该用哪个正确的键。更多字段说明见 docs/starting-your-app.mdx 和 docs/reference/config.mdx。坑 3模型没配好agent 步骤报 MODEL_UNAVAILABLE症状示例测试跑通了它不含 AI一写agent.act(...)就报MODEL_UNAVAILABLE或者登录了订阅却仍提示无模型。原因内置 agent 的每一步都需要模型常见三种漏配向导选了None之后却没再配置模型选了订阅但没有跑完登录——订阅用户必须在终端执行对应登录命令并走完浏览器/设备码流程用 API key但没装 provider 包或 key 没设在运行 e2e 的那个终端里AI_GATEWAY_API_KEY、OPENROUTER_API_KEY、OPENAI_API_KEY等由 provider 包各自读取runner 不代读。解决# 订阅登录四选一之后用 npx e2e models 查看可用模型 id npx e2e login openai # ChatGPT Plus / Pro npx e2e login github-copilot # GitHub Copilot可复用 gh CLI 登录 npx e2e login opencode-console # OpenCode Console npx e2e login spacexai # SuperGrok / X Premium用 API key 的话安装对应包内置 agent 无论哪家 provider 都需要ai包并把 key 写进终端环境变量。订阅登录、key 配置与本地模型端点的完整选项见 docs/models.mdx 和 docs/subscriptions.mdx。坑 4Next.js 16 开发服务器跨域页面看着在、点不动症状定位器找得到元素、点击也落下去了但 React 的事件处理器一个都不触发测试失败重试次次同样失败——像是鬼压床。原因这是 Next.js 16 开发服务器的新行为它会拦截跨源对开发资源的请求。当next dev自认为运行在localhost而你的测试目标打开的却是127.0.0.1或[::1]时页面能渲染、却永远不会水合hydrate。解决把目标实际打开的主机名加进next.config.ts的allowedDevOriginsconst nextConfig: NextConfig { allowedDevOrigins: [127.0.0.1], // 目标是 [::1] 时再补一条 [::1] };目标直接用localhost则无需配置生产环境next start也不受影响。该坑的完整说明见 docs/starting-your-app.mdx。坑 5应用没起来 / 端口冲突APP_UNREACHABLE 与 APP_ALREADY_RUNNING症状报APP_UNREACHABLE应用 60 秒内没就绪、或启动命令提前退出或报APP_ALREADY_RUNNINGapp.url在 runner 拉起命令前就已经能响应了。原因与解决两条路线任选手动启动先自己把开发服务器跑在app.url指向的地址上再执行测试。新手最常在这里忘了开服务器让 runner 启动推荐本地与 CI 都自洽在e2e.config.ts里声明app.commandrunner 会派生进程、轮询就绪、结束后自动停掉。注意两点子进程只继承PATH、HOME等基础变量模型密钥与DATABASE_URL之类必须通过command.env显式传入配上log: .e2e/logs/app.log启动报错时报告里会带上最后 20 行日志不配的话服务器悄悄死掉根本看不到原因。端口被占时本地可以设reuseExisting: true复用已在运行的服务器CI 会忽略该选项或者更优雅——把app.url写成http://127.0.0.1:0让 runner 自动挑空闲端口再用{port}占位符传给args和envlocalhost:0是不允许的。细节见 docs/starting-your-app.mdx。坑 6配置文件位置或形态不对CONFIG_NOT_FOUND / CONFIG_AMBIGUOUS症状报CONFIG_NOT_FOUND找不到配置、CONFIG_AMBIGUOUS同一目录同时存在e2e.config.ts和e2e.config.mts或CONFIG_LOAD_FAILED配置模块导入失败声明了但没装包、子路径写错、导出被移除等。原因runner 从当前目录一路向上找e2e.config.ts/e2e.config.mts直到仓库根目录只认这两个文件之一且配置要export default ... satisfies E2EConfig导出。解决确认在项目根目录执行命令确认e2e.config.ts确实存在没跑过npx e2e init或手动删掉过就会缺文件两个文件都存在就删掉一个CONFIG_LOAD_FAILED时消息会直接点名缺的依赖或错的子路径照做即可——典型情况是换了机器后没重新npm install。初始化排错速查先看退出码每次运行都有退出码它能帮你 10 秒内判断该改什么退出码含义该做什么1测试用例失败读断言/定位器报错2配置、收集或策略问题先修报告里点名的配置3引擎、应用进程、模型供应商或产物失败判断原因是否临时性再重试4runner 内部错误反馈给项目130运行被中断—完整错误码对照表见 docs/reference/errors.mdx失败报告的读法截图、trace、模型对话见 docs/debugging.mdx所有环境变量见 docs/reference/environment.mdx。初始化完成的标志自检清单✅npx e2e run tests/example.e2e.ts跑通✅package.json里已有test:e2e: e2e run脚本✅.gitignore已包含.e2e/输出目录init 会自动加。达到以上三点初始化就算真正完成可以放心开始写自己的第一个业务测试了。延伸阅读快速上手docs/quickstart.mdx启动被测应用docs/starting-your-app.mdx模型与订阅docs/models.mdx、docs/subscriptions.mdx错误码与调试docs/reference/errors.mdx、docs/debugging.mdx官方 skill 文档可喂给编码代理skills/e2e/SKILL.md完整示例工程examples/README.mdVite、Next.js、Expo、SwiftUI 四套独立项目各带一套通过测试的示例【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
e2e 测试框架入门避坑指南新手最常遇到的 6 个初始化问题【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e是一个面向 Web 与移动应用的下一代端到端测试框架你用一句自然语言描述目标AI 智能体就会驱动你的应用完成操作再用定位器和断言在同一个测试里检查结果。但很多新手卡在初始化这一步——装完依赖、写好配置e2e run却报了一串看不懂的错误码。这篇 e2e 测试框架入门避坑指南带你一次绕开新手最常踩的6 个初始化坑从 Node.js 版本到模型登录、从应用启动到 Next.js 16 跨域每个问题都给出快速定位方法和解法。想动手试试把仓库拉到本地即可git clone https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 初始化能自动做什么在应用目录下执行下面一条命令就是 e2e 安装初始化的入口npx e2e init # npmpnpm 用户用 pnpm dlx e2e initbun 用户用 bunx e2e init向导会问你两件事引擎Web 还是 Mobile和模型提供方订阅、API key或不带 AI 的 None。完成后它会自动写入 e2e.config.ts 风格的配置文件与示例测试 tests/example.e2e.ts、在package.json里加上test:e2e脚本并把.e2e/目录加入.gitignore——已有文件不会被破坏。两个引擎的定位引擎驱动方式目标应用配置WebPlaywrightChromium / Firefox / WebKit 浏览器必填app.urlMobileiOS/Android模拟器 / 模拟器上的真机agent-device必填app.bundleId或app.appPathWeb 测试里你还可以在配置里声明app.command让 e2e 自动拉起开发服务器、等它就绪、跑完自动停掉省得手动开终端。下面进入正题新手 e2e 初始化时最容易翻车的 6 个坑。坑 1Node.js 版本不达标CLI 直接罢工症状刚运行npx e2e init或npx e2e run就报NODE_UNSUPPORTED进程以退出码 2/3 结束。原因e2e 用内置 TypeScript loader 运行你的.ts配置和测试要求Node.js 24.8Node 22 分支需22.22.3Bun、Deno 目前不支持。版本不满足时CLI 在启动前就会检查并终止。解决用node -v查看版本用 nvm 升级到 24.xWindows 用户请在WSL里运行不要在原生 PowerShell 里硬跑移动端测试还有额外要求macOS 装 Xcode 并含 iOS 模拟器运行时或 Android SDK 加模拟器先跑一次npx agent-device doctor自检。坑 2引擎选错或配置字段对不上报 INVALID_CONFIG症状配置一加载就报INVALID_CONFIG消息里点出某个键名。原因e2e 的配置是严格键——配置工厂拒绝不认识的键目标里app的字段也各归各Web 目标必须写app.url写成app.baseUrl、把 url 塞进web({ url })这类旧式写法都会被拒绝移动端目标必须写app.bundleId包名/应用名或app.appPath.app/.apk目前不支持app.url没有services键数据库、mock 等依赖进程需要在运行前自己拉起或写进app.command的启动脚本里。解决照着向导生成的 e2e.config.ts 改只改值、不造键改完看报错消息里最近似键名的提示它会告诉你该用哪个正确的键。更多字段说明见 docs/starting-your-app.mdx 和 docs/reference/config.mdx。坑 3模型没配好agent 步骤报 MODEL_UNAVAILABLE症状示例测试跑通了它不含 AI一写agent.act(...)就报MODEL_UNAVAILABLE或者登录了订阅却仍提示无模型。原因内置 agent 的每一步都需要模型常见三种漏配向导选了None之后却没再配置模型选了订阅但没有跑完登录——订阅用户必须在终端执行对应登录命令并走完浏览器/设备码流程用 API key但没装 provider 包或 key 没设在运行 e2e 的那个终端里AI_GATEWAY_API_KEY、OPENROUTER_API_KEY、OPENAI_API_KEY等由 provider 包各自读取runner 不代读。解决# 订阅登录四选一之后用 npx e2e models 查看可用模型 id npx e2e login openai # ChatGPT Plus / Pro npx e2e login github-copilot # GitHub Copilot可复用 gh CLI 登录 npx e2e login opencode-console # OpenCode Console npx e2e login spacexai # SuperGrok / X Premium用 API key 的话安装对应包内置 agent 无论哪家 provider 都需要ai包并把 key 写进终端环境变量。订阅登录、key 配置与本地模型端点的完整选项见 docs/models.mdx 和 docs/subscriptions.mdx。坑 4Next.js 16 开发服务器跨域页面看着在、点不动症状定位器找得到元素、点击也落下去了但 React 的事件处理器一个都不触发测试失败重试次次同样失败——像是鬼压床。原因这是 Next.js 16 开发服务器的新行为它会拦截跨源对开发资源的请求。当next dev自认为运行在localhost而你的测试目标打开的却是127.0.0.1或[::1]时页面能渲染、却永远不会水合hydrate。解决把目标实际打开的主机名加进next.config.ts的allowedDevOriginsconst nextConfig: NextConfig { allowedDevOrigins: [127.0.0.1], // 目标是 [::1] 时再补一条 [::1] };目标直接用localhost则无需配置生产环境next start也不受影响。该坑的完整说明见 docs/starting-your-app.mdx。坑 5应用没起来 / 端口冲突APP_UNREACHABLE 与 APP_ALREADY_RUNNING症状报APP_UNREACHABLE应用 60 秒内没就绪、或启动命令提前退出或报APP_ALREADY_RUNNINGapp.url在 runner 拉起命令前就已经能响应了。原因与解决两条路线任选手动启动先自己把开发服务器跑在app.url指向的地址上再执行测试。新手最常在这里忘了开服务器让 runner 启动推荐本地与 CI 都自洽在e2e.config.ts里声明app.commandrunner 会派生进程、轮询就绪、结束后自动停掉。注意两点子进程只继承PATH、HOME等基础变量模型密钥与DATABASE_URL之类必须通过command.env显式传入配上log: .e2e/logs/app.log启动报错时报告里会带上最后 20 行日志不配的话服务器悄悄死掉根本看不到原因。端口被占时本地可以设reuseExisting: true复用已在运行的服务器CI 会忽略该选项或者更优雅——把app.url写成http://127.0.0.1:0让 runner 自动挑空闲端口再用{port}占位符传给args和envlocalhost:0是不允许的。细节见 docs/starting-your-app.mdx。坑 6配置文件位置或形态不对CONFIG_NOT_FOUND / CONFIG_AMBIGUOUS症状报CONFIG_NOT_FOUND找不到配置、CONFIG_AMBIGUOUS同一目录同时存在e2e.config.ts和e2e.config.mts或CONFIG_LOAD_FAILED配置模块导入失败声明了但没装包、子路径写错、导出被移除等。原因runner 从当前目录一路向上找e2e.config.ts/e2e.config.mts直到仓库根目录只认这两个文件之一且配置要export default ... satisfies E2EConfig导出。解决确认在项目根目录执行命令确认e2e.config.ts确实存在没跑过npx e2e init或手动删掉过就会缺文件两个文件都存在就删掉一个CONFIG_LOAD_FAILED时消息会直接点名缺的依赖或错的子路径照做即可——典型情况是换了机器后没重新npm install。初始化排错速查先看退出码每次运行都有退出码它能帮你 10 秒内判断该改什么退出码含义该做什么1测试用例失败读断言/定位器报错2配置、收集或策略问题先修报告里点名的配置3引擎、应用进程、模型供应商或产物失败判断原因是否临时性再重试4runner 内部错误反馈给项目130运行被中断—完整错误码对照表见 docs/reference/errors.mdx失败报告的读法截图、trace、模型对话见 docs/debugging.mdx所有环境变量见 docs/reference/environment.mdx。初始化完成的标志自检清单✅npx e2e run tests/example.e2e.ts跑通✅package.json里已有test:e2e: e2e run脚本✅.gitignore已包含.e2e/输出目录init 会自动加。达到以上三点初始化就算真正完成可以放心开始写自己的第一个业务测试了。延伸阅读快速上手docs/quickstart.mdx启动被测应用docs/starting-your-app.mdx模型与订阅docs/models.mdx、docs/subscriptions.mdx错误码与调试docs/reference/errors.mdx、docs/debugging.mdx官方 skill 文档可喂给编码代理skills/e2e/SKILL.md完整示例工程examples/README.mdVite、Next.js、Expo、SwiftUI 四套独立项目各带一套通过测试的示例【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
