mcpField
C
capacitor-testing

capacitor-testing

github.com/cap-go测试与质量731.3k 次安装2 周前更新
代码仓库

关于 capacitor-testing

这项测试技能面向 Capacitor 应用和插件开发者，涵盖 Web、原生桥接及设备测试，帮助选择合适的测试层，并指导模拟、原生测试、端到端测试和 CI。

主要功能

  1. 01选择测试层的指导
  2. 02使用 Vitest 模拟插件
  3. 03Web 流程与组件测试
  4. 04Swift 和 Kotlin 插件测试
  5. 05设备验证与 CI 指导

适用场景

  1. 01为 Capacitor 应用添加测试
  2. 02在 Web 测试中模拟插件 API
  3. 03测试原生插件代码
  4. 04验证应用在设备上的行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-testing

安装后在 Claude Code 中输入/capacitor-testing确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

metadata.json
references/
ci.md
device-verification-loop.md
e2e.md
native-plugin-tests.md
web-unit-tests.md

详细介绍

测试 Capacitor 应用和插件

Capacitor 应用有三个测试层：Web 应用（大部分逻辑）、原生桥接和插件（Swift/Kotlin），以及设备上运行的应用。选择能捕获该 Bug 的成本最低的层。

适用场景

在以下情况下使用：

  • 为 Capacitor 应用添加单元测试、组件测试或端到端测试
  • 在 Vitest / Jest 中模拟 Capacitor 或插件 API
  • 为插件编写或更新原生单元测试（Swift Testing、XCTest、JUnit）
  • 在模拟器、仿真器或设备上验证更改（“测试一下”“能正常工作吗”“在设备上检查”）
  • 端到端测试无法在应用中找到 Web 元素（WebView 上下文）
  • 在 CI 中设置测试作业

以下情况不使用：

  • 读取设备或崩溃日志：ios-android-logs
  • Safari Web Inspector / Chrome DevTools 调试：debugging-capacitor
  • 构建、签名和发布流水线：capacitor-ci-cd
  • App Intents 测试：capacitor-app-intents（AppIntentsTesting）

选择测试层

更改内容测试方式参考资料
业务逻辑、状态、调用插件的服务使用模拟插件的 Vitestreferences/web-unit-tests.md
组件（React、Vue、Angular、Svelte）使用 Vitest 上的 Testing Libraryreferences/web-unit-tests.md
Web 工作流（路由、表单）使用 Playwright 测试开发服务器或 distreferences/e2e.md
插件原生代码（Swift / Kotlin）Swift Testing 或 XCTest；JUnitreferences/native-plugin-tests.md
设备上的完整应用、原生 UI、权限、深层链接Agent 验证循环；使用 Appium 或 Maestro 编写可重复运行的测试套件references/device-verification-loop.md、references/e2e.md
CI 作业GitHub Actions 矩阵references/ci.md

仅在涉及相应测试层时才加载参考资料。

有助于节省时间的信息

  • 在 jsdom 中运行的插件会执行其 Web 实现，如果没有 Web 实现，则会抛出 unimplemented。除非模拟 @capacitor/core，否则 Capacitor.isNativePlatform() 在测试中会返回 false。应在插件包边界进行模拟，而不是深入应用内部模拟。
  • 端到端测试工具会将 WebView 视为一个原生元素。 Appium 必须切换到 WEBVIEW_* 上下文才能查找 DOM 元素。Capacitor 会在调试构建中允许检查 WebView；对于发布构建，请在 capacitor.config 中设置 ios.webContentsDebuggingEnabled / android.webContentsDebuggingEnabled。切勿因疏忽而在启用该设置的情况下发布应用。
  • 不能使用 Detox。 它面向 React Native，无法驱动 Capacitor WebView 内容。
  • Swift Testing 不能取代所有 XCTest。 UI 测试（XCUIApplication）和 measure {} 性能测试仍需使用 XCTest。单元测试可以逐个类迁移；同一个文件可以同时包含两者。
  • 仅支持 iOS 的插件包不能使用 swift test，因为它们依赖 UIKit 和 Capacitor。请运行 xcodebuild test -scheme <Package> -destination 'platform=iOS Simulator,...'。
  • Capacitor 9 移除了已弃用的 Swift API。 使用旧版 CAPPluginCall(callbackId:options:success:error:) 初始化器或 CAPPlugin(bridge:pluginId:pluginName:) 来构建调用的测试，必须改用 CAPPluginCall(callbackId:methodName:options:success:error:) 和普通的 init()。
  • Capacitor 9 更改了实时重载标记。 Capacitor 9：npx cap run ios --url http://<lan-ip>:5173。Capacitor 8：npx cap run ios -l --host <lan-ip> --port 5173。Ionic CLI 的 ionic cap run ios -l --external 是另一种工具。

