React Native Windows 测试体系完全指南:单元测试、集成测试与 E2E 测试实战
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,核心行为如下:
- 自动发现 vstest.console.exe:通过
vswhere.exe定位最新 Visual Studio 安装中的Common7\IDE\CommonExtensions\Microsoft\TestWindow\vstest.console.exe; - 默认执行两个测试程序集(针对
x64/Debug配置):target\x64\Debug\React.Windows.Desktop.UnitTests\React.Windows.Desktop.UnitTests.dlltarget\x64\Debug\ReactCommon.UnitTests\ReactCommon.UnitTests.exe
- 以
--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):
- Metro Packager(端口 8081):通过
Find-Packager检查本地 8081 端口是否已有 Packager 进程;若没有,则调用Start-Packager以npm run start方式在仓库根目录拉起; - 测试网站服务器(端口 5555):通过
Find-TestWebsiteServer检查 5555 端口;若未启动,则以dotnet run --project $ReactNativeLocation\TestWebSite\Microsoft.ReactNative.Test.Website.csproj启动vnext/TestWebSite下的 ASP.NET Core 测试站点; - (可选)预加载集成测试 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 测试由四层组件协作完成:
- WinAppDriver:通过 Windows UI Automation(UIA)检视与操控被测应用,对外暴露 W3C WebDriver 协议;
- WebDriverIO:JavaScript 库,通过 WebDriver 协议连接 WinAppDriver,提供查询应用 UI 树的全局 API 与操作应用的全局
browser对象; - Jest:测试运行器,负责断言、用例选择等;其 WebDriverIO 集成由自定义环境 packages/@react-native-windows/automation 提供;
- 自动化通道(可选):
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();
});
更新快照有两种方式:
- 本地执行
jest --updateSnapshot(或仓库脚本yarn e2etest:updateSnapshots,见 packages/e2e-test-app-fabric/package.json); - 从 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)。
桌面测试脚本的通用机制(源码级解读)
UnitTest.ps1 与 IntegrationTests.ps1 是桌面测试的"统一入口",它们共享以下设计(源码证据见 vnext/Scripts/UnitTest.ps1 与 vnext/Scripts/IntegrationTests.ps1):
- vswhere 自动定位 VSTest:二者均通过
vswhere.exe -latest -property installationPath找到最新 VS 实例,再拼接出vstest.console.exe路径,避免手动配置环境变量; - 默认平台/配置:默认
x64/Debug,可通过-Platform(x64/x86)与-Configuration(Debug/Release)覆盖;注意[ValidateSet]会直接拒绝非法取值; - 统一过滤语义:
Include/Exclude均基于FullyQualifiedName子串匹配,多个条件之间以&连接(AND 语义),并仅在传参时才追加--TestCaseFilter; - 隔离进程运行:统一追加
--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 全绿。
