Merge remote-tracking branch 'origin/master' into pankhur94/channel-e…

…rror-changes

.vscode/launch.json

@@ -1098,22 +1098,28 @@
       "request": "launch",
       "name": "Run Vitest Browser",
       "console": "integratedTerminal",
-      "cwd": "${workspaceFolder}/core/frontend",
-      "runtimeExecutable": "pnpm",
-      "runtimeArgs": [
-        "run",
-        "test",
-        "--inspect",
-        "--no-file-parallelism"
-      ],
+      "cwd": "${workspaceFolder}/core/frontend", // necessary to pick up frontend's vitest config
+      "program": "node_modules/vitest/vitest.mjs",
+      "args": ["--run", "--inspect", "--no-file-parallelism", "--test-timeout=0"], // disable test timeout while debugging
+      "autoAttachChildProcesses": true
     },
     {
       "type": "chrome",
       "request": "attach",
       "name": "Attach to Vitest Browser",
-      "url": "http://localhost:5173",
-      "timeout": 30000,
-      "port": 9229
+      "timeout": 60000, // Vitest setup could take longer than default timeout on Windows.
+      "port": 9229,
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Compile test worker for frontend tests",
+      "console": "integratedTerminal",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": [
+        "run",
+        "webpackTestWorker"
+      ],
     }
   ],
   "compounds": [
@@ -1127,6 +1133,7 @@
         "Attach to Vitest Browser",
         "Run Vitest Browser"
       ],
+      "preLaunchTask": "Run webpack for frontend test worker",
       "stopAll": true
     },
     {

.vscode/tasks.json

@@ -25,6 +25,13 @@
       ],
       "group": "build",
       "isBackground": true
-    }
+    },
+    {
+      "type": "npm",
+      "label": "Run webpack for frontend test worker",
+      "script": "webpackTestWorker",
+      "path": "core/frontend/",
+      "problemMatcher": []
+    },
   ]
 }

CONTRIBUTING.md

