feat(zone.js): Add 'flush' parameter option to fakeAsync to flush after the test (#57137)

atscott · thePunderWoman · commit 99d679d6061d · 2024-08-02T16:52:07.000Z
From the internal issue on the matter: > When using the standard Jasmine version of it promises returned by the body function are automatically awaited. The Catalyst version of it is fake-async, so awaiting the promise does not make sense; however it would be nice if Catalyst automatically flushed the promise to replicate the experience of using standard it. This would allow users to do the following: ``` it('should fail later', async () => { await new Promise(r => setTimeout(r)); fail('failure'); }); ``` > In Catalyst today the above test will pass. If this proposal to automatically flush the resulting promise were implemented it would fail. Flushing after the tests complete has been the default behavior inside Google since 2020. Very few tests remain that use the old behavior of only flushing microtasks. The example above would actually fail with `fakeAsync` due to the pending timer, but the argument still remains the same. We might as well just flush if we're going to fail the test anyways by throwing if there's no flush at the end. PR Close #57137
diff --git a/packages/zone.js/lib/zone-spec/fake-async-test.ts b/packages/zone.js/lib/zone-spec/fake-async-test.ts
@@ -785,7 +785,7 @@ class FakeAsyncTestZoneSpec implements ZoneSpec {
   }
 }
 
-let _fakeAsyncTestZoneSpec: any = null;
+let _fakeAsyncTestZoneSpec: FakeAsyncTestZoneSpec | null = null;
 
 type ProxyZoneSpecType = {
   setDelegate(delegateSpec: ZoneSpec): void;
@@ -816,7 +816,8 @@ export function resetFakeAsyncZone() {
  * - microtasks are manually executed by calling `flushMicrotasks()`,
  * - timers are synchronous, `tick()` simulates the asynchronous passage of time.
  *
- * If there are any pending timers at the end of the function, an exception will be thrown.
+ * When flush is `false`, if there are any pending timers at the end of the function,
+ * an exception will be thrown.
  *
  * Can be used to wrap inject() calls.
  *
@@ -825,11 +826,14 @@ export function resetFakeAsyncZone() {
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *
  * @param fn
+ * @param options
+ *     flush: when true, will drain the macrotask queue after the test function completes.
  * @returns The function wrapped to be executed in the fakeAsync zone
  *
  * @experimental
  */
-export function fakeAsync(fn: Function): (...args: any[]) => any {
+export function fakeAsync(fn: Function, options: {flush?: boolean} = {}): (...args: any[]) => any {
+  const {flush = false} = options;
   // Not using an arrow function to preserve context passed from call site
   const fakeAsyncFn: any = function (this: unknown, ...args: any[]) {
     const ProxyZoneSpec = getProxyZoneSpec();
@@ -851,7 +855,7 @@ export function fakeAsync(fn: Function): (...args: any[]) => any {
           throw new Error('fakeAsync() calls can not be nested');
         }
 
-        _fakeAsyncTestZoneSpec = new FakeAsyncTestZoneSpec();
+        _fakeAsyncTestZoneSpec = new FakeAsyncTestZoneSpec() as FakeAsyncTestZoneSpec;
       }
 
       let res: any;
@@ -860,22 +864,28 @@ export function fakeAsync(fn: Function): (...args: any[]) => any {
       _fakeAsyncTestZoneSpec.lockDatePatch();
       try {
         res = fn.apply(this, args);
-        flushMicrotasks();
+        if (flush) {
+          _fakeAsyncTestZoneSpec.flush(20, true);
+        } else {
+          flushMicrotasks();
+        }
       } finally {
         proxyZoneSpec.setDelegate(lastProxyZoneSpec);
       }
 
-      if (_fakeAsyncTestZoneSpec.pendingPeriodicTimers.length > 0) {
-        throw new Error(
-          `${_fakeAsyncTestZoneSpec.pendingPeriodicTimers.length} ` +
-            `periodic timer(s) still in the queue.`,
-        );
-      }
+      if (!flush) {
+        if (_fakeAsyncTestZoneSpec.pendingPeriodicTimers.length > 0) {
+          throw new Error(
+            `${_fakeAsyncTestZoneSpec.pendingPeriodicTimers.length} ` +
+              `periodic timer(s) still in the queue.`,
+          );
+        }
 
-      if (_fakeAsyncTestZoneSpec.pendingTimers.length > 0) {
-        throw new Error(
-          `${_fakeAsyncTestZoneSpec.pendingTimers.length} timer(s) still in the queue.`,
-        );
+        if (_fakeAsyncTestZoneSpec.pendingTimers.length > 0) {
+          throw new Error(
+            `${_fakeAsyncTestZoneSpec.pendingTimers.length} timer(s) still in the queue.`,
+          );
+        }
       }
       return res;
     } finally {
