跨平台开发 / 系统课时
测试超时与取消逻辑
测试超时与取消逻辑
超时和取消都会让异步流程提前离开正常路径,但两者含义不同:超时由截止时间触发,取消来自调用方主动停止。本篇通过可控的 Completer 和显式取消令牌构造两种场景,验证业务是否进入预期兜底或终止路径。
学习目标
- 构造稳定的超时场景并验证兜底结果
- 用显式取消信号验证任务不会继续产出正常结果
- 区分“超时返回”与“底层操作真正被取消”
先区分超时与取消
Future.timeout 可以在等待超过指定时长后抛出 TimeoutException,也可以通过 onTimeout 返回兜底值。但它不会自动取消原始 Future;原始异步操作之后仍可能完成。
Dart 的普通 Future 也没有通用的 cancel()。如果业务需要主动取消,通常要显式设计取消机制,例如取消 StreamSubscription、调用具体客户端提供的取消 API,或像下面这样让任务在关键边界检查取消令牌。
构造可控的两条失败路径
下面的完整测试不依赖长时间 Future.delayed。超时用一个永不主动完成的 Completer 触发,取消则用另一个 Completer 精确控制任务何时从等待点继续。
import 'dart:async';
import 'package:test/test.dart';
class CancelledException implements Exception {
const CancelledException();
}
class CancellationToken {
bool _cancelled = false;
void cancel() {
_cancelled = true;
}
void throwIfCancelled() {
if (_cancelled) {
throw const CancelledException();
}
}
}
Future<String> loadWithTimeout(Future<String> Function() operation) {
return operation().timeout(
const Duration(milliseconds: 20),
onTimeout: () => 'cached',
);
}
Future<String> buildReport({
required Future<void> gate,
required CancellationToken token,
}) async {
token.throwIfCancelled();
await gate;
token.throwIfCancelled();
return 'report-ready';
}
void main() {
test('超时后返回缓存兜底', () async {
final neverCompletes = Completer<String>();
final result = await loadWithTimeout(
() => neverCompletes.future,
);
expect(result, 'cached');
});
test('取消后不继续完成业务结果', () async {
final gate = Completer<void>();
final token = CancellationToken();
final resultFuture = buildReport(
gate: gate.future,
token: token,
);
token.cancel();
gate.complete();
await expectLater(
resultFuture,
throwsA(isA<CancelledException>()),
);
});
}把文件保存为 test/timeout_cancel_test.dart 后运行:
dart test test/timeout_cancel_test.dart预期输出
<TIME> +2: All tests passed!<TIME> 表示实际运行时间。第一个用例需要等待约 20 毫秒触发超时,因此具体耗时会随环境变化。
断言业务结果而不是计时精度
超时测试的重点是“超过业务截止时间后进入哪条路径”,而不是验证计时器恰好在第 20 毫秒触发。不要用秒表断言 19~21 毫秒这类窄区间,这会把操作系统调度和 CI 负载引入测试。
如果生产代码的超时策略是抛出异常,可以把 onTimeout 去掉,并用 throwsA(isA<TimeoutException>()) 验证;如果策略是读取缓存、返回默认值或记录降级状态,则应直接断言对应业务结果。
验证取消是否真的停止副作用
示例中的取消令牌只能在 buildReport 主动检查时生效,所以取消点应放在耗时步骤前后、循环边界或提交副作用之前。对于网络请求、订阅或第三方任务对象,应优先调用它们原生的取消能力,并在测试中验证取消后不会写入数据库、发送事件或更新状态。
还要避免把“Future.timeout 已返回兜底值”误认为“原操作已停止”。如果原操作可能继续产生副作用,生产代码必须另外提供真正的取消机制;测试也应分别覆盖超时决策和取消效果,而不是把两者混成同一个断言。