test_async_utils.dart 16.3 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:async';

import 'package:flutter/foundation.dart';

class _AsyncScope {
  _AsyncScope(this.creationStack, this.zone);
  final StackTrace creationStack;
  final Zone zone;
}

/// Utility class for all the async APIs in the `flutter_test` library.
///
/// This class provides checking for asynchronous APIs, allowing the library to
/// verify that all the asynchronous APIs are properly `await`ed before calling
/// another.
///
/// For example, it prevents this kind of code:
///
/// ```dart
/// tester.pump(); // forgot to call "await"!
/// tester.pump();
/// ```
///
/// ...by detecting, in the second call to `pump`, that it should actually be:
///
/// ```dart
/// await tester.pump();
/// await tester.pump();
/// ```
///
/// It does this while still allowing nested calls, e.g. so that you can
36
/// call [expect] from inside callbacks.
37 38 39 40 41 42
///
/// You can use this in your own test functions, if you have some asynchronous
/// functions that must be used with "await". Wrap the contents of the function
/// in a call to TestAsyncUtils.guard(), as follows:
///
/// ```dart
43
/// Future<void> myTestFunction() => TestAsyncUtils.guard(() async {
44 45 46 47
///   // ...
/// });
/// ```
class TestAsyncUtils {
48
  // This class is not meant to be instantiated or extended; this constructor
49
  // prevents instantiation and extension.
50 51 52
  TestAsyncUtils._();
  static const String _className = 'TestAsyncUtils';

53
  static final List<_AsyncScope> _scopeStack = <_AsyncScope>[];
54

55
  /// Calls the given callback in a new async scope. The callback argument is
56 57 58 59 60 61
  /// the asynchronous body of the calling method. The calling method is said to
  /// be "guarded". Nested calls to guarded methods from within the body of this
  /// one are fine, but calls to other guarded methods from outside the body of
  /// this one before this one has finished will throw an exception.
  ///
  /// This method first calls [guardSync].
62
  static Future<T> guard<T>(Future<T> Function() body) {
63
    guardSync();
64
    final Zone zone = Zone.current.fork(
65
      zoneValues: <dynamic, dynamic>{
66
        _scopeStack: true, // so we can recognize this as our own zone
67 68
      }
    );
69
    final _AsyncScope scope = _AsyncScope(StackTrace.current, zone);
70
    _scopeStack.add(scope);
71
    final Future<T> result = scope.zone.run<Future<T>>(body);
72 73
    late T resultValue; // This is set when the body of work completes with a result value.
    Future<T> completionHandler(dynamic error, StackTrace? stack) {
74 75 76 77
      assert(_scopeStack.isNotEmpty);
      assert(_scopeStack.contains(scope));
      bool leaked = false;
      _AsyncScope closedScope;
78
      final List<DiagnosticsNode> information = <DiagnosticsNode>[];
79 80 81 82
      while (_scopeStack.isNotEmpty) {
        closedScope = _scopeStack.removeLast();
        if (closedScope == scope)
          break;
83
        if (!leaked) {
84 85
          information.add(ErrorSummary('Asynchronous call to guarded function leaked.'));
          information.add(ErrorHint('You must use "await" with all Future-returning test APIs.'));
86 87
          leaked = true;
        }
88
        final _StackEntry? originalGuarder = _findResponsibleMethod(closedScope.creationStack, 'guard', information);
89
        if (originalGuarder != null) {
90
          information.add(ErrorDescription(
91 92 93 94 95
            'The test API method "${originalGuarder.methodName}" '
            'from class ${originalGuarder.className} '
            'was called from ${originalGuarder.callerFile} '
            'on line ${originalGuarder.callerLine}, '
            'but never completed before its parent scope closed.'
96
          ));
97 98
        }
      }
99 100
      if (leaked) {
        if (error != null) {
101 102 103 104 105 106
          information.add(DiagnosticsProperty<dynamic>(
            'An uncaught exception may have caused the guarded function leak. The exception was',
            error,
            style: DiagnosticsTreeStyle.errorProperty,
          ));
          information.add(DiagnosticsStackTrace('The stack trace associated with this exception was', stack));
107
        }
108
        throw FlutterError.fromParts(information);
109
      }
110
      if (error != null)
111
        return Future<T>.error(error! as Object, stack);
112
      return Future<T>.value(resultValue);
113
    }
114 115 116
    return result.then<T>(
      (T value) {
        resultValue = value;
117
        return completionHandler(null, null);
118
      },
119
      onError: completionHandler,
120
    );
121 122
  }

123 124
  static Zone? get _currentScopeZone {
    Zone? zone = Zone.current;
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
    while (zone != null) {
      if (zone[_scopeStack] == true)
        return zone;
      zone = zone.parent;
    }
    return null;
  }

