feat: allow configuring options for setup test env

setup-jest.js

@@ -5,23 +5,36 @@ const {
   platformBrowserDynamicTesting,
 } = require('@angular/platform-browser-dynamic/testing');
 
-let teardown = globalThis.ngJest?.teardown;
+let testEnvironmentOptions = globalThis.ngJest?.testEnvironmentOptions ?? Object.create(null);
+
 const configuredDestroyAfterEach = globalThis.ngJest?.destroyAfterEach;
 if (configuredDestroyAfterEach) {
   console.warn(
     'Passing destroyAfterEach for configuring the test environment has been deprecated.' +
-      ' Please pass a `teardown` object with ModuleTeardownOptions interface instead,' +
-      ' see https://github.com/angular/angular/blob/6952a0a3e68481564b2bc4955afb3ac186df6e34/packages/core/testing/src/test_bed_common.ts#L98'
+      ' Please pass a `testEnvironmentOptions` object with TestEnvironmentOptions interface instead,' +
+      ' see https://angular.io/api/core/testing/TestEnvironmentOptions'
   );
-  teardown = {
-    destroyAfterEach: true,
+
+  testEnvironmentOptions = {
+    ...testEnvironmentOptions,
+    teardown: {
+      destroyAfterEach: true,
+    },
   };
 }
 
-if (teardown !== undefined) {
-  getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting(), {
-    teardown,
-  });
-} else {
-  getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting());
+const configuredTeardown = globalThis.ngJest?.teardown;
+if (configuredTeardown) {
+  console.warn(
+    'Passing teardown for configuring the test environment has been deprecated.' +
+      ' Please pass a `testEnvironmentOptions` object with TestEnvironmentOptions interface instead,' +
+      ' see https://angular.io/api/core/testing/TestEnvironmentOptions'
+  );
+
+  testEnvironmentOptions = {
+    ...testEnvironmentOptions,
+    teardown: configuredTeardown,
+  };
 }
+
+getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting(), testEnvironmentOptions);

setup-jest.mjs

@@ -2,22 +2,36 @@ import 'zone.js/fesm2015/zone-testing-bundle.min.js';
 import { getTestBed } from '@angular/core/testing';
 import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
 
-let teardown = globalThis.ngJest?.teardown;
-const configuredDestroyAfterEach = globalThis.ngJest?.destroyAfterEach;
+let testEnvironmentOptions = globalThis.ngJest?.testEnvironmentOptions ?? Object.create(null);
 
+const configuredDestroyAfterEach = globalThis.ngJest?.destroyAfterEach;
 if (configuredDestroyAfterEach) {
-  console.warn('Passing destroyAfterEach for configuring the test environment has been deprecated.' +
-    ' Please pass a `teardown` object with ModuleTeardownOptions interface instead,' +
-    ' see https://github.com/angular/angular/blob/6952a0a3e68481564b2bc4955afb3ac186df6e34/packages/core/testing/src/test_bed_common.ts#L98');
-  teardown = {
-    destroyAfterEach: true,
+  console.warn(
+    'Passing destroyAfterEach for configuring the test environment has been deprecated.' +
+      ' Please pass a `testEnvironmentOptions` object with TestEnvironmentOptions interface instead,' +
+      ' see https://angular.io/api/core/testing/TestEnvironmentOptions',
+  );
+
+  testEnvironmentOptions = {
+    ...testEnvironmentOptions,
+    teardown: {
+      destroyAfterEach: true,
+    },
   };
 }
 
-if (teardown !== undefined) {
-  getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting(), {
-    teardown,
-  });
-} else {
-  getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting());
+const configuredTeardown = globalThis.ngJest?.teardown;
+if (configuredTeardown) {
+  console.warn(
+    'Passing teardown for configuring the test environment has been deprecated.' +
+      ' Please pass a `testEnvironmentOptions` object with TestEnvironmentOptions interface instead,' +
+      ' see https://angular.io/api/core/testing/TestEnvironmentOptions',
+  );
+
+  testEnvironmentOptions = {
+    ...testEnvironmentOptions,
+    teardown: configuredTeardown,
+  };
 }
