feat(core): Add 'flush' parameter option to fakeAsync to flush after the test (#57239)

atscott · thePunderWoman · commit f7918f52720d · 2024-08-05T17:46:04.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 #57239
diff --git a/goldens/public-api/core/testing/index.api.md b/goldens/public-api/core/testing/index.api.md
@@ -70,7 +70,9 @@ export { DeferBlockState }
 export function discardPeriodicTasks(): void;
 
 // @public
-export function fakeAsync(fn: Function): (...args: any[]) => any;
+export function fakeAsync(fn: Function, options?: {
+    flush?: boolean;
+}): (...args: any[]) => any;
 
 // @public
 export function flush(maxTurns?: number): number;
diff --git a/integration/typings_test_ts55/package.json b/integration/typings_test_ts55/package.json
@@ -21,7 +21,7 @@
     "@types/jasmine": "file:../../node_modules/@types/jasmine",
     "rxjs": "file:../../node_modules/rxjs",
     "typescript": "5.5.2",
-    "zone.js": "0.14.0"
+    "zone.js": "0.15.0"
   },
   "scripts": {
     "test": "tsc"
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -20,7 +20,7 @@
   },
   "peerDependencies": {
     "rxjs": "^6.5.3 || ^7.4.0",
-    "zone.js": "~0.14.0"
+    "zone.js": "~0.15.0"
   },
   "repository": {
     "type": "git",
diff --git a/packages/core/testing/src/fake_async.ts b/packages/core/testing/src/fake_async.ts
@@ -35,11 +35,12 @@ export function resetFakeAsyncZoneIfExists(): void {
  * - 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 is thrown.
- *
  * Can be used to wrap `inject()` calls.
  *
  * @param fn The function that you want to wrap in the `fakeAsync` zone.
+ * @param options
+ *   - flush: When true, will drain the macrotask queue after the test function completes.
+ *     When false, will throw an exception at the end of the function if there are pending timers.
  *
  * @usageNotes
  * ### Example
@@ -53,9 +54,9 @@ export function resetFakeAsyncZoneIfExists(): void {
  *
  * @publicApi
  */
-export function fakeAsync(fn: Function): (...args: any[]) => any {
+export function fakeAsync(fn: Function, options?: {flush?: boolean}): (...args: any[]) => any {
   if (fakeAsyncTestModule) {
-    return fakeAsyncTestModule.fakeAsync(fn);
+    return fakeAsyncTestModule.fakeAsync(fn, options);
   }
   throw new Error(fakeAsyncTestModuleNotLoadedErrorMessage);
 }

Original file line number	Diff line number	Diff line change
`@@ -35,11 +35,12 @@ export function resetFakeAsyncZoneIfExists(): void {`
`35`	`35`	* - Microtasks are manually executed by calling `flushMicrotasks()`.
`36`	`36`	* - Timers are synchronous; `tick()` simulates the asynchronous passage of time.
`37`	`37`	`*`
`38`		`- * If there are any pending timers at the end of the function, an exception is thrown.`
`39`		`- *`
`40`	`38`	* Can be used to wrap `inject()` calls.
`41`	`39`	`*`
`42`	`40`	* @param fn The function that you want to wrap in the `fakeAsync` zone.
	`41`	`+ * @param options`
	`42`	`+ * - flush: When true, will drain the macrotask queue after the test function completes.`
	`43`	`+ * When false, will throw an exception at the end of the function if there are pending timers.`
`43`	`44`	`*`
`44`	`45`	`* @usageNotes`
`45`	`46`	`* ### Example`
`@@ -53,9 +54,9 @@ export function resetFakeAsyncZoneIfExists(): void {`
`53`	`54`	`*`
`54`	`55`	`* @publicApi`
`55`	`56`	`*/`
`56`		`-export function fakeAsync(fn: Function): (...args: any[]) => any {`
	`57`	`+export function fakeAsync(fn: Function, options?: {flush?: boolean}): (...args: any[]) => any {`
`57`	`58`	`if (fakeAsyncTestModule) {`
`58`		`- return fakeAsyncTestModule.fakeAsync(fn);`
	`59`	`+ return fakeAsyncTestModule.fakeAsync(fn, options);`
`59`	`60`	`}`
`60`	`61`	`throw new Error(fakeAsyncTestModuleNotLoadedErrorMessage);`
`61`	`62`	`}`