RxJS 4 rx-lite-testing-compat:面向旧浏览器的时间虚拟化测试模块实战指南

原创2026-09-20 10:37:101,974 阅读
文章标签:后端

RxJS 4 rx-lite-testing-compat:面向旧浏览器的时间虚拟化测试模块实战指南

Reactive Extensions for JavaScript(RxJS)内置了一套完整的运算符测试机制,通过虚拟时间调度器(Virtual Time Scheduler)可以轻松地模拟(mock)绝对时间与相对时间,从而在无真实等待的情况下验证 delay、throttle、interval 等时间相关运算符的行为。本文以 rx-lite-testing-compat 模块为核心,讲解如何在 Node.js、Ringo.js 与旧版浏览器环境中搭建这套测试体系,深入剖析 Rx.ReactiveTest、Rx.Recorded、Rx.Subscription、Rx.TestScheduler 四大测试类的用法与底层实现,并给出可直接运行的完整测试示例。读完本文,你将掌握 RxJS 4 虚拟时间测试的标准套路:用 onNext/onError/onCompleted 构造带时间戳的通知记录、用 createHotObservable/createColdObservable 布置测试数据、用 startScheduler 驱动虚拟时钟,最后通过记录消息与订阅轨迹完成断言。

一、什么是 compat 版测试模块

rx-lite-testing-compat 是 RxJS 4 系列中 rx-lite-testing 的“兼容(compat)”变体,其全称为 "Lightweight older browser compatible library with testing functions for composing asynchronous and event-based operations in JavaScript"(见 modules/rx-lite-testing-compat/package.json)。它与常规版本的核心差异在于:面向不支持 ES5 特性的旧浏览器,因此在代码层面规避了 Object.defineProperty、Array.isArray 的严格依赖、Function.prototype.bind 等 ES5 语法特性,这也是模块名中 compat 的由来。

