From 627ee1f34dfec40c3deba3c766b6aae1c0629a32 Mon Sep 17 00:00:00 2001
From: quilicicf <quilicicf@gmail.com>
Date: Sun, 22 Jun 2025 14:49:15 +0200
Subject: [PATCH] docs(tests): Documentation for `jsdomIt` tests

---
 docs/community/contributing.md                | 26 ++++++++++++++++++-
 .../src/docs/community/contributing.md        | 26 ++++++++++++++++++-
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/docs/community/contributing.md b/docs/community/contributing.md
index 596b26430..ce010b316 100644
--- a/docs/community/contributing.md
+++ b/docs/community/contributing.md
@@ -301,7 +301,7 @@ If you are adding a feature, you will definitely need to add tests. Depending on
 
 Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run.
 
-Unit tests are mandatory for all code except the renderers. (The renderers are tested with integration tests.)
+Unit tests are mandatory for all code except the layout tests. (The layouts are tested with integration tests.)
 
 We use [Vitest](https://vitest.dev) to run unit tests.
 
@@ -327,6 +327,30 @@ When using Docker prepend your command with `./run`:
 ./run pnpm test
 ```
 
+##### Testing the DOM
+
+One can use `jsdomIt` to test any part of Mermaid that interacts with the DOM, as long as it is not related to the layout.
+
+The function `jsdomIt` ([developed in utils.ts](../../tests/util.ts)) overrides `it` from `vitest`, and creates a pseudo-browser environment that works almost like the real deal for the duration of the test. It uses JSDOM to create a DOM, and adds objects `window` and `document` to `global` to mock the browser environment.
+
+> \[!NOTE]
+> The layout cannot work in `jsdomIt` tests because JSDOM has no rendering engine, hence the pseudo-browser environment.
+
+Example :
+
+```typescript
+import { ensureNodeFromSelector, jsdomIt } from './tests/util.js';
+
+jsdomIt('should add element "thing" in the SVG', ({ svg }) => {
+  // Code in this block runs in a pseudo-browser environment
+  addThing(svg); // The svg item is the D3 selection of the SVG node
+  const svgNode = ensureNodeFromSelector('svg'); // Retrieve the DOM node using the DOM API
+  expect(svgNode.querySelector('thing')).not.toBeNull(); // Test the structure of the SVG
+});
+```
+
+They can be used to test any method that interacts with the DOM, including for testing renderers. For renderers, additional integration testing is necessary to test the layout though.
+
 #### Integration / End-to-End (E2E) Tests
 
 These test the rendering and visual appearance of the diagrams.
diff --git a/packages/mermaid/src/docs/community/contributing.md b/packages/mermaid/src/docs/community/contributing.md
index 62d06f72f..c35803c23 100644
--- a/packages/mermaid/src/docs/community/contributing.md
+++ b/packages/mermaid/src/docs/community/contributing.md
@@ -302,7 +302,7 @@ If you are adding a feature, you will definitely need to add tests. Depending on
 
 Unit tests are tests that test a single function or module. They are the easiest to write and the fastest to run.
 
-Unit tests are mandatory for all code except the renderers. (The renderers are tested with integration tests.)
+Unit tests are mandatory for all code except the layout tests. (The layouts are tested with integration tests.)
 
 We use [Vitest](https://vitest.dev) to run unit tests.
 
@@ -328,6 +328,30 @@ When using Docker prepend your command with `./run`:
 ./run pnpm test
 ```
 
+##### Testing the DOM
+
+One can use `jsdomIt` to test any part of Mermaid that interacts with the DOM, as long as it is not related to the layout.
+
+The function `jsdomIt` ([developed in utils.ts](../../tests/util.ts)) overrides `it` from `vitest`, and creates a pseudo-browser environment that works almost like the real deal for the duration of the test. It uses JSDOM to create a DOM, and adds objects `window` and `document` to `global` to mock the browser environment.
+
+> [!NOTE]
+> The layout cannot work in `jsdomIt` tests because JSDOM has no rendering engine, hence the pseudo-browser environment.
+
+Example :
+
+```typescript
+import { ensureNodeFromSelector, jsdomIt } from './tests/util.js';
+
+jsdomIt('should add element "thing" in the SVG', ({ svg }) => {
+  // Code in this block runs in a pseudo-browser environment
+  addThing(svg); // The svg item is the D3 selection of the SVG node
+  const svgNode = ensureNodeFromSelector('svg'); // Retrieve the DOM node using the DOM API
+  expect(svgNode.querySelector('thing')).not.toBeNull(); // Test the structure of the SVG
+});
+```
+
+They can be used to test any method that interacts with the DOM, including for testing renderers. For renderers, additional integration testing is necessary to test the layout though.
+
 #### Integration / End-to-End (E2E) Tests
 
 These test the rendering and visual appearance of the diagrams.