工作流

  1. 检查。 阅读 package.json（测试运行器、框架、@capacitor/* 版本）、capacitor.config.*、现有测试配置（vitest.config.*、playwright.config.*、wdio.conf.*、.maestro/），如果是插件，还要检查 Package.swift、podspec、ios/Tests/、android/src/test/。
  2. 询问 如果请求比较笼统，询问用户想测试哪个层级。建议选择能覆盖风险的最低成本方案。
  3. 编写测试，使用匹配的参考资料。遵循项目现有的测试运行器和风格；不要添加第二个测试运行器。
  4. 运行测试并展示输出。未运行的测试不算完成。
  5. 对于会影响 UI 的更改，运行设备验证循环（references/device-verification-loop.md），并报告截图和发现。

验证

# Web layer
npx vitest run
npx playwright test

# Plugin, iOS (from the plugin repo)
xcodebuild test -scheme <PluginPackageName> \
  -destination "platform=iOS Simulator,name=$(xcrun simctl list devices available | grep -m1 -o 'iPhone [^(]*' | sed 's/ *$//')"

# Plugin, Android (from the plugin repo)
cd android && ./gradlew test

# App native tests, if the app has a test target
xcodebuild test -project ios/App/App.xcodeproj -scheme App -destination 'platform=iOS Simulator,name=<device>'
# CocoaPods projects: -workspace ios/App/App.xcworkspace

报告：添加的测试、运行的命令、通过／失败数量，以及本地无法运行的内容（没有模拟器、没有设备、缺少 Android SDK）。

错误处理

症状原因修复方法
在 Vitest 中出现 "<Plugin>" plugin is not implemented on web在 jsdom 中运行了真实插件在 setup 文件中使用 vi.mock('<plugin package>')
Mock 被忽略，仍调用真实插件Mock 路径与导入路径不同，或 Mock 注册晚于导入Mock 应用导入的确切说明符。在 setupFiles 中或测试文件顶部添加 vi.mock
Appium 找不到 data-testid 元素仍处于 NATIVE_APP 上下文等待 getContexts() 列出 WEBVIEW_* 条目后，执行 await driver.switchContext(webviewContext)
没有 WEBVIEW_* 上下文WebView 不可检查（发布构建）使用调试构建，或仅为测试构建启用 webContentsDebuggingEnabled
Android WebView 上下文因 chromedriver 版本错误而失败Chromedriver 与设备上的 WebView 不匹配启用 Appium 的 chromedriver 自动下载（这是一项不安全的功能标志），或指定匹配的 chromedriver；参阅 Appium UiAutomator2 文档
No such module 'Testing'Xcode 版本过旧Swift Testing 需要 Xcode 16+ 工具链。Capacitor 9 无论如何都需要 Xcode 27
swift test 出现 error: no such module 'UIKit'在 macOS 主机构建 iOS 软件包使用 xcodebuild test，并指定 iOS Simulator 目标
'init(callbackId:options:success:error:)' is deprecated／不可用测试辅助工具版本过旧添加 methodName:
实时重载：error: unknown option '-l'Capacitor 9 CLI使用 --url http://<lan-ip>:<port>
实时重载应用显示空白页开发服务器绑定到 localhost，或 IP 地址错误绑定到 0.0.0.0（Vite：--host），使用局域网 IP，并确保连接同一 Wi-Fi

相关技能

  • debugging-capacitor：检查 WebView 和原生调试器
  • ios-android-logs：在设备运行期间流式查看日志
  • capacitor-ci-cd：构建和发布流水线
  • capacitor-ios-resizability：设备运行期间调整窗口大小时的检查要点
  • capacitor-plugin-upgrade-v8-to-v9：会影响测试辅助工具的插件 API 移除项

评论

支持 Markdown