企业官网建设流程全解析

• 测试
• 移动开发
• 质量保障
• 开发工具

detox run-server是 Detox 提供的一个独立启动测试服务器的 CLI 命令，它可以让开发者脱离测试运行器（如 Jest、Mocha），单独拉起一个监听本地端口的 WebSocket 服务器，供应用与测试端手动连接与调试。本文围绕该命令的完整语法、全部参数、源码实现与测试验证展开，帮助你在调试 Detox 原生代码或排查会话连接问题时，能够熟练地使用这个"幕后"工具。

命令定位：为什么需要独立服务器

在常规的 Detox 测试流程中，服务器进程是内嵌在测试运行器生命周期里的：detox test会自行创建DetoxServer实例，测试结束后随之关闭，开发者通常感知不到它的存在。而detox run-server提供的是"standalone（独立）"模式——正如官方文档在 docs/cli/run-server.md 中特别注明的：

This tool is useful mostly for contributing to the native codebase of Detox, not for the outside use.

也就是说，它的主要使用场景是Detox 原生代码（iOS/Android）的贡献者与调试者：当你需要观察应用与服务器之间的真实 WebSocket 消息、分析会话建立过程、或者在修改原生端后手动验证通信协议时，就可以用这个命令把服务器单独拉起来，再手动启动应用或连接测试端。

命令语法与完整参数表

命令的调用形式为：

detox run-server [options]

在仓库中，该命令由 detox/local-cli/run-server.js 实现，完整的参数定义如下：

对应到源码 detox/local-cli/run-server.js 中的 yargsbuilder定义：

• l被声明为choices: ['fatal', 'error', 'warn', 'info', 'verbose', 'trace']，传入不合法的级别会直接报错，从源头保证日志级别取值合法；
• p被声明为number: true且default: 8099，与文档表格完全一致；
• 'no-color'是一个boolean型开关。

端口参数校验：越界立即报错

run-server与其他命令不同，它不接受"范围外"的端口。看 detox/local-cli/run-server.js 的 handler 实现：

module.exports.handler = async function runServer(argv) { if (isNaN(argv.port) || argv.port < 1 || argv.port > 65535) { throw new DetoxRuntimeError(`The port should be between 1 and 65535, got ${argv.port}`); } ... };

端口必须落在1 ~ 65535之间，非数字、0或100000都会被拒绝。这一点有对应的测试用例与快照佐证：detox/local-cli/run-server.test.js 分别用-p PORT（非数字）、-p 0、-p 100000三种输入验证抛错，并且断言DetoxServer构造函数不会被调用；错误信息原文见 detox/local-cli/snapshots/run-server.test.js.snap：

The port should be between 1 and 65535, got NaN The port should be between 1 and 65535, got 0 The port should be between 1 and 65535, got 100000

注意这里的校验是"硬性"的，因此不要指望用-p 0让系统自动分配一个随机端口——这在独立模式下是不允许的。

日志级别与颜色控制

• -l, --loglevel用于控制服务器输出日志的详尽程度。在排查连接问题时，建议使用verbose甚至trace级别，因为会话建立、消息收发等关键日志都以debug/trace级别输出（详见下文源码分析）；
• --no-color用于在无 TTY 环境（如 CI 流水线、日志重定向到文件）下关闭 ANSI 彩色输出，避免日志文件被颜色转义码污染。

启动后的行为：从命令到服务器的完整调用链

run-server的 handler 逻辑虽然简短，但背后是一条完整的链路。执行detox run-server后会发生：

1. 校验端口（见上文），非法端口直接抛出DetoxRuntimeError；
2. 组装并应用日志配置：调用 detox/src/configuration/composeLoggerConfig.js 与 detox/src/configuration/collectCliConfig.js，把命令行里传入的loglevel、no-color等参数合入日志器配置，见 detox/local-cli/run-server.js；
3. 实例化并打开服务器：

await new DetoxServer({ port: +argv.port, standalone: true, }).open();

standalone: true是关键标记——它直接决定了启动日志的级别。

DetoxServer：底层 WebSocket 服务

DetoxServer类位于 detox/src/server/DetoxServer.js，基于ws库的WebSocket.Server实现：

• open()会调用_startListening()，在指定端口上创建WebSocket.Server，启用perMessageDeflate压缩，见 detox/src/server/DetoxServer.js；
• 启动成功后，standalone 模式用info级别打印监听地址，非 standalone 模式则用debug级别，见 detox/src/server/DetoxServer.js：

