跨平台开发 / 系统课时

测试超时与取消逻辑

测试超时与取消逻辑

超时和取消都会让异步流程提前离开正常路径,但两者含义不同:超时由截止时间触发,取消来自调用方主动停止。本篇通过可控的 Completer 和显式取消令牌构造两种场景,验证业务是否进入预期兜底或终止路径。

学习目标

  • 构造稳定的超时场景并验证兜底结果
  • 用显式取消信号验证任务不会继续产出正常结果
  • 区分“超时返回”与“底层操作真正被取消”

先区分超时与取消

Future.timeout 可以在等待超过指定时长后抛出 TimeoutException,也可以通过 onTimeout 返回兜底值。但它不会自动取消原始 Future;原始异步操作之后仍可能完成。

Dart 的普通 Future 也没有通用的 cancel()。如果业务需要主动取消,通常要显式设计取消机制,例如取消 StreamSubscription、调用具体客户端提供的取消 API,或像下面这样让任务在关键边界检查取消令牌。

构造可控的两条失败路径

下面的完整测试不依赖长时间 Future.delayed。超时用一个永不主动完成的 Completer 触发,取消则用另一个 Completer 精确控制任务何时从等待点继续。

dart
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 后运行:

bash
dart test test/timeout_cancel_test.dart

预期输出

text
<TIME> +2: All tests passed!

<TIME> 表示实际运行时间。第一个用例需要等待约 20 毫秒触发超时,因此具体耗时会随环境变化。

断言业务结果而不是计时精度

超时测试的重点是“超过业务截止时间后进入哪条路径”,而不是验证计时器恰好在第 20 毫秒触发。不要用秒表断言 19~21 毫秒这类窄区间,这会把操作系统调度和 CI 负载引入测试。

如果生产代码的超时策略是抛出异常,可以把 onTimeout 去掉,并用 throwsA(isA<TimeoutException>()) 验证;如果策略是读取缓存、返回默认值或记录降级状态,则应直接断言对应业务结果。

验证取消是否真的停止副作用

示例中的取消令牌只能在 buildReport 主动检查时生效,所以取消点应放在耗时步骤前后、循环边界或提交副作用之前。对于网络请求、订阅或第三方任务对象,应优先调用它们原生的取消能力,并在测试中验证取消后不会写入数据库、发送事件或更新状态。

还要避免把“Future.timeout 已返回兜底值”误认为“原操作已停止”。如果原操作可能继续产生副作用,生产代码必须另外提供真正的取消机制;测试也应分别覆盖超时决策和取消效果,而不是把两者混成同一个断言。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

测试超时与取消逻辑

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通