在 EAS Build 上运行 E2E 测试

初始化一个新的裸工作流程项目

¥Initialize a new bare workflow project

让我们首先初始化一个新的 Expo 项目，安装和配置 @config-plugins/detox，然后运行 npx expo prebuild 来生成原生项目。

¥Let's start by initializing a new Expo project, installing and configuring @config-plugins/detox, and running npx expo prebuild to generate the native projects.

从以下命令开始：

¥Start with the following commands:

现在，打开 app.json 并将 @config-plugins/detox 插件添加到 plugins 列表中（这必须在预构建之前完成）。这将自动配置 Android 原生代码以支持 Detox。

¥Now, open app.json and add the @config-plugins/detox plugin to your plugins list (this must be done before prebuilding). This will automatically configure the Android native code to support Detox.

{
  "expo": {
    // ...
    "plugins": ["@config-plugins/detox"]
  }
}

运行 prebuild 以生成原生项目：

¥Run prebuild to generate the native projects:

使主屏幕具有交互性

¥Make home screen interactive

编写 E2E 测试的第一步是有一些东西要测试 - 有一个空的应用，所以让我们让我们的应用具有交互性。你可以添加一个按钮并在按下时显示一些新文本。稍后，你将编写一个测试来模拟点击按钮并验证文本是否按预期显示。

¥The first step to writing E2E tests is to have something to test — have an empty app, so let's make our app interactive. You can add a button and display some new text when it's pressed. Later, you will write a test that simulates tapping the button and verifies if the text is displayed as expected.

