React Native Windows 测试体系完全指南:单元测试、集成测试与 E2E 测试实战

原创2026-09-20 16:33:471,840 阅读
文章标签:跨平台前端

React Native Windows 测试体系完全指南:单元测试、集成测试与 E2E 测试实战

导读

本文以 docs/testing.md 为核心骨架,系统梳理 react-native-windows 仓库的完整测试体系:从 React.Windows.Desktop.UnitTests 的单元测试、React.Windows.Desktop.IntegrationTests 的集成测试,到基于 WinAppDriver + WebDriverIO + Jest 的端到端(E2E)测试。无论你是向本仓库贡献代码的开发者,还是希望为自己的 RNW 应用搭建自动化质量保障体系的工程师,读完本文后都能掌握:三类测试各自的定位与适用场景、如何通过仓库内置 PowerShell 脚本一键运行测试、如何过滤与调试单个用例、以及如何编写并运行针对 RNTester 页面的 E2E 测试。

测试体系总览

当向 react-native-windows 贡献代码时,运行单元测试与集成测试是防止新 bug 与回归的基本要求(见 docs/testing.md)。仓库将测试按"隔离程度"划分为三层:

测试层级 实现工程 依赖外部环境 定位
单元测试 React.Windows.Desktop.UnitTests 否(Mock 依赖与数据) 隔离验证具体实现
集成测试 React.Windows.Desktop.IntegrationTests 是(文件系统、网络服务器、Metro Packager) 验证高层工作流
E2E 测试 packages/e2e-test-app-fabric 是(WinAppDriver + 打包后的原生 App) 模拟真实用户操作 UI

测试产物是面向 Windows 桌面的,因此所有桌面测试都必须使用 VSTest 兼容客户端来执行,例如 VSTest.Console.exe、Visual Studio Test 任务(Azure DevOps 的 vstest task)。仓库提供了便捷脚本来完成测试产物的构建准备与运行,无需手动拼装繁琐的 vstest.console.exe 命令行。

单元测试(Unit Tests)

定位与实现工程

单元测试实现在 React.Windows.Desktop.UnitTests 工程中(对应工程文件 vnext/Desktop.UnitTests/React.Windows.Desktop.UnitTests.vcxproj)。它们是隔离、自包含的测试:针对具体实现,配合 Mock 依赖与构造数据,不触碰真实的文件系统、网络或 UI。

从该工程的源码清单可以直观看出被测对象覆盖范围(见 vnext/Desktop.UnitTests):

  • UnicodeConversionTest.cpp、UnicodeTestStrings.cpp —— Unicode 编码转换
  • WebSocketMocks.cpp、WinRTNetworkingMocks.cpp、WinRTWebSocketResourceUnitTest.cpp —— WebSocket / 网络资源层的 Mock 驱动测试
  • OriginPolicyHttpFilterTest.cpp、RedirectHttpFilterUnitTest.cpp —— HTTP 过滤策略
  • MemoryMappedBufferTests.cpp、ScriptStoreTests.cpp —— 脚本存储与内存映射缓冲区
  • LayoutAnimationTests.cpp —— 布局动画
  • UtilsTest.cpp、BaseFileReaderResourceUnitTest.cpp —— 工具类与资源读取

