refactor(zone.js): Improve missing proxy zone error for jest imported (#64497)

atscott · atscott · commit ced2fa52539e · 2025-10-22T23:26:23.000Z
test functions This improves the fakeAsync error message when importing it, describe, etc from jest We will not be further expanding the ZoneJS patches to support additional use-cases. fixes #47603 PR Close #64497
diff --git a/packages/zone.js/lib/zone-spec/fake-async-test.ts b/packages/zone.js/lib/zone-spec/fake-async-test.ts
@@ -7,7 +7,7 @@
  */
 
 import {ZoneType} from '../zone-impl';
-import {type ProxyZoneSpec} from './proxy';
+import {throwProxyZoneError, type ProxyZoneSpec} from './proxy';
 
 const global: any =
   (typeof window === 'object' && window) || (typeof self === 'object' && self) || globalThis.global;
@@ -954,10 +954,7 @@ export function fakeAsync(fn: Function, options: {flush?: boolean} = {}): (...ar
   const fakeAsyncFn: any = function (this: unknown, ...args: any[]) {
     const ProxyZoneSpec = getProxyZoneSpec();
     if (!ProxyZoneSpec) {
-      throw new Error(
-        'ProxyZoneSpec is needed for the fakeAsync() test helper but could not be found. ' +
-          'Make sure that your environment includes zone-testing.js',
-      );
+      throwProxyZoneError();
     }
     const proxyZoneSpec = ProxyZoneSpec.assertPresent();
     if (Zone.current.get('FakeAsyncTestZoneSpec')) {
diff --git a/packages/zone.js/lib/zone-spec/proxy.ts b/packages/zone.js/lib/zone-spec/proxy.ts
@@ -8,6 +8,22 @@
 
 import {ZoneType} from '../zone-impl';
 
+declare let jest: any;
+
+export function throwProxyZoneError(): never {
+  const jestPatched = typeof jest !== 'undefined' && jest['__zone_patch__'];
+  if (jestPatched) {
+    throw new Error(
+      'Only globals are patched with zone-testing. If you import `it`, `describe`, etc. directly, you cannot use `fakeAsync` or `waitForAsync`.',
+    );
+  } else {
+    throw new Error(
+      'ProxyZoneSpec is needed for the fakeAsync and waitForAsync test helpers but could not be found. ' +
+        'Make sure that your environment includes zone-testing.js',
+    );
+  }
+}
+
 export class ProxyZoneSpec implements ZoneSpec {
   name: string = 'ProxyZone';
 