模块的版本号为 4.1.0,以 Apache License 2.0 协议发布,包内主入口为 rx.lite.testing.compat.js(508 行),并同时支持 CommonJS(Node.js/Ringo.js)、AMD(RequireJS 等)与全局变量三种加载方式——从其 UMD 包装头可以看到,它依次尝试 define(<a href="https://link.gitcode.com/i/44be406ecf7a5a89210e00ceb67e73a9" target="_blank">'./rx.lite.virtualtime.compat'], ...) 的 AMD 路径、require('rx-lite-virtualtime-compat') 的 CommonJS 路径,最终回退到 root.Rx 全局对象(见 [modules/rx-lite-testing-compat/rx.lite.testing.compat.js)。

1.1 核心依赖:rx-lite-virtualtime

测试机制的正常运转依赖虚拟时间调度器,因此该模块以 rx-virtualtime-compat 为强依赖(package.json 中声明 "dependencies": { "rx-virtualtime-compat": "*" })。它提供的是 Rx.VirtualTimeScheduler 与对应的 rx.lite.virtualtime.compat.js 文件,这是 Rx.TestScheduler 的父类。

在浏览器环境中,需要按以下顺序依次引入三个脚本(依赖在前,测试在后):

<!-- Just the core RxJS -->
<script src="path/to/rx.lite.compat.js"></script>
<script src="path/to/rx.lite.virtualtime.compat.js"></script>
<script src="path/to/rx.lite.testing.compat.js"></script>

注意:如果遗漏了 rx.lite.virtualtime.compat.js,Rx.TestScheduler 将因找不到 Rx.VirtualTimeScheduler 而无法构造。

二、安装与引入方式

2.1 通过 NPM 安装

$ npm install rx-lite-testing-compat
$ npm install -g rx-lite-testing-compat   # 可选:全局安装

本地安装时,依赖的 rx-virtualtime-compat 会被自动带上。

2.2 在 Node.js 与 Ringo.js 中使用

var Rx = require('rx-lite-testing-compat');

require 返回的 Rx 对象中已经聚合了 Rx.ReactiveTest、Rx.Recorded、Rx.Subscription、Rx.TestScheduler 等测试类,可以直接使用。

2.3 在浏览器中使用

<!-- Just the core RxJS -->
<script src="path/to/rx.lite.compat.js"></script>
<script src="path/to/rx.lite.virtualtime.compat.js"></script>
<script src="path/to/rx.lite.testing.compat.js"></script>

三个脚本全部加载完成后,window.Rx 即为聚合了测试能力的命名空间。若使用 RequireJS 等 AMD 加载器,也可以直接 define(['rx-lite-testing-compat'], function (Rx) { ... })。

三、测试体系全景:四个测试类各司其职

rx-lite-testing-compat 打包了四个测试类,它们共同构成一套"布置 → 运行 → 断言"的闭环:

类 职责 源码位置
Rx.ReactiveTest 提供构造带时间戳通知记录(Notification Record)的工厂方法与默认时间常量 src/core/testing/reactivetest.js
Rx.Recorded 记录"某个虚拟时间点产生了某个值"的元组,支持相等比较与字符串化 src/core/testing/recorded.js
Rx.Subscription 记录一次订阅的开始/结束虚拟时间,用于断言订阅与退订行为 src/core/testing/subscription.js
Rx.TestScheduler 继承 VirtualTimeScheduler 的测试调度器,驱动虚拟时钟并产出可断言的结果 src/core/testing/testscheduler.js

下面逐一深入讲解。

四、Rx.ReactiveTest:通知记录的工厂

ReactiveTest 的本质是一个挂载在 Rx.ReactiveTest 上的静态对象(源码见 src/core/testing/reactivetest.js),它只做两件事:定义三个默认虚拟时间常量、提供四个工厂方法。

4.1 三个默认虚拟时间常量

startScheduler 未显式指定时间参数时,测试将使用下列默认值:

字段 默认值 含义
Rx.ReactiveTest.created 100 调用工厂函数创建 Observable 序列的虚拟时间
Rx.ReactiveTest.subscribed 200 订阅该序列的虚拟时间
Rx.ReactiveTest.disposed 1000 取消订阅的虚拟时间

这三个常量在源码中直接以字面量定义(src/core/testing/reactivetest.js),并在 startScheduler 内部作为缺省值生效。

4.2 四个工厂方法

Rx.ReactiveTest.onCompleted(ticks)

在给定虚拟时间 ticks 处产生一条 OnCompleted 通知记录:

var onCompleted = Rx.ReactiveTest.onCompleted;

var scheduler = new Rx.TestScheduler();

var xs = scheduler.createHotObservable(
  onCompleted(260)
);

var res = scheduler.startScheduler(function () {
  return xs.map(function (x) { return x; });
});

// Write custom assertion
collectionAssert.assertEqual(res.messages, [
  onCompleted(260)
]);

Rx.ReactiveTest.onError(ticks, exception)

在 ticks 处产生一条携带异常 exception 的 OnError 通知记录。exception 既可以是真实的 Error 对象,也可以是一个断言谓词函数——后者在比较时会对实际收到的错误调用该谓词,非常适合只关心错误特征(如 message)的场景:

var ex = new Error('woops');

var onError = Rx.ReactiveTest.onError;

var scheduler = new Rx.TestScheduler();

var xs = scheduler.createHotObservable(
    onError(201, ex)
);

var res = scheduler.startScheduler(function () {
  return xs.map(function (x) { return x; });
});

// Write custom assertion
collectionAssert.assertEqual(res.messages, [

  // Using a predicate
  onError(201, function (e) { return e.message === 'woops'; })
]);

Rx.ReactiveTest.onNext(ticks, value)

在 ticks 处产生一条携带 value 的 OnNext 通知记录。value 同样可以是普通值或谓词函数:

var onNext = Rx.ReactiveTest.onNext;

var scheduler = new Rx.TestScheduler();

var xs = scheduler.createHotObservable(
    onNext(201, 42)
);

var res = scheduler.startScheduler(function () {
  return xs.map(function (x) { return x; });
});

// Write custom assertion
collectionAssert.assertEqual(res.messages, [

  // Using a predicate
  onNext(201, function (x) { return x === 42; })
]);

Rx.ReactiveTest.subscribe(start, [end])

构造一条订阅记录,start 为订阅发生的虚拟时间,可选的 end 为退订时间(缺省为 Number.MAX_VALUE,字符串化为 Infinite):

var subscribe = Rx.ReactiveTest.subscribe;

// 断言订阅发生在 200,退订发生在 230
collectionAssert.assertEqual(xs.subscriptions, [
  subscribe(200, 230)
]);

4.3 谓词比较的底层原理

onNext/onError 的谓词形式之所以可行,是因为源码内部定义了 OnNextPredicate 与 OnErrorPredicate 两个包装类(src/core/testing/reactivetest.js):当传入的是函数时,工厂方法会将其包装进谓词对象存入 Recorded.value,随后在 Recorded.equals 比较阶段通过 other.kind 校验通知类型('N' 或 'E')并调用 this.predicate(...) 求值(src/core/testing/recorded.js)。因此测试断言中既可以用精确值,也可以用"只要满足某条件即通过"的宽松匹配,这正是虚拟时间测试在应对不稳定错误对象时的常用技巧。

五、Rx.Recorded:带时间戳的值记录

Recorded 记录"某个值在哪个虚拟时间产生",是 res.messages 与 xs.subscriptions 中所有元素的载体。

5.1 构造与属性

var Rx = require('rx-lite-testing-compat');

var recorded = new Rx.Recorded(200, 'value');

console.log(recorded.time);
// => 200

console.log(recorded.value);
// => value
  • new Rx.Recorded(time, value, [comparer]):time 是虚拟时间,value 是产生的值,可选 comparer 为自定义比较函数,缺省使用 Rx.internals.isEqual。
  • 属性 time:产生值的虚拟时间;
  • 属性 value:被记录的值。

5.2 实例方法

equals(other) 比较时间戳与值(内部使用比较器):

var r1 = new Rx.Recorded(201, 'foo');
var r2 = new Rx.Recorded(201, 'bar');
var r3 = new Rx.Recorded(201, 'foo');

console.log(r1.equals(r2));
// => false

console.log(r1.equals(r3));
// => true

toString() 返回 值@时间 形式:

var r1 = new Rx.Recorded(201, 'foo');

console.log(r1.toString());
// => foo@201

从源码看,toString 的实现即 this.value.toString() + '@' + this.time(src/core/testing/recorded.js),在断言失败信息中会直接拼入该字符串,便于快速定位差异。

六、Rx.Subscription:订阅轨迹的记录

Subscription 记录一次订阅的开始与结束虚拟时间,用于断言"何时订阅、何时退订"这类行为。

6.1 构造与属性

var subscription = new Rx.Subscription(200, 1000);

console.log(subscription.subscribe);
// => 200

console.log(subscription.unsubscribe);
// => 1000
  • new Rx.Subscription(subscribe, <a href="https://link.gitcode.com/i/16b8d151e45881f46981734ca5bbde3e" target="_blank">unsubscribe]):subscribe 为订阅发生的虚拟时间;unsubscribe 缺省为 Number.MAX_VALUE,表示测试结束时仍未退订(源码见 [src/core/testing/subscription.js)。
  • 属性 subscribe:订阅虚拟时间;
  • 属性 unsubscribe:退订虚拟时间。

6.2 实例方法

equals(other) 同时比较订阅与退订时间:

var s1 = new Rx.Subscription(201, 500);
var s2 = new Rx.Subscription(201);
var s3 = new Rx.Subscription(201, 500);

console.log(s1.equals(s2));
// => false

console.log(s1.equals(s3));
// => true

toString() 输出 (开始, 结束),未退订时显示 Infinite:

var s1 = new Rx.Subscription(201);

console.log(s1.toString());
// => (201, Infinite)

var s2 = new Rx.Subscription(201, 1000);
console.log(s2.toString());
// => (201, 1000)

七、Rx.TestScheduler:驱动虚拟时钟的引擎

Rx.TestScheduler 继承自 Rx.VirtualTimeScheduler(src/core/testing/testscheduler.js),它把真实的时间流逝替换为可由代码精确控制的"虚拟时钟":测试中所有 scheduleAbsolute、delay、interval 等时间运算都基于这个虚拟时钟推进,因此整个测试过程不消耗真实等待时间。

7.1 构造

var scheduler = new Rx.TestScheduler();

构造时以 0 为初始时钟,并使用内置的数值比较器(baseComparer)对时间进行排序(src/core/testing/testscheduler.js)。它覆写了 scheduleAbsolute,将"不早于当前时钟"的任务强制推后到 clock + 1,确保任务按严格递增的时间戳执行,避免同一时钟点上的竞态(src/core/testing/testscheduler.js)。

7.2 常用实例方法

方法 作用
createHotObservable(...args) 用带绝对时间戳的通知记录创建热 Observable:即使没有订阅者,消息也会在指定时刻广播,订阅者只能收到订阅之后的消息
createColdObservable(...args) 创建冷 Observable:每条消息的时间戳是相对订阅时刻的偏移量,每次订阅都会"重放"整条序列
createObserver() 创建记录型 Observer,收到的每个通知都会被记录为带时间戳的 Recorded,存于 messages 数组
createResolvedPromise(ticks, value) 创建在 ticks 时刻以 value 兑现的模拟 Promise
createRejectedPromise(ticks, reason) 创建在 ticks 时刻以 reason 拒绝的模拟 Promise
startScheduler(create, settings) 按 settings 指定的创建/订阅/退订时间驱动虚拟时钟运行整个测试,返回记录型 Observer

其中 createHotObservable/createColdObservable 接受参数数组或单个数组两种形式(源码中通过 Array.isArray(arguments<a href="https://link.gitcode.com/i/c4c3f74fe8bff5b830952b7fc64ad4f1" target="_blank">0]) 判断,见 [src/core/testing/testscheduler.js);createResolvedPromise/createRejectedPromise 内部实际上构造的是 MockPromise(src/core/testing/testscheduler.js),用于配合 Rx.Observable.fromPromise 测试异步 Promise 场景。

7.3 startScheduler 的默认时间窗口

startScheduler(createFn, settings) 的三段式时间窗口与 ReactiveTest 常量一一对应(src/core/testing/testscheduler.js):

  • settings.created:调用 createFn() 创建序列的时间,默认 100;
  • settings.subscribed:订阅该序列的时间,默认 200;
  • settings.disposed:退订的时间,默认 1000。

传入方式既可以是三个独立字段的对象,也可以直接引用 ReactiveTest 常量:

var res = scheduler.startScheduler(
  function () { return xs.map(function (x) { return x; }) },
  Rx.ReactiveTest.created,
  Rx.ReactiveTest.subscribed,
  Rx.ReactiveTest.disposed
);

// 等价的对象写法
var res = scheduler.startScheduler(
  function () { return xs.map(function (x) { return x; }) },
  {
    created: Rx.ReactiveTest.created,
    subscribed: Rx.ReactiveTest.subscribed,
    disposed: Rx.ReactiveTest.disposed
  }
);

在 100 时刻创建序列、200 时刻订阅、1000 时刻退订的完整流程中,startScheduler 内部依次调度三个动作:创建 source、source.subscribe(observer)、subscription.dispose(),随后调用 this.start() 驱动虚拟时钟直到队列清空,最后返回记录型 observer(src/core/testing/testscheduler.js)。

7.4 热 Observable 的消息广播与订阅记录

HotObservable 在构造时就会把每条消息按绝对时间调度到虚拟时钟上(src/core/testing/hotobservable.js);订阅发生时,它把观察者推入 observers 数组,并以当前时钟生成一条 Subscription 记录;退订时把 unsubscribe 时间补全到该记录(src/core/testing/hotobservable.js)。这就是 xs.subscriptions 能够精确反映订阅窗口的原因。

八、端到端示例:从布置到断言

结合前面所有内容,下面是一个完整的虚拟时间测试(文档 doc/api/testing/testscheduler.md 中的标准用法)。为了对比结果,这里实现了一个基于 QUnit 的 collectionAssert,用于逐条比较消息记录:

function createMessage(expected, actual) {
  return 'Expected: [' + expected.toString() + ']\r\nActual: [' + actual.toString() + ']';
}

// Using QUnit testing for assertions
var collectionAssert = {
  assertEqual: function (actual, expected) {
    var comparer = Rx.internals.isEqual, isOk = true;

    if (expected.length !== actual.length) {
      ok(false, 'Not equal length. Expected: ' + expected.length + ' Actual: ' + actual.length);
      return;
    }

    for(var i = 0, len = expected.length; i < len; i++) {
      isOk = comparer(expected[i], actual[i]);
      if (!isOk) {
        break;
      }
    }

    ok(isOk, createMessage(expected, actual));
  }
};

var onNext = Rx.ReactiveTest.onNext,
  onCompleted = Rx.ReactiveTest.onCompleted,
  subscribe = Rx.ReactiveTest.subscribe;

var scheduler = new Rx.TestScheduler();

// Create hot observable which will start firing
var xs = scheduler.createHotObservable(
  onNext(150, 1),
  onNext(210, 2),
  onNext(220, 3),
  onCompleted(230)
);

// Note we'll start at 200 for subscribe, hence missing the 150 mark
var res = scheduler.startScheduler(function () {
  return xs.map(function (x) { return x * x });
});

// Implement collection assertion
collectionAssert.assertEqual(res.messages, [
  onNext(210, 4),
  onNext(220, 9),
  onCompleted(230)
]);

// Check for subscribe/unsubscribe
collectionAssert.assertEqual(xs.subscriptions, [
  subscribe(200, 230)
]);

这个示例展示了虚拟时间测试的完整心智模型:

  1. 布置:在虚拟时间 150/210/220/230 预置热序列消息,其中 150 处的事件发生在默认订阅时间 200 之前,因此不会被观察到;
  2. 运行:startScheduler 在 200 订阅、对每个值执行 x * x 变换;
  3. 断言消息:只有 210 → 4、220 → 9、230 → completed 被记录,150 处的 1 被正确忽略;
  4. 断言订阅:订阅窗口为 (200, 230),退订恰好发生在序列完成时刻。

九、冷 Observable 与相对时间偏移

与热序列的绝对时间戳不同,冷序列(createColdObservable)的消息时间戳是相对订阅时刻的偏移量。下面的例子用 filter 筛选偶数,订阅仍从 200 开始:

var onNext = Rx.ReactiveTest.onNext,
  onCompleted = Rx.ReactiveTest.onCompleted;

var scheduler = new Rx.TestScheduler();

// Create cold observable with offset from subscribe time
var xs = scheduler.createColdObservable(
  onNext(150, 1),
  onNext(200, 2),
  onNext(250, 3),
  onCompleted(300)
);

// Note we'll start at 200 for subscribe
var res = scheduler.startScheduler(function () {
  return xs.filter(function (x) { return x % 2 === 0; });
});

// Implement collection assertion
collectionAssert.assertEqual(res.messages, [
  onNext(400, 2),
  onCompleted(500)
]);

// Check for subscribe/unsubscribe
collectionAssert.assertEqual(xs.subscriptions, [
  subscribe(200, 500)
]);

解读:冷序列在 200 被订阅后,其相对偏移 150/200/250/300 映射为绝对时间 350/400/450/500;其中 2(偏移 200)经 filter 通过后在绝对时间 400 被记录,3(偏移 250)被过滤掉,序列在绝对时间 500 完成。订阅窗口 (200, 500) 与此完全吻合。

热 vs 冷的选型建议:需要模拟"订阅前就发生的事件会被错过"(如 UI 事件流)时用热序列;需要每个订阅者都能观察到完整、一致的序列(如每个测试用例独立的数据源)时用冷序列。

十、手动编排虚拟时间与 MockObserver

并非所有测试都必须走 startScheduler。当需要精细控制订阅时机时,可以直接用 scheduleAbsolute 手动编排,并用 createObserver() 收集结果:

var onNext = Rx.ReactiveTest.onNext;

var scheduler = new Rx.TestScheduler();

var d = new Rx.SerialDisposable();

var xs = Rx.Observable.return(42, scheduler);

var res = scheduler.createObserver();

scheduler.scheduleAbsolute(null, 100, function () {
  return d.setDisposable(xs.subscribe(
    function (x) {
      d.dispose();
      res.onNext(x);
    },
    res.onError.bind(res),
    res.onCompleted.bind(res)
  ));
});

scheduler.start();

collectionAssert.assertEqual(res.messages, [
  onNext(101, 42)
]);

这里 Rx.Observable.return(42, scheduler) 在虚拟时间 100 被订阅后,于下一个时钟点 101 发出值 42——这正是 TestScheduler.scheduleAbsolute 将"不早于当前时钟"任务推后到 clock + 1 的直接体现(src/core/testing/testscheduler.js)。

MockObserver 的实现印证了记录机制:它的 onNext/onError/onCompleted 分别以 this.scheduler.clock 为时间戳,把 Notification 包装成 Recorded 追加进 messages(src/core/testing/mockobserver.js)。因此 res.messages 中的每一条都天然带有精确的虚拟时间戳,可直接与 ReactiveTest.onNext(...) 等产物做 isEqual 比较。

十一、测试 Promise 异步场景

对于 fromPromise 等 Promise 相关运算符,TestScheduler 提供了 createResolvedPromise 与 createRejectedPromise 两个模拟 Promise 工厂,使 Promise 的兑现/拒绝也能落入虚拟时间轴:

var onNext = Rx.ReactiveTest.onNext,
  onError = Rx.ReactiveTest.onError,
  onCompleted = Rx.ReactiveTest.onCompleted;

var scheduler = new Rx.TestScheduler();

// Create resolved promise
var xs = scheduler.createResolvedPromise(201, 1);

// Note we'll start at 200 for subscribe, hence missing the 150 mark
var res = scheduler.startScheduler(function () {
  // Need to pass test scheduler due to issue #976
  return Rx.Observable.fromPromise(xs, scheduler);
});

// Implement collection assertion
collectionAssert.assertEqual(res.messages, [
  onNext(201, 1),
  onCompleted(201)
]);

被拒绝的 Promise 同理:

var error = new Error();
var xs = scheduler.createRejectedPromise(201, error);

var res = scheduler.startScheduler(function () {
  return Rx.Observable.fromPromise(xs, scheduler);
});

collectionAssert.assertEqual(res.messages, [
  onError(201, error)
]);

从源码看,createResolvedPromise 等价于在同一时刻投递一条 onNext 与一条 onCompleted,而 createRejectedPromise 只投递一条 onError(src/core/testing/testscheduler.js),其时间语义与热/冷序列完全一致。

十二、在仓库中验证:测试套件与更多示例

本仓库本身就是这套测试机制的最大用户:tests/observable/ 目录下每个运算符一个测试文件(如 tests/observable/delay.js、tests/observable/interval.js、tests/observable/throttle.js),全部基于 Rx.TestScheduler 与 ReactiveTest 编写,可以当作最佳实践范例阅读。tests/helpers/reactiveassert.js 则提供了项目内部使用的集合断言辅助(类似上文手写的 collectionAssert)。

仓库中与测试相关的文件速查:

十三、常见问题与注意事项

  1. 忘记引入 virtualtime 文件:rx-lite-testing-compat 强依赖 rx.lite.virtualtime.compat.js,浏览器引入顺序必须为 rx.lite.compat.js → rx.lite.virtualtime.compat.js → rx.lite.testing.compat.js;Node.js 下 npm install rx-lite-testing-compat 会自动带上 rx-virtualtime-compat。
  2. 热序列的消息会"错过":热 Observable 按绝对时间广播,发生在订阅时间(默认 200)之前的消息不会被记录——这不是 bug,而是模拟真实事件流的预期行为(如示例中 150 处的消息被忽略)。
  3. 冷序列的偏移换算:冷序列的时间戳相对订阅时刻,断言时需自行加上订阅时间(如 200 订阅时,偏移 200 的消息出现在绝对时间 400)。
  4. compat 与 ES5 版本的差异:若目标环境完整支持 ES5,可改用 rx-lite-testing(引入 rx.lite.js、rx.lite.virtualtime.js、rx.lite.testing.js);需要兼容 IE8 等旧浏览器的项目应选择本文的 compat 版本。
  5. 断言集合需要自行实现:RxJS 测试模块只负责"记录",不绑定任何测试框架;文档示例使用 QUnit 实现 collectionAssert,你也可以为 Jasmine、Mocha 等框架编写等效的集合断言。

十四、小结

rx-lite-testing-compat 为 RxJS 4 在旧浏览器与 Node.js/Ringo.js 环境下提供了一套完整、确定性的虚拟时间测试方案。其核心价值在于:通过 TestScheduler 将时间抽象为可控的虚拟时钟,配合 ReactiveTest 的工厂方法、Recorded/Subscription 的记录模型,让任何依赖时间流逝的运算符(delay、throttle、interval、timeout、Promise 桥接等)都能在毫秒级内完成精确到每一个 tick 的验证。掌握"布置通知记录 → 驱动虚拟时钟 → 断言消息与订阅轨迹"这套方法论后,你可以直接复用 tests/observable/ 中的真实测试作为模板,为自己的应用编写同样严谨的响应式逻辑测试。

登录后查看全文
RxJS