+
+getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting(), testEnvironmentOptions);

src/config/setup-jest.spec.ts

@@ -53,6 +53,7 @@ describe('setup-jest', () => {
 
   describe('for CJS setup-jest, test environment initialization', () => {
     test('should call getTestBed() and initTestEnvironment() with the ModuleTeardownOptions object passed to ngJest', async () => {
+      const spyConsoleWarn = (console.warn = jest.fn());
       globalThis.ngJest = {
         teardown: {
           destroyAfterEach: false,
@@ -62,6 +63,10 @@ describe('setup-jest', () => {
       await import('../../setup-jest');
 
       expect(mockUmdZoneJs).toHaveBeenCalled();
+      expect(spyConsoleWarn).toHaveBeenCalled();
+      expect(spyConsoleWarn.mock.calls[0][0]).toMatchInlineSnapshot(
+        `"Passing teardown for configuring the test environment has been deprecated. Please pass a \`testEnvironmentOptions\` object with TestEnvironmentOptions interface instead, see https://angular.io/api/core/testing/TestEnvironmentOptions"`,
+      );
       assertOnInitTestEnv();
       expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
         teardown: {
@@ -82,7 +87,7 @@ describe('setup-jest', () => {
       expect(mockUmdZoneJs).toHaveBeenCalled();
       expect(spyConsoleWarn).toHaveBeenCalled();
       expect(spyConsoleWarn.mock.calls[0][0]).toMatchInlineSnapshot(
-        `"Passing destroyAfterEach for configuring the test environment has been deprecated. Please pass a \`teardown\` object with ModuleTeardownOptions interface instead, see https://github.com/angular/angular/blob/6952a0a3e68481564b2bc4955afb3ac186df6e34/packages/core/testing/src/test_bed_common.ts#L98"`,
+        `"Passing destroyAfterEach for configuring the test environment has been deprecated. Please pass a \`testEnvironmentOptions\` object with TestEnvironmentOptions interface instead, see https://angular.io/api/core/testing/TestEnvironmentOptions"`,
       );
       assertOnInitTestEnv();
       expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
@@ -91,10 +96,37 @@ describe('setup-jest', () => {
         },
       });
     });
+
+    test('should call getTestBed() and initTestEnvironment() with the testEnvironmentOptions passed to ngJest', async () => {
+      globalThis.ngJest = {
+        testEnvironmentOptions: {
+          teardown: {
+            destroyAfterEach: false,
+            rethrowErrors: true,
+          },
+          errorOnUnknownElements: true,
+          errorOnUnknownProperties: true,
+        },
+      };
+
+      await import('../../setup-jest');
+
+      expect(mockUmdZoneJs).toHaveBeenCalled();
+      assertOnInitTestEnv();
+      expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
+        teardown: {
+          destroyAfterEach: false,
+          rethrowErrors: true,
+        },
+        errorOnUnknownElements: true,
+        errorOnUnknownProperties: true,
+      });
+    });
   });
 
   describe('for ESM setup-jest, test environment initialization', () => {
     test('should call getTestBed() and initTestEnvironment() with the ModuleTeardownOptions object passed to ngJest', async () => {
+      const spyConsoleWarn = (console.warn = jest.fn());
       globalThis.ngJest = {
         teardown: {
           destroyAfterEach: false,
@@ -104,6 +136,10 @@ describe('setup-jest', () => {
       await import('../../setup-jest.mjs');
 
       expect(mockEsmZoneJs).toHaveBeenCalled();
+      expect(spyConsoleWarn).toHaveBeenCalled();
+      expect(spyConsoleWarn.mock.calls[0][0]).toMatchInlineSnapshot(
+        `"Passing teardown for configuring the test environment has been deprecated. Please pass a \`testEnvironmentOptions\` object with TestEnvironmentOptions interface instead, see https://angular.io/api/core/testing/TestEnvironmentOptions"`,
+      );
       assertOnInitTestEnv();
       expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
         teardown: {
@@ -124,7 +160,7 @@ describe('setup-jest', () => {
       expect(mockEsmZoneJs).toHaveBeenCalled();
       expect(spyConsoleWarn).toHaveBeenCalled();
       expect(spyConsoleWarn.mock.calls[0][0]).toMatchInlineSnapshot(
-        `"Passing destroyAfterEach for configuring the test environment has been deprecated. Please pass a \`teardown\` object with ModuleTeardownOptions interface instead, see https://github.com/angular/angular/blob/6952a0a3e68481564b2bc4955afb3ac186df6e34/packages/core/testing/src/test_bed_common.ts#L98"`,
+        `"Passing destroyAfterEach for configuring the test environment has been deprecated. Please pass a \`testEnvironmentOptions\` object with TestEnvironmentOptions interface instead, see https://angular.io/api/core/testing/TestEnvironmentOptions"`,
       );
       assertOnInitTestEnv();
       expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
@@ -133,5 +169,31 @@ describe('setup-jest', () => {
         },
       });
     });
+
+    test('should call getTestBed() and initTestEnvironment() with the testEnvironmentOptions passed to ngJest', async () => {
+      globalThis.ngJest = {
+        testEnvironmentOptions: {
+          teardown: {
+            destroyAfterEach: false,
+            rethrowErrors: true,
+          },
+          errorOnUnknownElements: true,
+          errorOnUnknownProperties: true,
+        },
+      };
+
+      await import('../../setup-jest.mjs');
+
+      expect(mockEsmZoneJs).toHaveBeenCalled();
+      assertOnInitTestEnv();
+      expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
+        teardown: {
+          destroyAfterEach: false,
+          rethrowErrors: true,
+        },
+        errorOnUnknownElements: true,
+        errorOnUnknownProperties: true,
+      });
+    });
   });
 });

src/global.d.ts

@@ -1,14 +1,17 @@
 /* eslint-disable */
 
-import type { ModuleTeardownOptions } from "@angular/core/testing";
+import type { ModuleTeardownOptions, TestEnvironmentOptions } from '@angular/core/testing';
 
 declare global {
-  var ngJest: {
-    skipNgcc?: boolean;
-    tsconfig?: string;
-    destroyAfterEach?: boolean;
-    teardown?: ModuleTeardownOptions;
-  } | undefined;
+  var ngJest:
+    | {
+        skipNgcc?: boolean;
+        tsconfig?: string;
+        destroyAfterEach?: boolean;
+        teardown?: ModuleTeardownOptions;
+        testEnvironmentOptions?: TestEnvironmentOptions;
+      }
+    | undefined;
 }
 
-export {}
+export {};

website/docs/getting-started/test-environment.md

@@ -12,16 +12,23 @@ to run with **ESM** mode.
 
 ### Configure test environment
 
-When creating Angular test environment with `TestBed`, it is possible to specify the behavior of `teardown` via `globalThis` in the Jest setup file.
+When creating Angular test environment with `TestBed`, it is possible to specify the `testEnvironmentOptions` via `globalThis` in the Jest setup file.
 For example:
 
 ```ts
 // setup-test.ts
 globalThis.ngJest = {
-  destroyAfterEach: true,
+  testEnvironmentOptions: {
+    teardown: {
+      destroyAfterEach: false,
+      rethrowErrors: true,
+    },
+    errorOnUnknownElements: true,
+    errorOnUnknownProperties: true,
+  },
 };
 
 import 'jest-preset-angular/setup-jest';
 ```
 
-`jest-preset-angular` will look at `globalThis.ngJest` and pass the correct [`ModuleTearDownOptions`](https://github.com/angular/angular/blob/6952a0a3e68481564b2bc4955afb3ac186df6e34/packages/core/testing/src/test_bed_common.ts#L98) object to `TestBed`.
+`jest-preset-angular` will look at `globalThis.ngJest` and pass the correct [`TestEnvironmentOptions`](https://angular.io/api/core/testing/TestEnvironmentOptions) object to `TestBed`.