docs: update testing guides for Vitest and reorder navigation

This commit updates the unit testing, code coverage, and debugging guides to align with the Vitest test runner, which is now the default for new Angular CLI projects.

Key changes include:
- **Unit Testing Overview**: Revised to focus on Vitest, including details on DOM emulation (jsdom/happy-dom), browser testing setup, and custom Vitest configuration via `runnerConfig`. A prominent note links to the Karma-to-Vitest migration guide.
- **Code Coverage**: Updated to reflect Vitest-specific prerequisites (`@vitest/coverage-v8`), command-line flags, and `angular.json` configuration for coverage reporting and threshold enforcement.
- **Debugging**: Completely rewritten to provide instructions for debugging Vitest tests in both Node.js and browser environments using the `--debug` flag.
- **Navigation Reordering**: The 'Testing' section in `sub-navigation-data.ts` has been reordered to present a more logical educational flow, starting with core concepts and progressing to advanced topics and migration.

Author: clydin

adev/src/app/routing/sub-navigation-data.ts

@@ -521,21 +521,6 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
             path: 'guide/testing',
             contentPath: 'guide/testing/overview',
           },
-          {
-            label: 'Code coverage',
-            path: 'guide/testing/code-coverage',
-            contentPath: 'guide/testing/code-coverage',
-          },
-          {
-            label: 'Testing with Karma and Jasmine',
-            path: 'guide/testing/karma',
-            contentPath: 'guide/testing/karma',
-          },
-          {
-            label: 'Testing services',
-            path: 'guide/testing/services',
-            contentPath: 'guide/testing/services',
-          },
           {
             label: 'Basics of testing components',
             path: 'guide/testing/components-basics',
@@ -546,6 +531,11 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
             path: 'guide/testing/components-scenarios',
             contentPath: 'guide/testing/components-scenarios',
           },
+          {
+            label: 'Testing services',
+            path: 'guide/testing/services',
+            contentPath: 'guide/testing/services',
+          },
           {
             label: 'Testing attribute directives',
             path: 'guide/testing/attribute-directives',
@@ -567,16 +557,16 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
             path: 'guide/testing/debugging',
             contentPath: 'guide/testing/debugging',
           },
+          {
+            label: 'Code coverage',
+            path: 'guide/testing/code-coverage',
+            contentPath: 'guide/testing/code-coverage',
+          },
           {
             label: 'Testing utility APIs',
             path: 'guide/testing/utility-apis',
             contentPath: 'guide/testing/utility-apis',
           },
-          {
-            label: 'Migrating from Karma to Vitest',
-            path: 'guide/testing/unit-tests',
-            contentPath: 'guide/testing/migrating-to-vitest',
-          },
           {
             label: 'Component harnesses overview',
             path: 'guide/testing/component-harnesses-overview',
@@ -597,6 +587,16 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
             path: 'guide/testing/component-harnesses-testing-environments',
             contentPath: 'guide/testing/component-harnesses-testing-environments',
           },
