docs: refactor test environment related pages

- `test-environment.md` -> `testbed-environment.md`
- `jsdom-version.md` -> `jsdom-environment`
- Deprecate old doc pages

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

@@ -3,6 +3,12 @@ id: test-environment
 title: Test environment
 ---
 
+:::warning DEPRECATED
+
+This page is now **DEPRECATED** and will be removed in the next major release. Please visit [TestBed environment configuration](testbed-environment.md)
+
+:::
+
 In Jest, a test environment defines the sandbox context in which your tests run.
 For Angular projects, setting up the correct test environment is essential to ensure compatibility with the
 framework-specific features, such as dependency injection and change detection.

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

@@ -0,0 +1,124 @@
+---
+id: testbed-environment
+title: TestBed environment
+---
+
+Angular provides a powerful testing utility called [TestBed](https://angular.dev/api/core/testing/TestBed),
+which allows to configure and initialize an environment for unit testing and provides methods for creating components and services in unit tests.
+
+`jest-preset-angular` provides utility functions to simplify setting up `TestBed` environment. These below utility functions
+support both **zone-based** and **zoneless** environments, catering to different testing needs.
+
+## Functions
+
+import TOCInline from '@theme/TOCInline';
+
+<TOCInline toc={toc.slice(1)} />
+
+---
+
+### `setupZoneTestEnv(options)`
+
+Configures an environment that uses `zone.js`, which is the mechanism for tracking asynchronous operations.
+It is suitable for most Angular applications that rely on `zone.js` for change detection and other framework features.
+
+You can customize the environment by providing options as function arguments.
+
+#### Parameters
+
+- `options`**(optional)**: An object follows [TestEnvironmentOptions interface](https://github.com/angular/angular/blob/a55341b1ab8d2bc4285a4cce59df7fc0b23c0125/packages/core/testing/src/test_bed_common.ts#L95), which allows fine-tuning the environment.
+
+#### Example:
+
+- Create a Jest setup file:
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript CJS"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+
+setupZoneTestEnv({
+  //...options
+});
+```
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript ESM"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
+
+setupZoneTestEnv({
+  //...options
+});
+```
+
+- Update your Jest configuration:
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createCjsPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createEsmPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```
+
+### `setupZonelessTestEnv(options)`
+
+Configures an environment that **DOESN'T** use `zone.js`, as described in [Angular experimental zoneless guide](https://angular.dev/guide/experimental/zoneless).
+It is designed for projects that have disabled `zone.js`, which can lead to improved performance and simplified testing.
+
+You can customize the environment by providing options as function arguments.
+
+#### Parameters
+
+- `options`**(optional)**: An object follows [TestEnvironmentOptions interface](https://github.com/angular/angular/blob/a55341b1ab8d2bc4285a4cce59df7fc0b23c0125/packages/core/testing/src/test_bed_common.ts#L95), which allows fine-tuning the environment.
+
+#### Example:
+
+- Create a Jest setup file:
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript CJS"}
+import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless';
+
+setupZonelessTestEnv({
+  //...options
+});
+```
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript ESM"}
+import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless/index.mjs';
+
+setupZonelessTestEnv({
+  //...options
+});
+```
+
+- Update your Jest configuration:
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createCjsPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createEsmPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```

website/docs/guides/angular-ivy.md

@@ -3,7 +3,7 @@ id: angular-ivy
 title: Angular Ivy
 ---
 
-:::warning
+:::warning DEPRECATED
 
 This guide is now **DEPRECATED** and will be removed in the next major release together with the below APIs.
 

website/docs/guides/jsdom-environment.md

@@ -0,0 +1,31 @@
+---
+id: jsdom-environment
+title: JSDOM environment
+---
+
+`jest-preset-angular` provides a way to configure a different version of [JSDOM](https://github.com/jsdom/jsdom) than the one ships with `Jest`
+via a custom `JSDOM` environment. One can follow the below steps to configure a different `JSDOM` version:
+
+- Install the desired JSDOM version
+
+```bash npm2yarn
+npm install -D jsdom@<desired-version>
+```
+
+- In Jest config, set the `testEnvironment` like following
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+
+export default {
+  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env',
+} satisfies Config;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+
+export default {
+  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env',
+} satisfies Config;
+```

website/docs/guides/jsdom-version.md

@@ -3,6 +3,12 @@ id: jsdom-version
 title: JSDOM version
 ---
 
+:::warning DEPRECATED
+
+This page is now **DEPRECATED** and will be removed in the next major release. Please visit [JSDOM environment configuration](jsdom-environment.md)
+
+:::
+
 `jest-preset-angular` provides a way to configure a different version of `JSDOM` than the one ships with `Jest`
 via a custom `JSDOM` environment. One can follow the below steps to configure a different JSDOM version:
 

website/sidebars.json

@@ -8,12 +8,14 @@
       "getting-started/installation",
       "getting-started/presets",
       "getting-started/options",
-      "getting-started/test-environment"
+      "getting-started/test-environment",
+      "getting-started/testbed-environment"
     ],
     "Guides": [
       "guides/angular-ivy",
       "guides/angular-13+",
       "guides/esm-support",
+      "guides/jsdom-environment",
       "guides/jsdom-version",
       "guides/snapshot-testing",
       "guides/using-with-babel",

website/versioned_docs/version-14.5/getting-started/test-environment.md

@@ -3,6 +3,12 @@ id: test-environment
 title: Test environment
 ---
 
+:::warning DEPRECATED
+
+This page is now **DEPRECATED** and will be removed in the next major release. Please visit [TestBed environment configuration](testbed-environment.md)
+
+:::
+
 In Jest, a test environment defines the sandbox context in which your tests run.
 For Angular projects, setting up the correct test environment is essential to ensure compatibility with the
 framework-specific features, such as dependency injection and change detection.

website/versioned_docs/version-14.5/getting-started/testbed-environment.md

@@ -0,0 +1,124 @@
+---
+id: testbed-environment
+title: TestBed environment
+---
+
+Angular provides a powerful testing utility called [TestBed](https://angular.dev/api/core/testing/TestBed),
+which allows to configure and initialize an environment for unit testing and provides methods for creating components and services in unit tests.
+
+`jest-preset-angular` provides utility functions to simplify setting up `TestBed` environment. These below utility functions
+support both **zone-based** and **zoneless** environments, catering to different testing needs.
+
+## Functions
+
+import TOCInline from '@theme/TOCInline';
+
+<TOCInline toc={toc.slice(1)} />
+
+---
+
+### `setupZoneTestEnv(options)`
+
+Configures an environment that uses `zone.js`, which is the mechanism for tracking asynchronous operations.
+It is suitable for most Angular applications that rely on `zone.js` for change detection and other framework features.
+
+You can customize the environment by providing options as function arguments.
+
+#### Parameters
+
+- `options`**(optional)**: An object follows [TestEnvironmentOptions interface](https://github.com/angular/angular/blob/a55341b1ab8d2bc4285a4cce59df7fc0b23c0125/packages/core/testing/src/test_bed_common.ts#L95), which allows fine-tuning the environment.
+
+#### Example:
+
+- Create a Jest setup file:
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript CJS"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+
+setupZoneTestEnv({
+  //...options
+});
+```
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript ESM"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
+
+setupZoneTestEnv({
+  //...options
+});
+```
+
+- Update your Jest configuration:
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createCjsPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createEsmPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```
+
+### `setupZonelessTestEnv(options)`
+
+Configures an environment that **DOESN'T** use `zone.js`, as described in [Angular experimental zoneless guide](https://angular.dev/guide/experimental/zoneless).
+It is designed for projects that have disabled `zone.js`, which can lead to improved performance and simplified testing.
+
+You can customize the environment by providing options as function arguments.
+
+#### Parameters
+
+- `options`**(optional)**: An object follows [TestEnvironmentOptions interface](https://github.com/angular/angular/blob/a55341b1ab8d2bc4285a4cce59df7fc0b23c0125/packages/core/testing/src/test_bed_common.ts#L95), which allows fine-tuning the environment.
+
+#### Example:
+
+- Create a Jest setup file:
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript CJS"}
+import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless';
+
+setupZonelessTestEnv({
+  //...options
+});
+```
+
+```ts title="setup-jest.ts" tab={"label": "TypeScript ESM"}
+import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless/index.mjs';
+
+setupZonelessTestEnv({
+  //...options
+});
+```
+
+- Update your Jest configuration:
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createCjsPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+import presets from 'jest-preset-angular/presets';
+
+export default {
+  ...presets.createEsmPreset(),
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+} satisfies Config;
+```

website/versioned_docs/version-14.5/guides/angular-ivy.md

@@ -3,7 +3,7 @@ id: angular-ivy
 title: Angular Ivy
 ---
 
-:::warning
+:::warning DEPRECATED
 
 This guide is now **DEPRECATED** and will be removed in the next major release together with the below APIs.
 

website/versioned_docs/version-14.5/guides/jsdom-environment.md

@@ -0,0 +1,31 @@
+---
+id: jsdom-environment
+title: JSDOM environment
+---
+
+`jest-preset-angular` provides a way to configure a different version of [JSDOM](https://github.com/jsdom/jsdom) than the one ships with `Jest`
+via a custom `JSDOM` environment. One can follow the below steps to configure a different `JSDOM` version:
+
+- Install the desired JSDOM version
+
+```bash npm2yarn
+npm install -D jsdom@<desired-version>
+```
+
+- In Jest config, set the `testEnvironment` like following
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+
+export default {
+  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env',
+} satisfies Config;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+
+export default {
+  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env',
+} satisfies Config;
+```

website/versioned_docs/version-14.5/guides/jsdom-version.md

@@ -3,6 +3,12 @@ id: jsdom-version
 title: JSDOM version
 ---
 
+:::warning DEPRECATED
+
+This page is now **DEPRECATED** and will be removed in the next major release. Please visit [JSDOM environment configuration](jsdom-environment.md)
+
+:::
+
 `jest-preset-angular` provides a way to configure a different version of `JSDOM` than the one ships with `Jest`
 via a custom `JSDOM` environment. One can follow the below steps to configure a different JSDOM version: