feat: add new setup test env functions

ahnpnl · ahnpnl · commit 21c0238cb4ad · 2024-11-15T17:23:08.000+07:00
Closes #354 Closes #2755
diff --git a/.eslintignore b/.eslintignore
@@ -6,3 +6,4 @@ src/config/setup-jest.ts
 coverage
 src/transformers/jit_transform.js
 index.html
+*.mjs
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -9,6 +9,7 @@ const baseJsTsConfig = {
     parser: '@typescript-eslint/parser',
     parserOptions: {
         project: 'tsconfig.eslint.json',
+        sourceType: 'module',
     },
     rules: {
         '@typescript-eslint/no-empty-function': 'error',
@@ -71,7 +72,7 @@ module.exports = {
     overrides: [
         {
             ...baseJsTsConfig,
-            files: ['*.ts', '*.js'],
+            files: ['*.ts', '*.js', '*.mts'],
             extends: [
                 'plugin:@angular-eslint/recommended',
                 'plugin:@angular-eslint/template/process-inline-templates',
diff --git a/examples/example-app-monorepo/apps/app1/setup-jest-esm.ts b/examples/example-app-monorepo/apps/app1/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-monorepo/apps/app1/setup-jest.ts b/examples/example-app-monorepo/apps/app1/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-monorepo/libs/user/setup-jest-esm.ts b/examples/example-app-monorepo/libs/user/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-monorepo/libs/user/setup-jest.ts b/examples/example-app-monorepo/libs/user/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-v16/setup-jest-esm.ts b/examples/example-app-v16/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-v16/setup-jest.ts b/examples/example-app-v16/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-v17/setup-jest-esm.ts b/examples/example-app-v17/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-v17/setup-jest.ts b/examples/example-app-v17/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-v18/setup-jest-esm.ts b/examples/example-app-v18/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-v18/setup-jest.ts b/examples/example-app-v18/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-yarn-workspace/packages/angular-app/setup-jest-esm.ts b/examples/example-app-yarn-workspace/packages/angular-app/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-yarn-workspace/packages/angular-app/setup-jest.ts b/examples/example-app-yarn-workspace/packages/angular-app/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-yarn-workspace/packages/user/setup-jest-esm.ts b/examples/example-app-yarn-workspace/packages/user/setup-jest-esm.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest.mjs';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/examples/example-app-yarn-workspace/packages/user/setup-jest.ts b/examples/example-app-yarn-workspace/packages/user/setup-jest.ts
@@ -1,2 +1,4 @@
-import 'jest-preset-angular/setup-jest';
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
 import './jest-global-mocks';
+
+setupZoneTestEnv();
diff --git a/scripts/test-examples.js b/scripts/test-examples.js
@@ -43,6 +43,7 @@ const executeTest = (projectPath) => {
         'package.json',
         'setup-jest.js',
         'setup-jest.mjs',
+        'setup-env',
     ].forEach((asset) => {
         const assetToReplace = join(projectPath, 'node_modules', 'jest-preset-angular', asset);
         const assetToCopy = join(rootDir, asset);
diff --git a/setup-env/utils.mjs b/setup-env/utils.mjs
@@ -0,0 +1,19 @@
+import { TextDecoder, TextEncoder } from 'util';
+
+export const polyfillEncoder = () => {
+    if (typeof globalThis.TextEncoder === 'undefined') {
+        globalThis.TextEncoder = TextEncoder;
+        globalThis.TextDecoder = TextDecoder;
+    }
+};
+
+export const resolveTestEnvOptions = (options) => {
+    const globalTestEnvOptions = globalThis.ngJest?.testEnvironmentOptions;
+    if (globalTestEnvOptions) {
+        console.warn(
+            'Setting testEnvironmentOptions via globalThis.ngJest is deprecated. Please provide testEnvironmentOptions via function argument',
+        );
+    }
+
+    return globalTestEnvOptions ?? options;
+};
diff --git a/setup-env/zone/index.d.mts b/setup-env/zone/index.d.mts
@@ -0,0 +1,3 @@
+import type { TestEnvironmentOptions } from '@angular/core/testing';
+
+export declare const setupZoneTestEnv: (options?: TestEnvironmentOptions) => void;
diff --git a/setup-env/zone/index.d.ts b/setup-env/zone/index.d.ts
@@ -0,0 +1,6 @@
+import type { TestEnvironmentOptions } from '@angular/core/testing';
+
+declare const _default: {
+    setupZoneTestEnv: (options?: TestEnvironmentOptions) => void;
+};
+export = _default;
diff --git a/setup-env/zone/index.js b/setup-env/zone/index.js
@@ -0,0 +1,43 @@
+require('zone.js');
+require('zone.js/testing');
+
+const { TextEncoder, TextDecoder } = require('util');
+
+const { getTestBed } = require('@angular/core/testing');
+const {
+    BrowserDynamicTestingModule,
+    platformBrowserDynamicTesting,
+} = require('@angular/platform-browser-dynamic/testing');
+
+const polyfillEncoder = () => {
+    if (typeof globalThis.TextEncoder === 'undefined') {
+        globalThis.TextEncoder = TextEncoder;
+        globalThis.TextDecoder = TextDecoder;
+    }
+};
+
+const resolveTestEnvOptions = (options) => {
+    const globalTestEnvOptions = globalThis.ngJest?.testEnvironmentOptions;
+    if (globalTestEnvOptions) {
+        console.warn(
+            'Setting testEnvironmentOptions via globalThis.ngJest is deprecated. Please provide testEnvironmentOptions via function argument',
+        );
+    }
+
+    return globalTestEnvOptions ?? options;
+};
+
+const setupZoneTestEnv = (options) => {
+    polyfillEncoder();
+    const testEnvironmentOptions = resolveTestEnvOptions(options);
+
+    getTestBed().initTestEnvironment(
+        BrowserDynamicTestingModule,
+        platformBrowserDynamicTesting(),
+        testEnvironmentOptions,
+    );
+};
+
+module.exports = {
+    setupZoneTestEnv,
+};
diff --git a/setup-env/zone/index.mjs b/setup-env/zone/index.mjs
@@ -0,0 +1,18 @@
+import 'zone.js';
+import 'zone.js/testing';
+
+import { getTestBed } from '@angular/core/testing';
+import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
+
+import { polyfillEncoder, resolveTestEnvOptions } from '../utils.mjs';
+
+export const setupZoneTestEnv = (options) => {
+    polyfillEncoder();
+    const testEnvironmentOptions = resolveTestEnvOptions(options);
+
+    getTestBed().initTestEnvironment(
+        BrowserDynamicTestingModule,
+        platformBrowserDynamicTesting(),
+        testEnvironmentOptions,
+    );
+};
diff --git a/setup-env/zoneless/index.d.mts b/setup-env/zoneless/index.d.mts
@@ -0,0 +1,3 @@
+import type { TestEnvironmentOptions } from '@angular/core/testing';
+
+export declare const setupZonelessTestEnv: (options?: TestEnvironmentOptions) => void;
diff --git a/setup-env/zoneless/index.d.ts b/setup-env/zoneless/index.d.ts
@@ -0,0 +1,6 @@
+import type { TestEnvironmentOptions } from '@angular/core/testing';
+
+declare const _default: {
+    setupZonelessTestEnv: (options?: TestEnvironmentOptions) => void;
+};
+export = _default;
diff --git a/setup-env/zoneless/index.js b/setup-env/zoneless/index.js
@@ -0,0 +1,11 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const setupZonelessTestEnv = (_options) => {
+    throw Error(
+        'Zoneless testing environment only works when running Jest in ESM mode with Jest 29. ' +
+            'Jest 30+ will support to work with CommonJS mode.',
+    );
+};
+
+module.exports = {
+    setupZonelessTestEnv,
+};
diff --git a/setup-env/zoneless/index.mjs b/setup-env/zoneless/index.mjs
@@ -0,0 +1,39 @@
+import { ErrorHandler, NgModule, provideExperimentalZonelessChangeDetection } from '@angular/core';
+import { getTestBed } from '@angular/core/testing';
+import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
+
+import { polyfillEncoder, resolveTestEnvOptions } from '../utils.mjs';
+
+export const setupZonelessTestEnv = (options) => {
+    if (typeof provideExperimentalZonelessChangeDetection !== 'undefined') {
+        polyfillEncoder();
+        const testEnvironmentOptions = resolveTestEnvOptions(options);
+        @NgModule({
+            providers: [
+                provideExperimentalZonelessChangeDetection(),
+                {
+                    provide: ErrorHandler,
+                    useValue: {
+                        handleError: (e) => {
+                            throw e;
+                        },
+                    },
+                },
+            ],
+        })
+        export class TestModule {}
+
+        getTestBed().initTestEnvironment(
+            [BrowserDynamicTestingModule, TestModule],
+            platformBrowserDynamicTesting(),
+            testEnvironmentOptions,
+        );
+
+        return;
+    }
+
+    throw Error(
+        'Cannot find provideExperimentalZonelessChangeDetection() to setup zoneless testing environment. ' +
+            'Please use setupZoneTestEnv() from jest-preset-angular/setup-env/setup-zone-env.mjs instead.',
+    );
+};
diff --git a/src/config/setup-jest.spec.ts b/src/config/setup-jest.spec.ts
@@ -85,6 +85,39 @@ describe('setup-jest', () => {
 
             expect(globalThis.TextEncoder).toBeDefined();
         });
+
+        it('should call getTestBed() and initTestEnvironment() with the testEnvironmentOptions passed as argument with setupZoneTestEnv()', async () => {
+            const { setupZoneTestEnv } = await import('../../setup-env/zone/index.js');
+
+            setupZoneTestEnv({
+                teardown: {
+                    destroyAfterEach: false,
+                    rethrowErrors: true,
+                },
+                errorOnUnknownElements: true,
+                errorOnUnknownProperties: true,
+            });
+
+            expect(mockZoneJs).toHaveBeenCalled();
+            expect(mockZoneJsTesting).toHaveBeenCalled();
+            assertOnInitTestEnv();
+            expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
+                teardown: {
+                    destroyAfterEach: false,
+                    rethrowErrors: true,
+                },
+                errorOnUnknownElements: true,
+                errorOnUnknownProperties: true,
+            });
+        });
+
+        it('should always have TextEncoder in globalThis with setupZoneTestEnv()', async () => {
+            const { setupZoneTestEnv } = await import('../../setup-env/zone/index.js');
+
+            setupZoneTestEnv();
+
+            expect(globalThis.TextEncoder).toBeDefined();
+        });
     });
 
     describe('for ESM setup-jest, test environment initialization', () => {
@@ -120,5 +153,38 @@ describe('setup-jest', () => {
 
             expect(globalThis.TextEncoder).toBeDefined();
         });
+
+        it('should call getTestBed() and initTestEnvironment() with the testEnvironmentOptions passed as argument with setupZoneTestEnv()', async () => {
+            const { setupZoneTestEnv } = await import('../../setup-env/zone/index.mjs');
+
+            setupZoneTestEnv({
+                teardown: {
+                    destroyAfterEach: false,
+                    rethrowErrors: true,
+                },
+                errorOnUnknownElements: true,
+                errorOnUnknownProperties: true,
+            });
+
+            expect(mockZoneJs).toHaveBeenCalled();
+            expect(mockZoneJsTesting).toHaveBeenCalled();
+            assertOnInitTestEnv();
+            expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
+                teardown: {
+                    destroyAfterEach: false,
+                    rethrowErrors: true,
+                },
+                errorOnUnknownElements: true,
+                errorOnUnknownProperties: true,
+            });
+        });
+
+        it('should always have TextEncoder in globalThis with setupZoneTestEnv()', async () => {
+            const { setupZoneTestEnv } = await import('../../setup-env/zone/index.mjs');
+
+            setupZoneTestEnv();
+
+            expect(globalThis.TextEncoder).toBeDefined();
+        });
     });
 });
diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md
diff --git a/website/docs/getting-started/test-environment.md b/website/docs/getting-started/test-environment.md
diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md