+          {
+            label: 'Migrating from Karma to Vitest',
+            path: 'guide/testing/migrating-to-vitest',
+            contentPath: 'guide/testing/migrating-to-vitest',
+          },
+          {
+            label: 'Testing with Karma and Jasmine',
+            path: 'guide/testing/karma',
+            contentPath: 'guide/testing/karma',
+          },
         ],
       },
       {

adev/src/content/guide/testing/code-coverage.md

@@ -1,25 +1,42 @@
-# Find out how much code you're testing
+# Code coverage
 
-The Angular CLI can run unit tests and create code coverage reports.
 Code coverage reports show you any parts of your code base that might not be properly tested by your unit tests.
 
-To generate a coverage report run the following command in the root of your project.
+## Prerequisites
+
+To generate code coverage reports with Vitest, you must install the `@vitest/coverage-v8` package:
+
+<docs-code-multifile>
+  <docs-code header="pnpm" language="shell">
+    pnpm add -D @vitest/coverage-v8
+  </docs-code>
+  <docs-code header="npm" language="shell">
+    npm install --save-dev @vitest/coverage-v8
+  </docs-code>
+  <docs-code header="yarn" language="shell">
+    yarn add --dev @vitest/coverage-v8
+  </docs-code>
+</docs-code-multifile>
+
+## Generating a report
+
+To generate a coverage report, add the `--coverage` flag to the `ng test` command:
 
 ```shell
-ng test --no-watch --coverage
+ng test --coverage
 ```
 
-When the tests are complete, the command creates a new `/coverage` directory in the project.
-Open the `index.html` file to see a report with your source code and code coverage values.
+After the tests run, the command creates a new `coverage/` directory in the project. Open the `index.html` file to see a report with your source code and code coverage values.
 
-If you want to create code-coverage reports every time you test, set the following option in the Angular CLI configuration file, `angular.json`:
+If you want to create code-coverage reports every time you test, you can set the `coverage` option to `true` in your `angular.json` file:
 
 ```json
 {
   "projects": {
     "your-project-name": {
       "architect": {
         "test": {
+          "builder": "@angular/build:unit-test",
           "options": {
             "coverage": true
           }
@@ -30,20 +47,19 @@ If you want to create code-coverage reports every time you test, set the followi
 }
 ```
 
-## Code coverage enforcement
+## Enforcing code coverage thresholds
 
-The code coverage percentages let you estimate how much of your code is tested.
-If your team decides on a set minimum amount to be unit tested, you can enforce this minimum directly in your Angular CLI configuration.
+The code coverage percentages let you estimate how much of your code is tested. If your team decides on a minimum amount to be unit tested, you can enforce this minimum in your configuration.
 
-For example, suppose you want the code base to have a minimum of 80% code coverage.
-To enable this, open the `angular.json` file and add the `coverageThresholds` option to your test configuration:
+For example, suppose you want the code base to have a minimum of 80% code coverage. To enable this, add the `coverageThresholds` option to your `angular.json` file:
 
 ```json
 {
   "projects": {
     "your-project-name": {
       "architect": {
         "test": {
+          "builder": "@angular/build:unit-test",
           "options": {
             "coverage": true,
             "coverageThresholds": {
@@ -60,4 +76,36 @@ To enable this, open the `angular.json` file and add the `coverageThresholds` op
 }
 ```
 
-Now, when you run `ng test`, the tool will throw an error if the coverage drops below 80%.
+Now, if your coverage drops below 80% when you run your tests, the command will fail.
+
+## Advanced configuration
+
+You can configure several other coverage options in your `angular.json` file:
+
+- `coverageInclude`: Glob patterns of files to include in the coverage report.
+- `coverageReporters`: An array of reporters to use (e.g., `html`, `lcov`, `json`).
+- `coverageWatermarks`: An object specifying `[low, high]` watermarks for the HTML reporter, which can affect the color-coding of the report.
+
+```json
+{
+  "projects": {
+    "your-project-name": {
+      "architect": {
+        "test": {
+          "builder": "@angular/build:unit-test",
+          "options": {
+            "coverage": true,
+            "coverageReporters": ["html", "lcov"],
+            "coverageWatermarks": {
+              "statements": [50, 80],
+              "branches": [50, 80],
+              "functions": [50, 80],
+              "lines": [50, 80]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```

adev/src/content/guide/testing/debugging.md

@@ -1,19 +1,30 @@
 # Debugging tests
 
-If your tests aren't working as you expect them to, you can inspect and debug them in the browser.
+If your tests aren't working as you expect, you can debug them in both the default Node.js environment and in a real browser.
 
-NOTE: This guide describes debugging with the Karma test runner.
+## Debugging in Node.js
 
-To debug an application with the Karma test runner:
+Debugging in the default Node.js environment is often the quickest way to diagnose issues that are not related to browser-specific APIs or rendering.
 
-1. Reveal the Karma browser window.
-   See [Set up testing](guide/testing#set-up-testing) if you need help with this step.
+1.  Run the `ng test` command with the `--debug` flag:
+    ```shell
+    ng test --debug
+    ```
+2.  The test runner will start in debug mode and wait for a debugger to attach.
+3.  You can now attach your preferred debugger. For example, you can use the built-in Node.js debugger in VS Code or the Chrome DevTools for Node.js.
 
-1. Click the **DEBUG** button to open a new browser tab and re-run the tests.
-1. Open the browser's **Developer Tools**. On Windows, press `Ctrl-Shift-I`. On macOS, press `Command-Option-I`.
-1. Pick the **Sources** section.
-1. Press `Control/Command-P`, and then start typing the name of your test file to open it.
-1. Set a breakpoint in the test.
-1. Refresh the browser, and notice how it stops at the breakpoint.
+## Debugging in a browser
 
-<img alt="Karma debugging" src="assets/images/guide/testing/karma-1st-spec-debug.png">
+Debugging in a browser is recommended for tests that rely on the DOM or other browser-specific APIs. This approach allows you to use the browser's own developer tools.
+
+1.  Ensure you have a browser provider installed. See [Running tests in a browser](guide/testing/overview#running-tests-in-a-browser) for setup instructions.
+2.  Run the `ng test` command with both the `--browsers` and `--debug` flags:
+    ```shell
+    ng test --browsers=chromium --debug
+    ```
+3.  This command runs the tests in a headed browser and keeps it open after the tests finish, allowing you to inspect the output.
+4.  Open the browser's **Developer Tools**. On Windows, press `Ctrl-Shift-I`. On macOS, press `Command-Option-I`.
+5.  Go to the **Sources** tab.
+6.  Use `Control/Command-P` to search for and open your test file.
+7.  Set a breakpoint in your test.
+8.  Reload the test runner UI in the browser. The execution will now stop at your breakpoint.

adev/src/content/guide/testing/karma.md

@@ -180,3 +180,19 @@ ng test --no-watch --no-progress --browsers=ChromeHeadless
 ```
 
 NOTE: The `--no-watch` and `--no-progress` flags are crucial for Karma in CI environments to ensure tests run once and exit cleanly. The `--browsers=ChromeHeadless` flag is also essential for running tests in a browser environment without a graphical interface.
+
+## Debugging tests
+
+If your tests aren't working as you expect, you can inspect and debug them in the browser.
+
+To debug an application with the Karma test runner:
+
+1.  Reveal the Karma browser window. See [Set up for testing](guide/testing/overview#set-up-for-testing) if you need help with this step.
+2.  Click the **DEBUG** button to open a new browser tab and re-run the tests.
+3.  Open the browser's **Developer Tools**. On Windows, press `Ctrl-Shift-I`. On macOS, press `Command-Option-I`.
+4.  Pick the **Sources** section.
+5.  Press `Control/Command-P`, and then start typing the name of your test file to open it.
+6.  Set a breakpoint in the test.
+7.  Refresh the browser, and notice how it stops at the breakpoint.
+
+<img alt="Karma debugging" src="assets/images/guide/testing/karma-1st-spec-debug.png">