import { StatusBar } from 'expo-status-bar';
import { useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';

export default function App() {
  const [clicked, setClicked] = useState(false);

  return (
    <View style={styles.container}>
      {!clicked && (
        <Pressable testID="click-me-button" style={styles.button} onPress={() => setClicked(true)}>
          <Text style={styles.text}>Click me</Text>
        </Pressable>
      )}
      {clicked && <Text style={styles.hi}>Hi!</Text>}
      <StatusBar style="auto" />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
  hi: {
    fontSize: 30,
    color: '#4630EB',
  },
  button: {
    alignItems: 'center',
    justifyContent: 'center',
    paddingVertical: 12,
    paddingHorizontal: 32,
    borderRadius: 4,
    elevation: 3,
    backgroundColor: '#4630EB',
  },
  text: {
    fontSize: 16,
    lineHeight: 21,
    fontWeight: 'bold',
    letterSpacing: 0.25,
    color: 'white',
  },
});

设置排毒

¥Set up Detox

安装依赖

¥Install dependencies

让我们在项目中添加两个开发依赖 - jest 和 detox。jest（或 mocha）是必需的，因为 detox 没有自己的测试运行程序。

¥Let's add two development dependencies to the project - jest and detox. jest (or mocha) is required because detox does not have its own test-runner.

请参阅官方 Detox 文档中的 入门 和 项目设置 指南，了解此过程的任何潜在更新。

¥See the Getting started and Project setup guides in official Detox documentation to learn about any potential updates to this process.

配置排毒

¥Configure Detox

Detox 要求你指定构建命令及其生成的二进制文件的路径。从技术上讲，在 EAS Build 上运行测试时，构建命令不是必需的，但允许你在本地运行测试（例如，使用 npx detox build --configuration ios.release）。

¥Detox requires you to specify both the build command and the path to the binary produced by it. Technically, the build command is not necessary when running tests on EAS Build, but allows you to run tests locally (for example, using npx detox build --configuration ios.release).

使用以下配置更新 .detoxrc.js：

¥Update .detoxrc.js with the following configuration with:

/** @type {Detox.DetoxConfig} */
module.exports = {
  logger: {
    level: process.env.CI ? 'debug' : undefined,
  },
  testRunner: {
    $0: 'jest',
    args: {
      config: 'e2e/jest.config.js',
      _: ['e2e'],
    },
  },
  artifacts: {
    plugins: {
      log: process.env.CI ? 'failing' : undefined,
      screenshot: 'failing',
    },
  },
  apps: {
    'ios.release': {
      type: 'ios.app',
      build:
        'xcodebuild -workspace ios/eastestsexample.xcworkspace -scheme eastestsexample -configuration Release -sdk iphonesimulator -arch x86_64 -derivedDataPath ios/build',
      binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/eastestsexample.app',
    },
    'android.release': {
      type: 'android.apk',
      build:
        'cd android && ./gradlew :app:assembleRelease :app:assembleAndroidTest -DtestBuildType=release && cd ..',
      binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
    },
  },
  devices: {
    simulator: {
      type: 'ios.simulator',
      device: {
        type: 'iPhone 14',
      },
    },
    emulator: {
      type: 'android.emulator',
      device: {
        avdName: 'pixel_4',
      },
    },
  },
  configurations: {
    'ios.release': {
      device: 'simulator',
      app: 'ios.release',
    },
    'android.release': {
      device: 'emulator',
      app: 'android.release',
    },
  },
};

编写 E2E 测试

¥Write E2E tests

接下来，添加你的第一个 E2E 测试。删除自动生成的 e2e/starter.test.js 并使用以下代码片段创建我们自己的 e2e/homeScreen.test.js：

¥Next, add your first E2E tests. Delete the auto-generated e2e/starter.test.js and create our own e2e/homeScreen.test.js with the following snippet:

describe('Home screen', () => {
  beforeAll(async () => {
    await device.launchApp();
  });

  beforeEach(async () => {
    await device.reloadReactNative();
  });

  it('"Click me" button should be visible', async () => {
    await expect(element(by.id('click-me-button'))).toBeVisible();
  });

  it('shows "Hi!" after tapping "Click me"', async () => {
    await element(by.id('click-me-button')).tap();
    await expect(element(by.text('Hi!'))).toBeVisible();
  });
});

套件中有两个测试：

¥There are two tests in the suite:

• 检查 "点我" 按钮在主屏幕上是否可见。

  ¥One that checks whether the "Click me" button is visible on the home screen.

• 另一个验证点击按钮会触发显示 "你好！"。

  ¥Another that verifies that tapping the button triggers displaying "Hi!".

两个测试均假设按钮的 testID 设置为 click-me-button。详细信息请参见 源代码。

¥Both tests assume the button has the testID set to click-me-button. See the source code for details.

配置 EAS 构建

¥Configure EAS Build

配置 Detox 并编写初始 E2E 测试后，下一步是配置 EAS Build 并在云中执行测试。

¥After configuring Detox and writing the initial E2E test, the next step is to configure EAS Build and execute the tests in the cloud.

创建 eas.json

¥Create eas.json

以下命令在项目根目录中创建 eas.json：

¥The following command creates eas.json in the project's root directory:

配置 EAS 构建

¥Configure EAS Build

作为构建的一部分，还需要执行几个步骤来配置 EAS Build 以运行 E2E 测试：

¥There are a few more steps to configure EAS Build for running E2E tests as part of the build:

• 安卓测试：

  ¥Android test:

  • 测试在 Android 模拟器中运行。你将定义一个构建配置文件，用于为模拟器构建应用（生成 .apk 文件）。

    ¥Tests are run in the Android Emulator. You will define a build profile that builds your app for the emulator (produces a .apk file).

  • 安装模拟器及其所有系统依赖。

    ¥Install the emulator and all its system dependencies.

• iOS 测试：

  ¥iOS test:

  • 测试在 iOS 模拟器中运行。你将定义一个构建配置文件来为模拟器构建应用。

    ¥Tests are run in the iOS Simulator. You will define a build profile that builds your app for the simulator.

  • 安装 applesimutils 命令行实用程序。

    ¥Install the applesimutils command line util.

• 配置 EAS Build 以在成功构建应用后运行 Detox 测试。

  ¥Configure EAS Build to run Detox tests after successfully building the app.

编辑 eas.json 并添加 test 构建配置文件：

¥Edit eas.json and add the test build profile:

{
  "build": {
    "test": {
      "android": {
        "gradleCommand": ":app:assembleRelease :app:assembleAndroidTest -DtestBuildType=release",
        "withoutCredentials": true
      },
      "ios": {
        "simulator": true
      }
    }
  }
}

创建 eas-hooks/eas-build-pre-install.sh 来安装给定平台所需的工具和依赖：

¥Create eas-hooks/eas-build-pre-install.sh to install the necessary tools and dependencies for the given platform:

#!/usr/bin/env bash

set -eox pipefail

if [[ "$EAS_BUILD_RUNNER" == "eas-build" && "$EAS_BUILD_PROFILE" == "test"* ]]; then
  if [[ "$EAS_BUILD_PLATFORM" == "android" ]]; then
    sudo apt-get --quiet update --yes

    # Install emulator & video bridge dependencies
    # Source: https://github.com/react-native-community/docker-android/blob/master/Dockerfile
    sudo apt-get --quiet install --yes \
      libc6 \
      libdbus-1-3 \
      libfontconfig1 \
      libgcc1 \
      libpulse0 \
      libtinfo5 \
      libx11-6 \
      libxcb1 \
      libxdamage1 \
      libnss3 \
      libxcomposite1 \
      libxcursor1 \
      libxi6 \
      libxext6 \
      libxfixes3 \
      zlib1g \
      libgl1 \
      pulseaudio \
      socat

    # Emulator must be API 31 -- API 32 and 33 fail due to https://github.com/wix/Detox/issues/3762
    sdkmanager --install "system-images;android-31;google_apis;x86_64"
    avdmanager --verbose create avd --force --name "pixel_4" --device "pixel_4" --package "system-images;android-31;google_apis;x86_64"
  else
    brew tap wix/brew
    brew install applesimutils
  fi
fi

接下来，创建 eas-hooks/eas-build-on-success.sh 并添加代码片段，如下所示。该脚本针对 Android 和 iOS 运行不同的命令。

¥Next, create eas-hooks/eas-build-on-success.sh and add the code snippet as shown below. The script runs different commands for Android and iOS.

• 对于 Android，你必须在运行测试之前手动启动模拟器，因为 detox 偶尔会遇到独立启动模拟器的问题，这可能会导致套件的第一次测试期间挂起。完成 detox test 后，有一个命令可以杀死之前启动的模拟器。

  ¥For Android, you have to manually start the emulator before running the tests as detox occasionally encounters issues initiating the emulator independently, which can cause a hang during the first test of your suite. After completing the detox test, there is a command that kills the previously started emulator.

• 对于 iOS，唯一的命令是 detox test。

  ¥For iOS, the only command is detox test.

#!/usr/bin/env bash

function cleanup()
{
  echo 'Cleaning up...'
  if [[ "$EAS_BUILD_PLATFORM" == "android" ]]; then
    # Kill emulator
    adb emu kill &
  fi
}

if [[ "$EAS_BUILD_PROFILE" != "test" ]]; then
  exit
fi

# Fail if anything errors
set -eox pipefail
# If this script exits, trap it first and clean up the emulator
trap cleanup EXIT

ANDROID_EMULATOR=pixel_4

if [[ "$EAS_BUILD_PLATFORM" == "android" ]]; then
  # Start emulator
  $ANDROID_SDK_ROOT/emulator/emulator @$ANDROID_EMULATOR -no-audio -no-boot-anim -no-window -use-system-libs 2>&1 >/dev/null &

  # Wait for emulator
  max_retry=10
  counter=0
  until adb shell getprop sys.boot_completed; do
    sleep 10
    [[ counter -eq $max_retry ]] && echo "Failed to start the emulator!" && exit 1
    counter=$((counter + 1))
  done

  # Execute Android tests
  if [[ "$EAS_BUILD_PROFILE" == "test" ]]; then
    detox test --configuration android.release
  fi
else
  # Execute iOS tests
  if [[  "$EAS_BUILD_PROFILE" == "test" ]]; then
    detox test --configuration ios.release
  fi
fi

更新 package.json 以使用 EAS 构建钩子 在 EAS Build 上运行上述脚本：

¥Update package.json to use EAS Build hooks to run the above scripts on EAS Build:

{
  "scripts": {
    "eas-build-pre-install": "./eas-hooks/eas-build-pre-install.sh",
    "eas-build-on-success": "./eas-hooks/eas-build-on-success.sh"
  }
}

不要忘记为 eas-build-pre-install.sh 和 eas-build-on-success.sh 添加可执行权限。运行 chmod +x eas-hooks/*.sh。

¥Don't forget to add executable permissions to eas-build-pre-install.sh and eas-build-on-success.sh. Run chmod +x eas-hooks/*.sh.

在 EAS Build 上运行测试

¥Run tests on EAS Build

在 EAS Build 上运行测试就像运行常规构建一样：

¥Running the tests on EAS Build is like running a regular build:

如果你已正确设置所有内容，你应该在构建日志中看到成功的测试结果：

¥If you have set up everything correctly you should see the successful test result in the build logs:

上传失败测试用例的截图

¥Upload screenshots of failed test cases

此步骤是可选的，但强烈推荐。

¥This step is optional but highly recommended.

当 E2E 测试用例失败时，查看应用状态的屏幕截图会很有帮助。EAS Build 可以轻松地使用 eas.json 中的 buildArtifactPaths 上传任意构建工件。

¥When an E2E test case fails, it can be helpful to see the screenshot of the application state. EAS Build makes it easy to upload any arbitrary build artifacts using buildArtifactPaths in eas.json.

对失败的测试进行屏幕截图

¥Take screenshots for failed tests

Detox 支持在测试中截取设备的屏幕截图。上面的 .detoxrc.js 示例 包括 Detox 的配置，用于拍摄失败测试的屏幕截图。

¥Detox supports taking in-test screenshots of the device. The .detoxrc.js sample above includes a configuration for Detox to take screenshots of failed tests.

配置 EAS Build 以进行屏幕截图上传

¥Configure EAS Build for screenshots upload

编辑 eas.json 并将 buildArtifactPaths 添加到 test 构建配置文件中：

¥Edit eas.json and add buildArtifactPaths to the test build profile:

{
  "build": {
    "test": {
      "android": {
        "gradleCommand": ":app:assembleRelease :app:assembleAndroidTest -DtestBuildType=release",
        "withoutCredentials": true
      },
      "ios": {
        "simulator": true
      },
      "buildArtifactPaths": ["artifacts/**/*.png"]
    }
  }
}