  /// Verifies that there are no guarded methods currently pending (see [guard]).
  ///
  /// If a guarded method is currently pending, and this is not a call nested
  /// from inside that method's body (directly or indirectly), then this method
  /// will throw a detailed exception.
  static void guardSync() {
    if (_scopeStack.isEmpty) {
      // No scopes open, so we must be fine.
      return;
    }
    // Find the current TestAsyncUtils scope zone so we can see if it's the one we expect.
144
    final Zone? zone = _currentScopeZone;
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
    if (zone == _scopeStack.last.zone) {
      // We're still in the current scope zone. All good.
      return;
    }
    // If we get here, we know we've got a conflict on our hands.
    // We got an async barrier, but the current zone isn't the last scope that
    // we pushed on the stack.
    // Find which scope the conflict happened in, so that we know
    // which stack trace to report the conflict as starting from.
    //
    // For example, if we called an async method A, which ran its body in a
    // guarded block, and in its body it ran an async method B, which ran its
    // body in a guarded block, but we didn't await B, then in A's block we ran
    // an async method C, which ran its body in a guarded block, then we should
    // complain about the call to B then the call to C. BUT. If we called an async
    // method A, which ran its body in a guarded block, and in its body it ran
    // an async method B, which ran its body in a guarded block, but we didn't
    // await A, and then at the top level we called a method D, then we should
    // complain about the call to A then the call to D.
    //
    // In both examples, the scope stack would have two scopes. In the first
    // example, the current zone would be the zone of the _scopeStack[0] scope,
    // and we would want to show _scopeStack[1]'s creationStack. In the second
    // example, the current zone would not be in the _scopeStack, and we would
    // want to show _scopeStack[0]'s creationStack.
    int skipCount = 0;
    _AsyncScope candidateScope = _scopeStack.last;
    _AsyncScope scope;
    do {
      skipCount += 1;
      scope = candidateScope;
176 177 178 179 180 181 182 183 184 185 186 187 188
      if (skipCount >= _scopeStack.length) {
        if (zone == null)
          break;
        // Some people have reported reaching this point, but it's not clear
        // why. For now, just silently return.
        // TODO(ianh): If we ever get a test case that shows how we reach
        // this point, reduce it and report the error if there is one.
        return;
      }
      candidateScope = _scopeStack[_scopeStack.length - skipCount - 1];
      assert(candidateScope != null);
      assert(candidateScope.zone != null);
    } while (candidateScope.zone != zone);
189
    assert(scope != null);
190 191 192 193
    final List<DiagnosticsNode> information = <DiagnosticsNode>[
      ErrorSummary('Guarded function conflict.'),
      ErrorHint('You must use "await" with all Future-returning test APIs.'),
    ];
194 195
    final _StackEntry? originalGuarder = _findResponsibleMethod(scope.creationStack, 'guard', information);
    final _StackEntry? collidingGuarder = _findResponsibleMethod(StackTrace.current, 'guardSync', information);
196
    if (originalGuarder != null && collidingGuarder != null) {
197
      final String originalKind = originalGuarder.className == null ? 'function' : 'method';
198 199
      String originalName;
      if (originalGuarder.className == null) {
200
        originalName = '$originalKind (${originalGuarder.methodName})';
201
        information.add(ErrorDescription(
202 203 204
          'The guarded "${originalGuarder.methodName}" function '
          'was called from ${originalGuarder.callerFile} '
          'on line ${originalGuarder.callerLine}.'
205
        ));
206
      } else {
207
        originalName = '$originalKind (${originalGuarder.className}.${originalGuarder.methodName})';
208
        information.add(ErrorDescription(
209 210 211 212
          'The guarded method "${originalGuarder.methodName}" '
          'from class ${originalGuarder.className} '
          'was called from ${originalGuarder.callerFile} '
          'on line ${originalGuarder.callerLine}.'
213
        ));
214 215 216 217
      }
      final String again = (originalGuarder.callerFile == collidingGuarder.callerFile) &&
                           (originalGuarder.callerLine == collidingGuarder.callerLine) ?
                           'again ' : '';
218
      final String collidingKind = collidingGuarder.className == null ? 'function' : 'method';
219 220 221
      String collidingName;
      if ((originalGuarder.className == collidingGuarder.className) &&
          (originalGuarder.methodName == collidingGuarder.methodName)) {
222 223
        originalName = originalKind;
        collidingName = collidingKind;
224
        information.add(ErrorDescription(
225 226 227
          'Then, it '
          'was called ${again}from ${collidingGuarder.callerFile} '
          'on line ${collidingGuarder.callerLine}.'
228
        ));
229
      } else if (collidingGuarder.className == null) {
230
        collidingName = '$collidingKind (${collidingGuarder.methodName})';
231
        information.add(ErrorDescription(
232 233 234
          'Then, the "${collidingGuarder.methodName}" function '
          'was called ${again}from ${collidingGuarder.callerFile} '
          'on line ${collidingGuarder.callerLine}.'
235
        ));
236
      } else {
237
        collidingName = '$collidingKind (${collidingGuarder.className}.${collidingGuarder.methodName})';
238
        information.add(ErrorDescription(
239 240 241 242 243
          'Then, the "${collidingGuarder.methodName}" method '
          '${originalGuarder.className == collidingGuarder.className ? "(also from class ${collidingGuarder.className})"
                                                                     : "from class ${collidingGuarder.className}"} '
          'was called ${again}from ${collidingGuarder.callerFile} '
          'on line ${collidingGuarder.callerLine}.'
244
        ));
245
      }
246
      information.add(ErrorDescription(
247
        'The first $originalName '
248
        'had not yet finished executing at the time that '
249
        'the second $collidingName '
250 251 252
        'was called. Since both are guarded, and the second was not a nested call inside the first, the '
        'first must complete its execution before the second can be called. Typically, this is achieved by '
        'putting an "await" statement in front of the call to the first.'
253
      ));
254
      if (collidingGuarder.className == null && collidingGuarder.methodName == 'expect') {
255
        information.add(ErrorHint(
256
          'If you are confident that all test APIs are being called using "await", and '
257
          'this expect() call is not being called at the top level but is itself being '
258 259
          'called from some sort of callback registered before the ${originalGuarder.methodName} '
          'method was called, then consider using expectSync() instead.'
260
        ));
261
      }
262
      information.add(DiagnosticsStackTrace(
263
        '\nWhen the first $originalName was called, this was the stack',
264 265
        scope.creationStack,
      ));
266
    }
267
    throw FlutterError.fromParts(information);
268 269 270 271 272 273 274
  }

  /// Verifies that there are no guarded methods currently pending (see [guard]).
  ///
  /// This is used at the end of tests to ensure that nothing leaks out of the test.
  static void verifyAllScopesClosed() {
    if (_scopeStack.isNotEmpty) {
275 276 277 278
      final List<DiagnosticsNode> information = <DiagnosticsNode>[
        ErrorSummary('Asynchronous call to guarded function leaked.'),
        ErrorHint('You must use "await" with all Future-returning test APIs.')
      ];
279
      for (final _AsyncScope scope in _scopeStack) {
280
        final _StackEntry? guarder = _findResponsibleMethod(scope.creationStack, 'guard', information);
281
        if (guarder != null) {
282
          information.add(ErrorDescription(
283 284 285 286 287
            'The guarded method "${guarder.methodName}" '
            '${guarder.className != null ? "from class ${guarder.className} " : ""}'
            'was called from ${guarder.callerFile} '
            'on line ${guarder.callerLine}, '
            'but never completed before its parent scope closed.'
288
          ));
289 290
        }
      }
291
      throw FlutterError.fromParts(information);
292 293 294
    }
  }

295 296 297 298
  static bool _stripAsynchronousSuspensions(String line) {
    return line != '<asynchronous suspension>';
  }

299
  static _StackEntry? _findResponsibleMethod(StackTrace rawStack, String method, List<DiagnosticsNode> information) {
300
    assert(method == 'guard' || method == 'guardSync');
301
    final List<String> stack = rawStack.toString().split('\n').where(_stripAsynchronousSuspensions).toList();
302 303
    assert(stack.last == '');
    stack.removeLast();
304
    final RegExp getClassPattern = RegExp(r'^#[0-9]+ +([^. ]+)');
305
    Match? lineMatch;
306 307 308 309
    int index = -1;
    do { // skip past frames that are from this class
      index += 1;
      assert(index < stack.length);
310
      lineMatch = getClassPattern.matchAsPrefix(stack[index]);
311
      assert(lineMatch != null);
312
      lineMatch = lineMatch!;
313 314 315 316
      assert(lineMatch.groupCount == 1);
    } while (lineMatch.group(1) == _className);
    // try to parse the stack to find the interesting frame
    if (index < stack.length) {
317
      final RegExp guardPattern = RegExp(r'^#[0-9]+ +(?:([^. ]+)\.)?([^. ]+)');
318
      final Match? guardMatch = guardPattern.matchAsPrefix(stack[index]); // find the class that called us
319 320
      if (guardMatch != null) {
        assert(guardMatch.groupCount == 2);
321 322
        final String? guardClass = guardMatch.group(1); // might be null
        final String? guardMethod = guardMatch.group(2);
323 324 325 326 327 328 329 330 331 332 333 334
        while (index < stack.length) { // find the last stack frame that called the class that called us
          lineMatch = getClassPattern.matchAsPrefix(stack[index]);
          if (lineMatch != null) {
            assert(lineMatch.groupCount == 1);
            if (lineMatch.group(1) == (guardClass ?? guardMethod)) {
              index += 1;
              continue;
            }
          }
          break;
        }
        if (index < stack.length) {
335
          final RegExp callerPattern = RegExp(r'^#[0-9]+ .* \((.+?):([0-9]+)(?::[0-9]+)?\)$');
336
          final Match? callerMatch = callerPattern.matchAsPrefix(stack[index]); // extract the caller's info
337 338
          if (callerMatch != null) {
            assert(callerMatch.groupCount == 2);
339 340
            final String? callerFile = callerMatch.group(1);
            final String? callerLine = callerMatch.group(2);
341
            return _StackEntry(guardClass, guardMethod, callerFile, callerLine);
342 343 344 345
          } else {
            // One reason you might get here is if the guarding method was called directly from
            // a 'dart:' API, like from the Future/microtask mechanism, because dart: URLs in the
            // stack trace don't have a column number and so don't match the regexp above.
346
            information.add(ErrorSummary('(Unable to parse the stack frame of the method that called the method that called $_className.$method(). The stack may be incomplete or bogus.)'));
347
            information.add(ErrorDescription(stack[index]));
348 349
          }
        } else {
350
          information.add(ErrorSummary('(Unable to find the stack frame of the method that called the method that called $_className.$method(). The stack may be incomplete or bogus.)'));
351 352
        }
      } else {
353
        information.add(ErrorSummary('(Unable to parse the stack frame of the method that called $_className.$method(). The stack may be incomplete or bogus.)'));
354
        information.add(ErrorDescription(stack[index]));
355 356
      }
    } else {
357
      information.add(ErrorSummary('(Unable to find the method that called $_className.$method(). The stack may be incomplete or bogus.)'));
358 359 360 361 362 363 364
    }
    return null;
  }
}

class _StackEntry {
  const _StackEntry(this.className, this.methodName, this.callerFile, this.callerLine);
365 366 367 368
  final String? className;
  final String? methodName;
  final String? callerFile;
  final String? callerLine;
369
}