用途：为 Capacitor 应用与插件提供分层测试指南。Capacitor 有三层可测：Web 层（承载大部分逻辑）、原生桥接与插件（Swift/Kotlin）、真机运行的应用。原则是选能捕获该缺陷的最便宜的一层。仅当对应层涉及时才加载相应参考文档。
适用时机：为 Capacitor 应用添加单元、组件或 E2E 测试；在 Vitest/Jest 中模拟 Capacitor 或插件 API；为插件编写或现代化原生单测（Swift Testing、XCTest、JUnit）；在模拟器或设备上验证变更；E2E 在 WebView 中找不到元素；配置 CI 测试任务。不适用于读设备/崩溃日志、Web Inspector 调试、构建签名发布、App Intents 测试等，可转相关技能。
选层建议：业务逻辑、状态、调用插件的服务用 Vitest 加模拟插件；组件用 Testing Library 跑在 Vitest 上；Web 流程（路由、表单）用 Playwright；插件原生代码用 Swift Testing/XCTest 或 JUnit；真机上的完整应用、原生 UI、权限、深链用代理验证循环或 Appium/Maestro；CI 用 GitHub Actions 矩阵。
关键事实：jsdom 中插件会跑其 Web 实现或抛未实现异常，Capacitor.isNativePlatform() 默认返回 false，需模拟 @capacitor/core，模拟应在插件包边界而非应用深处。E2E 工具把 WebView 视为一个原生元素，Appium 需切到 WEBVIEW_* 上下文才能找 DOM；调试构建可检查 WebView，发布构建需在 capacitor.config 开启 ios/android.webContentsDebuggingEnabled，切勿误带发布。Detox 不适用于 Capacitor。Swift Testing 不能完全替代 XCTest，UI 测试（XCUIApplication）与 measure{} 性能测试仍用 XCTest。仅 iOS 的插件包因依赖 UIKit 与 Capacitor，不能用 swift test，改用 xcodebuild test -scheme <Package> -destination。Capacitor 9 移除了废弃 Swift API，旧初始化器需迁移并加 methodName。热重载在 Capacitor 9 用 npx cap run ios --url http://<lan-ip>:5173，Capacitor 8 用 npx cap run ios -l --host <lan-ip> --port 5173。
工作流：先检查 package.json、capacitor.config.* 与现有测试配置；需求笼统时询问目标层并建议覆盖风险的最便宜层；按现有 runner 与风格写测试，不新增第二个 runner；运行并展示输出；影响 UI 的改动跑设备验证循环。
验证命令：Web 层 npx vitest run、npx playwright test；iOS 插件在插件仓库运行 xcodebuild test -scheme <PluginPackageName> -destination "platform=iOS Simulator,..."；Android 插件 cd android && ./gradlew test；应用原生测试 xcodebuild test -project ios/App/App.xcodeproj -scheme App -destination 'platform=iOS Simulator,name=<device>'。报告需含新增测试、运行命令、通过/失败数及本地无法运行的原因。
常见错误处理：Vitest 报插件未在 Web 实现，用 vi.mock('<plugin package>') 放入 setupFiles；模拟被忽略多为路径不符或注册过晚，须模拟应用实际导入的说明符；Appium 找不到 data-testid 需切 WEBVIEW_* 上下文；无 WEBVIEW_* 说明 WebView 不可检查，改用调试构建；chromedriver 版本错误需自动下载或固定匹配版本；swift test 报无 UIKit 模块需改用 xcodebuild test 加模拟器目标；-l 未知选项是 Capacitor 9 CLI 变更；热重载白屏多因 dev server 绑定 localhost，需绑 0.0.0.0 并用同一 Wi-Fi 的 LAN IP。