工程通过 ProjectReference 链接 React.Windows.Desktop.vcxproj 并引入 Mso、Common、Shared、Microsoft.ReactNative.Cxx 等头文件路径(见 vnext/Desktop.UnitTests/React.Windows.Desktop.UnitTests.vcxproj#L57-L59),并在工程内定义了 Target Name="Test",可直接执行产物中的测试程序。

运行命令

在仓库根目录(即 vnext 目录)执行:

& Scripts\UnitTests.ps1

该脚本定义在 vnext/Scripts/UnitTest.ps1,核心行为如下:

  1. 自动发现 vstest.console.exe:通过 vswhere.exe 定位最新 Visual Studio 安装中的 Common7\IDE\CommonExtensions\Microsoft\TestWindow\vstest.console.exe;
  2. 默认执行两个测试程序集(针对 x64 / Debug 配置):
    • target\x64\Debug\React.Windows.Desktop.UnitTests\React.Windows.Desktop.UnitTests.dll
    • target\x64\Debug\ReactCommon.UnitTests\ReactCommon.UnitTests.exe
  3. 以 --InIsolation 隔离进程模式运行,并传入 --Platform:x64。

常用参数

UnitTest.ps1 支持以下参数(与 IntegrationTests.ps1 一致):

# 指定平台与配置
& Scripts\UnitTests.ps1 -Platform x86 -Configuration Release

# 按测试全名模糊过滤(FullyQualifiedName~)
& Scripts\UnitTests.ps1 -Include "LayoutAnimation"

# 排除特定测试(FullyQualifiedName!~)
& Scripts\UnitTests.ps1 -Exclude "WebSocket"

# 组合过滤
& Scripts\UnitTests.ps1 -Include "Unicode" -Exclude "WinRTWebSocket"

脚本内部将 Include / Exclude 翻译为 VSTest 的 --TestCaseFilter 表达式:Include 生成 (FullyQualifiedName~A)&(FullyQualifiedName~B) 形式的 AND 过滤,Exclude 生成 (FullyQualifiedName!~A) 形式的否定过滤(见 vnext/Scripts/UnitTest.ps1#L31-L37)。

前提:运行前需先完成构建,确保 target\<Platform>\<Configuration>\ 下存在对应 DLL;脚本使用 $(Split-Path $PSScriptRoot) 定位 vnext\target 输出目录。

集成测试(Integration Tests)

定位与实现工程

集成测试实现在 React.Windows.Desktop.IntegrationTests 工程中(见 vnext/Desktop.IntegrationTests)。与单元测试不同,它们验证更高层的工作流,会与真实的外部依赖交互——包括文件系统、网络服务器、Metro Packager 等。这些测试可以直接在本地开发主机上运行。

从工程源码可以看出其覆盖的集成场景:

  • HttpResourceIntegrationTests.cpp —— 真实 HTTP 资源请求
  • WebSocketIntegrationTest.cpp —— 真实 WebSocket 连接
  • RNTesterHeadlessTests.cpp —— RNTester 无头测试
  • TestReactNativeHostHolder.cpp / TestReactPackageProvider.cpp —— React Native Host 生命周期与包注册
  • TestUIDispatcher.cpp —— UI 线程调度

运行命令与自动化行为

# 启动测试服务并运行测试
& Scripts\IntegrationTests.ps1

脚本 vnext/Scripts/IntegrationTests.ps1 在启动 VSTest 前会先完成三项"环境保障"(逻辑封装在 vnext/Scripts/TestServers.ps1):

  1. Metro Packager(端口 8081):通过 Find-Packager 检查本地 8081 端口是否已有 Packager 进程;若没有,则调用 Start-Packager 以 npm run start 方式在仓库根目录拉起;
  2. 测试网站服务器(端口 5555):通过 Find-TestWebsiteServer 检查 5555 端口;若未启动,则以 dotnet run --project $ReactNativeLocation\TestWebSite\Microsoft.ReactNative.Test.Website.csproj 启动 vnext/TestWebSite 下的 ASP.NET Core 测试站点;
  3. (可选)预加载集成测试 Bundle:传入 -Preload 时,脚本会先 Invoke-WebRequest 探测 http://localhost:5555,再请求 http://localhost:8081/IntegrationTests/IntegrationTestsApp.bundle?platform=windows&dev=true 预取 Bundle,显著加快后续测试执行。

随后脚本才调用 VSTest 运行 React.Windows.Desktop.IntegrationTests.dll。

常用参数

# 不启动也不使用测试服务器(适合服务器已在运行或纯本地用例)
& Scripts\IntegrationTests.ps1 -NoServers

# 启动服务后等待 10 秒(默认)并预加载 Bundle,然后退出不执行测试
& Scripts\IntegrationTests.ps1 -Preload -Delay 20

# 只列出全部测试的全限定名称,不执行
& Scripts\IntegrationTests.ps1 -List

# 仅启动服务器与预加载,不运行测试(供调试环境准备)
& Scripts\IntegrationTests.ps1 -NoRun

# 过滤单个/多个测试
& Scripts\IntegrationTests.ps1 -Include "HttpResource"
& Scripts\IntegrationTests.ps1 -Include "WebSocket" -Exclude "WinRTWebSocket"

其中 -List 借助 VSTest 的 --ListFullyQualifiedTests 将测试清单写入临时文件后再输出到控制台(见 vnext/Scripts/IntegrationTests.ps1#L49-L56),便于你确认可用用例名后精确过滤。

E2E 测试

端到端测试的目标是像真实用户一样驱动打包后的原生应用。详情请参阅 docs/e2e-testing.md,此处提炼其要点。

e2e-test-app-fabric 工程结构

E2E 测试工程位于 packages/e2e-test-app-fabric,组织如下:

  • test/ —— 使用 Jest + WebDriverIO 编写的测试用例(如 visitAllPages.test.ts、LegacyControlStyleTest.test.ts 等)
  • windows/ —— UWP / WinAppSDK 原生测试应用(RNTesterApp-Fabric)
  • jest.config.js —— Jest 与 WebDriverIO 的配置

技术栈与架构

E2E 测试由四层组件协作完成:

  1. WinAppDriver:通过 Windows UI Automation(UIA)检视与操控被测应用,对外暴露 W3C WebDriver 协议;
  2. WebDriverIO:JavaScript 库,通过 WebDriver 协议连接 WinAppDriver,提供查询应用 UI 树的全局 API 与操作应用的全局 browser 对象;
  3. Jest:测试运行器,负责断言、用例选择等;其 WebDriverIO 集成由自定义环境 packages/@react-native-windows/automation 提供;
  4. 自动化通道(可选):enableAutomationChannel: true 时,通过 @react-native-windows/automation-channel 建立与应用的通信通道,用于错误日志收集、UI 树转储等高级能力。

jest.config.js 中的关键配置(见 packages/e2e-test-app-fabric/jest.config.js):

module.exports = {
  testEnvironment: '@react-native-windows/automation',
  testRegex: ['.*\\.test\\.ts$', '.*\\.test\\.js$'],
  testTimeout: 70000,
  maxWorkers: 1,
  setupFilesAfterEnv: ['react-native-windows/jest/setup', './jest.setup.js'],
  testEnvironmentOptions: {
    app: 'RNTesterApp-Fabric',   // 要启动并附加的应用包
    useRootSession: true,        // WinAppSDK 打包应用需使用 Root(Desktop) 会话
    rootLaunchApp: true,         // 设置阶段启动、清理阶段关闭应用
    enableAutomationChannel: true,
  },
};

运行前提:安装 WinAppDriver

运行前需安装 WinAppDriver v1.2.1。若使用 RNW 依赖安装脚本(rnw-dependencies)并传入 rnwDev 参数,则会自动完成安装。脚本默认假定 WinAppDriver 位于 C:\Program Files (x86)\Windows Application Driver\WinAppDriver.exe;若安装在其他路径,需在 jest.config.js 的 testEnvironmentOptions 中显式指定:

module.exports = {
  ...
  testEnvironmentOptions: {
    ...
    winAppDriverBin: 'D:\\Program Files (x86)\\Windows Application Driver\\WinAppDriver.exe',
  },
};

构建原生测试应用并运行

# 1. 进入 E2E 工程并构建原生应用(不自动启动)
cd packages\e2e-test-app-fabric
yarn windows --no-launch

# 2. 启动 Metro(另开终端)
yarn start

# 3. 运行全部 E2E 测试
yarn e2etest

运行单个测试文件时,只需传文件名(不含路径前缀):

yarn e2etest visitAllPages.test.ts

需要在应用启动时断点调试:

yarn e2etest:debug visitAllPages.test.ts

这些脚本定义在 packages/e2e-test-app-fabric/package.json 中:e2etest 等价于 npx @react-native-community/cli rnx-test --platform windows,e2etest:debug 额外指定 jest.debug.config.js。

编写 E2E 测试

测试面向运行 RNTester 的测试应用编写,通常优先复用现有 RNTester 示例页作为测试 UI。一个针对组件示例页的典型用例(参考 packages/e2e-test-app-fabric/test/LegacyControlStyleTest.test.ts):

// LegacyControlStyleTestPage.test.ts
describe('FancyWidget', () => {
  beforeAll(async () => {
    await goToComponentExample('FancyWidget');
  });

  test('FancyWidget is populated with placeholder', async () => {
    // 通过 accessibilityId 定位元素(见下方 "locators")
    const field = await app.findElementByTestID('foo');
    expect(await field.getText()).toBe('placeholder');
  });
});

如果需要新增自定义测试页,优先考虑将改动合并进现有 RNTester 页并向上游提交;确实需要自定义页时,可加入 Windows 分支的 RNTester(packages/@react-native-windows/tester)。推荐使用 React Hooks 编写测试页,并按 RNTester 的 title / description / examples 约定导出:

// ControlStyleTestPage.tsx
export const title = 'LegacyControlStyleTest';
export const description = 'Legacy e2e test for Control Styles';
export const examples = [
  {
    render: function (): JSX.Element {
      return <ControlStyleTestPage />;
    },
  },
];

随后在 RNTester 列表中注册该页(Windows 专属列表文件):

// RNTesterList.windows.js
{
  key: 'LegacyControlStyleTest',
  module: require('../examples-win/LegacyTests/ControlStyleTestPage'),
},

快照测试(Snapshot Tests)

E2E 测试使用 Jest 快照测试检测非预期的视觉变化。与 React 组件树快照不同,e2e-test-app-fabric 对比的是完整渲染后的 Composition 树,从而能够直接验证 ViewComponent 的渲染正确性:

import {dumpVisualTree} from '@react-native-windows/automation-commands';

test('Example test', async () => {
  const dump = await dumpVisualTree('test-id-here');
  expect(dump).toMatchSnapshot();
});

更新快照有两种方式:

  1. 本地执行 jest --updateSnapshot(或仓库脚本 yarn e2etest:updateSnapshots,见 packages/e2e-test-app-fabric/package.json);
  2. 从 CI 失败产物中下载 "snapshots" 工件进行覆盖。

调试 E2E 测试与 CI 产物

提高日志详细度:默认只输出 WinAppDriver 报错与断言失败信息;如需查看每条 WebDriver wire 命令,可调整 jest.config.js:

module.exports = {
  ...
  testEnvironmentOptions: {
    ...
    webdriverOptions: {
      // 日志级别:trace | debug | info | warn | error
      logLevel: 'error',
      ...
    },
  },
};

CI 测试工件(Artifacts):当你在 Azure DevOps 流水线中运行 PR 时,可从运行详情页的 artifacts 链接获取以下调试材料(见 docs/e2e-testing.md):

  • 测试失败时应用错误截图;
  • 测试运行 XML —— 包含失败的 wdio 测试名称与 JS 堆栈;
  • 树转储输出(tree dump) —— 可与主干分支输出对比,定位导致失败的差异;
  • E2E 测试应用(RNTesterApp)的崩溃转储(crash dump)。

E2E 测试 CI 工件下载入口

桌面测试脚本的通用机制(源码级解读)

UnitTest.ps1 与 IntegrationTests.ps1 是桌面测试的"统一入口",它们共享以下设计(源码证据见 vnext/Scripts/UnitTest.ps1 与 vnext/Scripts/IntegrationTests.ps1):

  1. vswhere 自动定位 VSTest:二者均通过 vswhere.exe -latest -property installationPath 找到最新 VS 实例,再拼接出 vstest.console.exe 路径,避免手动配置环境变量;
  2. 默认平台/配置:默认 x64 / Debug,可通过 -Platform(x64 / x86)与 -Configuration(Debug / Release)覆盖;注意 [ValidateSet] 会直接拒绝非法取值;
  3. 统一过滤语义:Include / Exclude 均基于 FullyQualifiedName 子串匹配,多个条件之间以 & 连接(AND 语义),并仅在传参时才追加 --TestCaseFilter;
  4. 隔离进程运行:统一追加 --InIsolation --Platform:<Platform>,保证测试互不干扰。

小结:如何选择测试层级

  • 单元测试(Scripts\UnitTests.ps1):修改具体实现、工具函数、网络协议栈等底层代码时优先运行,速度快、无外部依赖;
  • 集成测试(Scripts\IntegrationTests.ps1):改动涉及 React Native Host、模块生命周期、真实网络/文件系统交互时运行,脚本会自动拉起 Packager 与测试网站;
  • E2E 测试(packages/e2e-test-app-fabric + yarn e2etest):UI 行为、组件渲染、无障碍与视觉回归场景必测,需要 WinAppDriver 与构建好的原生应用。

三类测试共同构成 react-native-windows 的质量防线:从"实现是否正确"(单元)到"工作流是否打通"(集成),再到"真实用户是否可用"(E2E)。向仓库贡献代码时,建议按改动范围选择对应层级并保持 CI 全绿。

登录后查看全文
react-native-windows