const level = this._options.standalone ? 'info' : 'debug'; loglevel;

这一点在 detox/src/server/DetoxServer.test.js 中有两个对应的测试用例：standalone 模式断言log.info被调用且log.debug未被调用，反之亦然。也就是说，用detox run-server启动后，你会在终端直接看到Detox server listening on localhost:8099...这一行info日志——这也是确认服务器已就绪的最直观信号。

• 关闭时（close()），服务器最多等待 10 秒（_closeWithTimeout(10000)）让所有连接优雅关闭，超时或异常会以warn级别记录"abruptly closed"告警，见 detox/src/server/DetoxServer.js 与 detox/src/server/DetoxServer.test.js 中的超时/拒绝/错误三种关闭失败场景。

会话管理：tester 与 app 的双端模型

服务器接收到 WebSocket 连接后，会交给DetoxSessionManager（detox/src/server/DetoxSessionManager.js）管理：

• registerConnection()为每个 WebSocket 建立一个DetoxConnection（detox/src/server/DetoxConnection.js），后者负责消息收发：收到的 payload 必须是合法 JSON 且包含type字段，否则抛出DetoxRuntimeError；
• registerSession()把连接按role（'tester' | 'app'）挂到某个sessionId对应的DetoxSession上，见 detox/src/server/DetoxSessionManager.js；
• 每个DetoxSession（detox/src/server/DetoxSession.js）最多承载一个 tester 连接和一个 app 连接，当任一方加入/离开时，通过notify()向另一方广播appConnected、appDisconnected、testerDisconnected等事件，见 detox/src/server/DetoxSession.js。

这个"一测一端"的会话模型，正是 Detox 客户端-服务器架构的核心，更完整的架构说明可参考 docs/architecture/client-server.md。

独立模式与内嵌模式的对比

DetoxServer本身既可以独立运行（standalone: true），也可以由测试流程内嵌启动（standalone: false，即常规detox test模式）。两者差异集中体现在：

从源码看，standalone只是DetoxServer构造函数的一个布尔选项，detox/src/server/DetoxServer.js 中的默认值合并逻辑（_.defaults）说明它甚至可以替换底层WebSocket.Server实现——这也是单元测试注入 mock 服务的方式。

实战：如何用 run-server 调试

以下是在当前仓库语境下推荐的使用路径：

1. 启动独立服务器：

npx detox run-server --port 8099 --loglevel verbose

看到Detox server listening on localhost:8099...（info 级别）即表示就绪。若端口被占用，可选择其他端口（如--port 9000），但需同步修改应用与测试端的连接配置。

2. 观察会话日志：将--loglevel提到trace，可以逐条看到connection :<localPort><->:<remotePort>、created session <id>、app joined session、tester joined session等会话事件（这些日志分别来自 detox/src/server/DetoxConnection.js 与 detox/src/server/DetoxSession.js），从而判断应用端与测试端是否都成功入会。

3. 在无颜色环境下运行（CI、日志落盘）：

npx detox run-server --no-color

4. 查看帮助：npx detox run-server --help会输出上文参数表对应的帮助文本。

需要说明的是：run-server只负责把服务器拉起来，它本身不参与测试调度。若你的目标只是跑一遍端到端测试，请直接使用detox test（参见 docs/cli/overview.md 的命令总览），服务器会自动内嵌启动；若你需要在测试会话中使用自定义的sessionId或外部服务器地址，可参考 docs/config/session.mdx 中的session配置项。

小结

detox run-server是一个短小精悍却直击要害的调试工具：语法上只有端口、日志级别、颜色三个开关，但通过它拉起的DetoxServer承载了 Detox 完整的 WebSocket 会话管理逻辑。掌握它，意味着你在调试 Detox 原生代码或排查"应用连不上测试端"类问题时，拥有了一把可以直接观察协议层面的钥匙。

进一步阅读

• 命令实现：detox/local-cli/run-server.js
• 命令测试与错误快照：detox/local-cli/run-server.test.js、detox/local-cli/snapshots/run-server.test.js.snap
• 服务器核心实现：detox/src/server/DetoxServer.js、detox/src/server/DetoxSessionManager.js、detox/src/server/DetoxSession.js
• 服务器单元测试：detox/src/server/DetoxServer.test.js
• 架构与配置： docs/architecture/client-server.md、docs/cli/overview.md、docs/config/session.mdx

• 测试
• 移动开发
• 质量保障
• 开发工具