@@ -9,6 +9,8 @@ The goal of this document is to provide a high-level overview of how you can get
   - [Repo Setup](#repo-setup)
   - [Source Code Edit Workflow](#source-code-edit-workflow)
     - [Other NPM Scripts](#other-npm-scripts)
+    - [Debugging](#debugging)
+      - [Filtering Test Suites](#filtering-test-suites)
   - [Asking Questions](#asking-questions)
   - [Providing Feedback](#providing-feedback)
   - [Reporting Issues](#reporting-issues)
@@ -76,6 +78,68 @@ Here is a sample [changelog](https://github.com/microsoft/rushstack/blob/master/
 1. Build TypeDoc documentation for all packages: `rush docs`
 2. Build TypeDoc documentation for a single package: `cd core\backend` and then `rushx docs`
 
+### Debugging
+
+Custom VSCode tasks are found in [launch.json](/.vscode/launch.json) to make debugging easier for contributors. Navigate to the `Run and Debug` panel in VSCode and you can select one of many custom tasks to run, which will attach a debugger to the process, and stop at a breakpoint you've set up.
+
+#### Filtering Test Suites
+
+The custom scripts above run all tests found in their respective package. This monorepo contains packages using either mocha or vitest. Below is guidance for running specific tests using filters in either test library.
+
+<details>
+  <summary> Filtering Mocha tests</summary>
+
+Add a `.only` to a `describe()` or `it()` test function. Afterwards, run the custom VSCode task for the package through the `Run and Debug` panel, and mocha will run only that test suite. Example:
+
+```ts
+
+  // Both Car and Plane test suites are found in the same test file. Mocha detects the use of `.only()` and will ignore all other test files.
+  describe.only("Car", () => { // Mocha will only run the Car test suite.
+    it("should drive", () => ...);
+
+    it.only("should stop", () => ...); // Mocha will only run this test case and not the first one.
+  });
+
+  describe("Plane", () => {
+    it("should fly", () => ...)
+  });
+
+```
+</details>
+
+<details>
+  <summary>Filtering Vitest tests</summary>
+
+  There are 2 ways to filter Vitest tests:
+
+1. ​The [Vitest Explorer](https://marketplace.visualstudio.com/items?itemName=vitest.explorer) is a Visual Studio Code extension that enables running and debugging individual test cases. If unexpected behavior occurs after editing a test or source code, click the "Refresh Tests" button in the Testing view to reload your test suite and reflect any changes.
+
+![Vitest refresh tests helper](./docs/assets/vitest-explorer-help.png)
+
+> The Vitest Explorer is not compatible with tests running in a browser environment. The method below is the only viable way to debug browser-based tests.
+
+2. Edit the `vitest.config.mts` found in a package's root folder and add an [include](https://vitest.dev/config/#include) property to filter out tests. Afterwards, run the custom VSCode task for the package through the `Run and Debug` panel. For example, to test the `ViewRect` class in core-frontend (corresponding to the `ViewRect.test.ts` test), one would edit the `vitest.config.mts` for core-frontend as demonstrated below. By adding `.only` to a `describe()` or `it()` test function in `ViewRect.test.ts`, you can filter out tests in more detail.
+
+```typescript
+export default defineConfig({
+  esbuild: {
+    target: "es2022",
+  },
+  test: {
+    dir: "src",
+    setupFiles: "./src/test/setupTests.ts",
+    include: ["**/ViewRect.test.ts"], // Added here - the include property accepts a regex pattern.
+    browser: {
+      ...
+    },
+    ...
+  }
+  ...
+})
+```
+</details>
+
+To distinguish whether a package is using vitest or mocha, look at the `package.json` `devDependencies`.
 ## Asking Questions
 
 Have a question?
@@ -203,5 +267,3 @@ Use these instructions to update dependencies and devDependencies on external pa
 1. Go into the appropriate `package.json` file and update the semantic version range of the dependency you want to update.
 2. Run `rush check` to make sure that you are specifying consistent versions across the repository
 3. Run `rush update` to make sure the newer version of the module specified in #1 is installed
-
-

README.md

@@ -62,7 +62,7 @@ The following instructions will quickly set the repo up for you to edit the sour
 3. Build source: `rush build`
 4. Run tests: `rush cover`
 
-For more information, our [Contributing guide](./CONTRIBUTING.md) contains detailed instructions on typical source code editing workflows, our contribution standards, FAQs, instructions on how to post questions and et cetera.
+​For more information, please refer to our [Contributing Guide](https://github.com/iTwin/itwinjs-core/pull/7767/CONTRIBUTING.md), which provides detailed instructions on source code editing workflows, debugging tests, contribution standards, FAQs, and guidelines for posting questions.​
 
 ## Licensing
 

common/changes/@itwin/core-frontend/nam-debugger-frontend_2025-02-24-18-59.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-frontend",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-frontend"
+}

core/frontend/package.json

@@ -23,7 +23,6 @@
     "pseudolocalize": "betools pseudolocalize --englishDir ./src/public/locales/en --out ./public/locales/en-PSEUDO",
     "test": "npm run webpackTestWorker && vitest --run",
     "cover": "npm run webpackTestWorker && vitest --run",
-    "test:debug": "vitest --run",
     "webpackTests": "webpack --config ./src/test/utils/webpack.config.js 1>&2 && npm run -s webpackTestWorker",
     "webpackTestWorker": "webpack --config ./src/test/worker/webpack.config.js 1>&2 && cpx \"./lib/test/test-worker.js\" ./lib/test",
     "webpackWorkers": "webpack --config ./src/workers/ImdlParser/webpack.config.js 1>&2"

core/frontend/vitest.config.mts

@@ -8,6 +8,7 @@ export default defineConfig({
   test: {
     dir: "src",
     setupFiles: "./src/test/setupTests.ts",
+    // include: ["**/<insert-file-name-here>.test.ts"],
     browser: {
       provider: "playwright",
       enabled: true,