前言¶
React Native 應用在真機與模擬器上的端到端測試，往往要同時處理 Jest 用例結構、Detox 的 element(by.id()) 選擇器、.detoxrc.js 構建配置，以及 iOS/Android 各自的 build 命令。手寫樣板容易漏掉 Detox 的同步機制或誤用 waitFor 輪詢。下面介紹 TestMu AI 維護的 detox-skill：在對話裏提到 Detox、RN E2E 或 device.launchApp 時，Agent 按該 Skill 中的模式生成 JavaScript/TypeScript 測試與配置，面向本地模擬器/仿真器，也可按文檔對接 TestMu AI 雲執行。
這是什麼¶
detox-skill 是 LambdaTest agent-skills 倉庫 下的 Agent Skill（SKILL.md 格式，MIT 許可，metadata 版本 1.0）。定位是：爲 React Native 應用生成 Detox 灰盒 E2E 測試；Detox 在 RN 社區裏是常用的原生驅動 E2E 方案，帶自動同步，減少手寫等待。
維護方在 metadata 中標註爲 TestMu AI（LambdaTest 體系）。Skill 自述的觸發場景包括：Detox、React Native E2E、React Native test、element(by.id)、device.launchApp 等關鍵詞。
核心功能¶
資料中寫明的能力可歸納爲以下幾類（均來自官方 Skill 正文，非外推）。
測試結構與生命週期
describe/it組織用例；beforeAll裏device.launchApp()，beforeEach裏device.reloadReactNative()，避免每個用例重複冷啓動。- 登錄等流程示例：通過
testID定位輸入框與按鈕，typeText、tap，再用expect(...).toBeVisible()/toHaveText斷言。
元素定位（Matchers）
- 優先
element(by.id('...'))（對應組件testID）。 - 另支持
by.text、by.label、by.type、by.traits；組合withDescendant/withAncestor；多匹配時用atIndex(n)。
交互與斷言
- Actions：
tap、longPress、multiTap、typeText、replaceText、clearText、scroll、scrollTo、swipe、tapReturnKey等。 - Expectations：
toBeVisible、not.toBeVisible、toExist、toHaveText、toHaveToggleValue、toHaveValue。
設備控制
launchApp({ newInstance: true })、reloadReactNative、sendToHome、terminateApp、installApp、shake、setLocation、setURLBlacklist等。
反模式對照
Skill 用表格強調：不要到處 waitFor().withTimeout()，應信任 Detox 自動同步；組件應加 testID；避免每個測試都 launchApp()；不要用手動 delay。
項目配置
- 提供完整的
.detoxrc.js示例：testRunner指向e2e/jest.config.js，apps下ios.debug/android.debug的binaryPath與build命令，devices（如iPhone 16、Pixel_7_API_34AVD），以及configurations映射。 - React Native 側需在控件上設置
testID（文檔給出TextInput、Button、Text示例）。
本地與雲端
- 本地：
detox build/detox test配合ios.sim.debug、android.emu.debug等 configuration。 - 雲端：Detox 生成原生測試運行器（Android Espresso、iOS XCUITest）；文檔給出在 TestMu AI 上上傳 APK/IPA、調用
mobile-api.lambdatest.com的 Espresso / XCUITest build 接口的步驟（需LT_USERNAME、LT_ACCESS_KEY）。
進階
- 高級模式、調試、CI/CD 等指向 Skill 包內
reference/playbook.md（需從倉庫獲取該文件，本文不展開未抓取內容）。
安裝與啓用¶
Detox 項目側（Skill 內 Setup）¶
在已有 React Native 工程中安裝 Detox 與 Jest，並初始化目錄結構：
npm install detox --save-dev
npm install jest jest-circus --save-dev
detox init
隨後按 Skill 中的 .detoxrc.js 與組件 testID 示例調整工程路徑與 scheme。
Agent Skill 側¶
官方入口爲 GitHub 目錄：detox-skill。Skill 採用通用 SKILL.md 描述（含 name、description、languages、category: mobile-testing 等 front matter）。將該項目中的 Skill 定義按你所用 Agent 產品的 Skill 加載方式接入即可；各編輯器/CLI 的具體菜單路徑以各自文檔爲準，本資料未單獨列出 Cursor 與 Codex CLI 的差異步驟，此處不臆造。
典型用法¶
1、生成基礎登錄流測試¶
Agent 在 Skill 引導下應產出類似結構的用例：啓動應用、每個用例前 reload RN、用 testID 填表並斷言儀表盤或錯誤信息。
describe('Login', () => {
beforeAll(async () => {
await device.launchApp();
});
beforeEach(async () => {
await device.reloadReactNative();
});
it('should login with valid credentials', async () => {
await element(by.id('emailInput')).typeText('user@test.com');
await element(by.id('passwordInput')).typeText('password123');
await element(by.id('loginButton')).tap();
await expect(element(by.id('dashboardTitle'))).toBeVisible();
await expect(element(by.text('Welcome'))).toBeVisible();
});
});
2、本地跑 iOS / Android¶
先 build 再 test，configuration 名稱需與 .detoxrc.js 一致：
detox build --configuration ios.sim.debug
detox test --configuration ios.sim.debug
detox build --configuration android.emu.debug
detox test --configuration android.emu.debug
只跑單個文件：
detox test --configuration ios.sim.debug e2e/login.test.js
錄製與截圖：detox test --record-videos all；用例內 await device.takeScreenshot('login-page')。
3、Android 雲側 Espresso（節選）¶
本地 build 後上傳 app 與 androidTest APK，再 POST 觸發 build（設備名、鑑權以 TestMu AI 賬號爲準）：
detox build --configuration android.emu.debug
上傳與觸發接口見 Skill 正文中的 curl 示例（manual-api.lambdatest.com 上傳、mobile-api.lambdatest.com/framework/v1/espresso/build）。
適用場景與注意¶
適合誰
- 維護 React Native 應用、已採用或計劃採用 Detox 的團隊；需要在 Agent 對話裏快速產出符合社區慣例的 E2E 用例、matcher/action 片段和
.detoxrc.js骨架的開發者。 - 需要在模擬器/仿真器本地驗證，或按官方文檔把同一套 Detox 產物推到 TestMu AI 真機雲上的場景。
限制與注意
- Skill 針對 JavaScript / TypeScript 與 Detox 體系；不是 Appium 或 Maestro 的通用移動 Skill，移動端測試類 Skill 在生態裏相對少，本 Skill 綁定 Detox 與 RN。
- 雲執行依賴 LambdaTest/TestMu AI 賬號與正確產物路徑；示例中的設備型號字符串需與平臺當前可用列表一致，以官方 API 文檔爲準。
binaryPath、xcodebuild、gradlew命令需按你的 app 名稱與目錄改寫；Skill 示例中的MyApp僅爲模板。- 反模式表明確：穩定性依賴
testID與 Detox 同步，而不是堆超時與 sleep。
結尾¶
detox-skill 把 Detox 的用例結構、選擇器、設備 API、配置與本地/雲執行要點收斂進一份 Agent Skill，適合在 RN 項目裏系統化補 E2E 時使用。官方地址：https://github.com/LambdaTest/agent-skills/tree/main/detox-skill。
