@nativescript/detox

轻松地将 Detox 端到端测试添加到您的 NativeScript 应用中！


iOS 示例	Android 示例

安装

ns plugin add @nativescript/detox

全局设置

完整的设置要求可以在这里找到，但最小设置步骤如下

安装 Detox 命令行工具（《detox-cli》）

npm install -g detox-cli

安装 applesimutils（iOS）

brew tap wix/brew
brew install applesimutils

项目设置

将 Detox 包安装到您的 NativeScript 项目中

npm install detox --save-dev

安装 Jest

npm install jest jest-cli jest-circus --save-dev --no-package-lock

初始化 Detox

detox init -r jest

如果一切顺利，您应该有以下的设置

在项目根目录下有一个 e2e/ 文件夹
一个 e2e/config.json 文件；示例
一个 e2e/environment.js 文件；示例
一个 e2e/firstTest.e2e.ts 文件，内容类似于这个。

在您的项目根目录中还应有一个名为 .detoxrc.json 的文件。

配置 Detox

Detox 必须配置以了解 iOS 和 Android 应用二进制文件的位置以及要使用的模拟器/模拟器。

打开 .detoxrc.json 并在 apps 和 devices 下进行以下修改。

binaryPath：指定应用二进制文件的位置（可能是以下内容）。
- iOS：platforms/ios/build/Debug-iphonesimulator/[APP_NAME].app
- Android：platforms/android/app/build/outputs/apk/debug/app-debug.apk
build：指定 iOS 和 Android 的构建命令。
- iOS：ns build ios
- Android：ns build android --detox
设备:
- iOS："type": "iPhone 11"
- Android："avdName": "Pixel_4_API_30"（使用 emulator -list-avds 列出 Android 模拟器）

以下是一个完整的 Detox 配置示例

{
  "testRunner": "jest",
  "runnerConfig": "e2e/config.json",
  "skipLegacyWorkersInjection": true,
  "apps": {
	"ios": {
		"type": "ios.app",
		"binaryPath": "platforms/ios/build/Debug-iphonesimulator/[APP_NAME].app",
		"build": "ns build ios"
	},
	"android": {
		"type": "android.apk",
		"binaryPath": "platforms/android/app/build/outputs/apk/debug/app-debug.apk",
		"build": "ns build android --detox"
	}
  },
  "devices": {
	"simulator": {
		"type": "ios.simulator",
		"device": {
            "type": "iPhone 11 Pro"
		}
	},
	"emulator": {
		"type": "android.emulator",
		"device": {
			"avdName": "Pixel_4_API_30"
		}
	}
  },
  "configurations": {
    "ios": {
        "device": "simulator",
        "app": "ios"
    },
    "android": {
        "device": "emulator",
        "app": "android"
    }
  }
}

注意：默认的 NativeScript Android 项目使用 17 作为最小 SDK，但 Detox 需要 >=21。请从您的 App_Resources/Android/app.gradle 中删除或修改 minSdkVersion。

添加资源 ID（仅限 Android）

为了在 NativeScript 中使用 automationText 属性，必须通过添加自定义资源 ID 来启用它。

在 App_Resources/Android/src/main/res/values/ 中创建一个名为 ids.xml 的文件，并添加以下内容

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <item type="id" name="nativescript_accessibility_id"/>
</resources>

允许本地网络（仅限 iOS）

根据您的设置，iOS 可能无法直接与 Detox 通信。在这种情况下，您需要在您的 Info.plist 文件中添加以下内容以允许本地网络请求。

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

使用方法

阅读 Detox 关于编写第一个测试的这篇教程。其中大部分内容也适用于 NativeScript 应用。

通过在 e2e/firstTest.e2e.js 中打开默认测试场景来开始。

describe('Example', () => {
	beforeEach(async () => {
		await device.reloadReactNative();
	});

	it('should have welcome screen', async () => {
		await expect(element(by.text('Sergio'))).toBeVisible();
	});
});

此示例创建了一个名为 Example 的测试场景，并在其中包含一个名为 should have welcome screen 的单个测试。

匹配器

Detox 使用匹配器来在您的 UI 中找到要与之交互的元素。

您可以使用 NativeScript 的 automationText 属性，通过 Detox 的 by.id() 匹配器找到您的 UI 元素。

示例

<Button text="Tap Me!" automationText="testButton"></Button>

await element(by.id('testButton')).tap();

操作

一旦找到您的 UI 元素，您就可以使用一个操作来与之交互，例如使用 tap() 来模拟用户交互。

现在您应该能够编写测试来模拟用户行为并测试预期结果。

运行测试

构建

使用以下命令为测试构建您的应用程序

detox build -c ios|android

测试

使用以下命令运行您的测试

detox test -c ios|android

注意：如果使用 Android 模拟器，Detox 在运行测试时会禁用动画。测试完成后，动画将保持禁用状态。这可能会在您积极开发时非常令人烦恼。您可以通过从项目目录运行以下辅助脚本来重新启用动画 ./node_modules/.bin/enable-animations。

为了使这个过程更加简单，建议将以下脚本添加到您的 package.json 中。

{
	"scripts": {
		"e2e:android:build": "detox build -c android",
		"e2e:android:test": "detox test -c android && ./node_modules/.bin/enable-animations",
		"e2e:ios:build": "detox build -c ios",
		"e2e:ios:test": "detox test -c ios"
	}
}

现在要构建和运行测试，您将运行

Android

npm run e2e:android:build
npm run e2e:android:test

iOS

npm run e2e:ios:build
npm run e2e:ios:test

故障排除

Detox 需要至少 SDK 版本 21，所以如果您遇到以下错误，请将 minSdkVersion 更改为 21，在 App_Resources/Android/app.gradle 中。

Execution failed for task ':app:processDebugAndroidTestManifest'.
Manifest merger failed : uses-sdk:minSdkVersion 17 cannot be smaller than version 18 declared in library [com.wix:detox:17.6.1] /Users/user/.gradle/caches/transforms-2/files-2.1/91a3acd87d710d1913b266ac114d7001/jetified-detox-17.6.1/AndroidManifest.xml as the library might be using APIs not available in 17
        Suggestion: use a compatible library with a minSdk of at most 17,
                or increase this project's minSdk version to at least 21,
                or use tools:overrideLibrary="com.wix.detox" to force usage (may lead to runtime failures)

Command ./gradlew failed with exit code 1

许可证

Apache 许可证版本 2.0