与 applicationArchivePath 相比，即使构建失败，也会上传 buildArtifactPaths 中定义的构建工件。工件目录中的所有 .png 文件都将打包到 tarball 中并上传到 AWS S3。你可以稍后从构建详细信息页面下载它们。

¥In contrast to applicationArchivePath, the build artifacts defined at buildArtifactPaths will be uploaded even if the build fails. All .png files from the artifacts directory will be packed into a tarball and uploaded to AWS S3. You can download them later from the build details page.

如果你在本地运行 E2E 测试，请记住将工件添加到 .gitignore：

¥If you run E2E tests locally, remember to add artifacts to .gitignore:

artifacts/

中断测试并运行构建

¥Break a test and run a build

为了测试新配置，让我们进行测试并查看 EAS Build 上传屏幕截图。

¥To test the new configuration, let's break a test and see that EAS Build uploads the screenshots.

编辑 e2e/homeScreen.test.js 并进行以下更改：

¥Edit e2e/homeScreen.test.js and make the following change:

使用以下命令运行 iOS 构建并等待其完成：

¥Run an iOS build with the following command and wait for it to finish:

进入构建详细信息页面后，你应该会看到构建失败。使用 "下载工件" 按钮下载并检查屏幕截图：

¥After going to the build details page you should see that the build failed. Use the "Download artifacts" button to download and examine the screenshot: