Merge branch 'develop' into pr/Ronid1/5066

* develop: (122 commits)
  Cleanup e2e.yml
  Ignore push events on merge queue
  Remove ::
  Remove ::
  Remove ::
  Debug
  Debug
  Remove spec selector
  Handle edge cases in E2E
  Always run combineArtifacts
  Fix error message
  Fix cache save
  Update cache key
  Notify users
  Flatten uploaded images
  Flatten uploaded images
  Use pixelmatch for image comparison
  Run all tests
  Fix lint
  Update lockfile
  ...

.github/pull_request_template.md

@@ -14,5 +14,5 @@ Make sure you
 
 - [ ] :book: have read the [contribution guidelines](https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md)
 - [ ] :computer: have added necessary unit/e2e tests.
-- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/development.md#3-update-documentation) is used for all new features.
+- [ ] :notebook: have added documentation. Make sure [`MERMAID_RELEASE_VERSION`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/docs/community/contributing.md#update-documentation) is used for all new features.
 - [ ] :bookmark: targeted `develop` branch

.github/workflows/e2e-applitools.yml

@@ -28,7 +28,7 @@ jobs:
       - if: ${{ ! env.USE_APPLI }}
         name: Warn if not using Applitools
         run: |
-          echo "::error,title=Not using Applitols::APPLITOOLS_API_KEY is empty, disabling Applitools for this run."
+          echo "::error,title=Not using Applitools::APPLITOOLS_API_KEY is empty, disabling Applitools for this run."
 
       - uses: actions/checkout@v4
 

.github/workflows/e2e.yml

@@ -1,16 +1,63 @@
+# We use github cache to save snapshots between runs.
+# For PRs and MergeQueues, the target commit is used, and for push events, github.event.previous is used.
+# If a snapshot for a given Hash is not found, we checkout that commit, run the tests and cache the snapshots.
+# These are then downloaded before running the E2E, providing the reference snapshots.
+# If there are any errors, the diff image is uploaded to artifacts, and the user is notified.
+
 name: E2E
 
 on:
   push:
+    branches-ignore:
+      - 'gh-readonly-queue/**'
   pull_request:
   merge_group:
 
 permissions:
   contents: read
 
+env:
+  # For PRs and MergeQueues, the target commit is used, and for push events, github.event.previous is used.
+  targetHash: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
+
 jobs:
+  cache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+
+      - name: Cache snapshots
+        id: cache-snapshot
+        uses: actions/cache@v4
+        with:
+          save-always: true
+          path: ./cypress/snapshots
+          key: ${{ runner.os }}-snapshots-${{ env.targetHash }}
+
+      # If a snapshot for a given Hash is not found, we checkout that commit, run the tests and cache the snapshots.
+      - name: Switch to base branch
+        if: ${{ steps.cache-snapshot.outputs.cache-hit != 'true' }}
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.targetHash }}
+
+      - name: Cypress run
+        uses: cypress-io/github-action@v4
+        id: cypress-snapshot-gen
+        if: ${{ steps.cache-snapshot.outputs.cache-hit != 'true' }}
+        with:
+          start: pnpm run dev
+          wait-on: 'http://localhost:9000'
+          browser: chrome
+
   e2e:
     runs-on: ubuntu-latest
+    needs: cache
     strategy:
       fail-fast: false
       matrix:
@@ -27,6 +74,14 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
+      # These cached snapshots are downloaded, providing the reference snapshots.
+      - name: Cache snapshots
+        id: cache-snapshot
+        uses: actions/cache/restore@v3
+        with:
+          path: ./cypress/snapshots
+          key: ${{ runner.os }}-snapshots-${{ env.targetHash }}
+
       # Install NPM dependencies, cache them correctly
       # and run all Cypress tests
       - name: Cypress run
@@ -38,6 +93,7 @@ jobs:
         with:
           start: pnpm run dev:coverage
           wait-on: 'http://localhost:9000'
+          browser: chrome
           # Disable recording if we don't have an API key
           # e.g. if this action was run from a fork
           record: ${{ secrets.CYPRESS_RECORD_KEY != '' }}
@@ -46,6 +102,7 @@ jobs:
           CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
           VITEST_COVERAGE: true
           CYPRESS_COMMIT: ${{ github.sha }}
+
       - name: Upload Coverage to Codecov
         uses: codecov/codecov-action@v3
         # Run step only pushes to develop and pull_requests
@@ -57,9 +114,55 @@ jobs:
           fail_ci_if_error: false
           verbose: true
           token: 6845cc80-77ee-4e17-85a1-026cd95e0766
+
+      # We upload the artifacts into numbered archives to prevent overwriting
       - name: Upload Artifacts
-        uses: actions/upload-artifact@v3
-        if: ${{ failure() && steps.cypress.conclusion == 'failure' }}
+        uses: actions/upload-artifact@v4
+        if: ${{ always() }}
+        with:
+          name: snapshots-${{ matrix.containers }}
+          retention-days: 1
+          path: ./cypress/snapshots
+
+  combineArtifacts:
+    needs: e2e
+    runs-on: ubuntu-latest
+    if: ${{ always() }}
+    steps:
+      # Download all snapshot artifacts and merge them into a single folder
+      - name: Download All Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: snapshots
+          pattern: snapshots-*
+          merge-multiple: true
+
+      # For successful push events, we save the snapshots cache
+      - name: Save snapshots cache
+        id: cache-upload
+        if: ${{ github.event_name == 'push' && needs.e2e.result != 'failure' }}
+        uses: actions/cache/save@v3
+        with:
+          path: ./snapshots
+          key: ${{ runner.os }}-snapshots-${{ github.event.after }}
+
+      - name: Flatten images to a folder
+        if: ${{ needs.e2e.result == 'failure'  }}
+        run: |
+          mkdir errors
+          cd snapshots
+          find . -mindepth 2 -type d -name "*__diff_output__*" -exec sh -c 'mv "$0"/*.png ../errors/' {} \;
+
+      - name: Upload Error snapshots
+        if: ${{ needs.e2e.result == 'failure' }}
+        uses: actions/upload-artifact@v4
+        id: upload-artifacts
         with:
           name: error-snapshots
-          path: cypress/snapshots/**/__diff_output__/*
+          retention-days: 10
+          path: errors/
+
+      - name: Notify Users
+        if: ${{ needs.e2e.result == 'failure' }}
+        run: |
+          echo "::error title=Visual tests failed::You can view images that failed by downloading the error-snapshots artifact: ${{ steps.upload-artifacts.outputs.artifact-url }}"

.github/workflows/link-checker.yml

@@ -36,7 +36,7 @@ jobs:
           restore-keys: cache-lychee-
 
       - name: Link Checker
-        uses: lycheeverse/lychee-action@v1.8.0
+        uses: lycheeverse/lychee-action@v1.9.1
         with:
           args: >-
             --config .github/lychee.toml

.github/workflows/release-draft.yml

@@ -3,7 +3,7 @@ name: Draft Release
 on:
   push:
     branches:
-      - develop
+      - master
 
 permissions:
   contents: read

.gitignore

@@ -46,3 +46,4 @@ stats/
 
 demos/dev/**
 !/demos/dev/example.html
+tsx-0/**

.npmrc

@@ -1,2 +1,3 @@
+registry=https://registry.npmjs.org
 auto-install-peers=true
 strict-peer-dependencies=false

CONTRIBUTING.md

@@ -0,0 +1 @@
+./packages/mermaid/src/docs/community/contributing.md

Dockerfile

@@ -0,0 +1,2 @@
+FROM node:18.19.0-alpine3.18 AS base
+RUN wget -qO- https://get.pnpm.io/install.sh | ENV="$HOME/.shrc" SHELL="$(which sh)" sh -

README.md

@@ -74,12 +74,12 @@ Mermaid addresses this problem by enabling users to create easily modifiable dia
 <br/>
 
 Mermaid allows even non-programmers to easily create detailed diagrams through the [Mermaid Live Editor](https://mermaid.live/).<br/>
-For video tutorials, visit our [Tutorials](./docs/config/Tutorials.md) page.
+For video tutorials, visit our [Tutorials](./docs/ecosystem/tutorials.md) page.
 Use Mermaid with your favorite applications, check out the list of [Integrations and Usages of Mermaid](./docs/ecosystem/integrations-community.md).
 
 You can also use Mermaid within [GitHub](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) as well many of your other favorite applications—check out the list of [Integrations and Usages of Mermaid](./docs/ecosystem/integrations-community.md).
 
-For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](./docs/intro/getting-started.md), [Usage](./docs/config/usage.md) and [Tutorials](./docs/config/Tutorials.md).
+For a more detailed introduction to Mermaid and some of its more basic uses, look to the [Beginner's Guide](./docs/intro/getting-started.md), [Usage](./docs/config/usage.md) and [Tutorials](./docs/ecosystem/tutorials.md).
 
 In our release process we rely heavily on visual regression tests using [applitools](https://applitools.com/). Applitools is a great service which has been easy to use and integrate with our tests.
 

README.zh-CN.md

@@ -57,9 +57,9 @@ Mermaid 是一个基于 Javascript 的图表绘制工具，通过解析类 Markd
 Mermaid 通过允许用户创建便于修改的图表来解决这一难题，它也可以作为生产脚本（或其他代码）的一部分。<br/>
 <br/>
 Mermaid 甚至能让非程序员也能通过 [Mermaid Live Editor](https://mermaid.live/) 轻松创建详细的图表。<br/>
-你可以访问 [教程](./docs/config/Tutorials.md) 来查看 Live Editor 的视频教程，也可以查看 [Mermaid 的集成和使用](./docs/ecosystem/integrations-community.md) 这个清单来检查你的文档工具是否已经集成了 Mermaid 支持。
+你可以访问 [教程](./docs/ecosystem/tutorials.md) 来查看 Live Editor 的视频教程，也可以查看 [Mermaid 的集成和使用](./docs/ecosystem/integrations-community.md) 这个清单来检查你的文档工具是否已经集成了 Mermaid 支持。
 
-如果想要查看关于 Mermaid 更详细的介绍及基础使用方式，可以查看 [入门指引](./docs/intro/getting-started.md), [用法](./docs/config/usage.md) 和 [教程](./docs/config/Tutorials.md).
+如果想要查看关于 Mermaid 更详细的介绍及基础使用方式，可以查看 [入门指引](./docs/intro/getting-started.md), [用法](./docs/config/usage.md) 和 [教程](./docs/ecosystem/tutorials.md).
 
 <!-- </Main description> -->
 

cSpell.json

@@ -26,6 +26,7 @@
     "città",
     "classdef",
     "codedoc",
+    "codemia",
     "colour",
     "commitlint",
     "cpettitt",
@@ -101,6 +102,7 @@
     "pathe",
     "pbrolin",
     "phpbb",
+    "pixelmatch",
     "plantuml",
     "playfair",
     "pnpm",
@@ -123,6 +125,7 @@
     "sidharth",
     "sidharthv",
     "sphinxcontrib",
+    "ssim",
     "startx",
     "starty",
     "statediagram",

cypress.config.cjs

@@ -6,10 +6,18 @@ const coverage = require('@cypress/code-coverage/task');
 
 module.exports = defineConfig({
   projectId: 'n2sma2',
+  viewportWidth: 1440,
+  viewportHeight: 1024,
   e2e: {
-    specPattern: 'cypress/integration/**/*.{js,jsx,ts,tsx}',
+    specPattern: 'cypress/integration/**/*.{js,ts}',
     setupNodeEvents(on, config) {
       coverage(on, config);
+      on('before:browser:launch', (browser = {}, launchOptions) => {
+        if (browser.name === 'chrome' && browser.isHeadless) {
+          launchOptions.args.push('--window-size=1440,1024', '--force-device-scale-factor=1');
+        }
+        return launchOptions;
+      });
       addMatchImageSnapshotPlugin(on, config);
       // copy any needed variables from process.env to config.env
       config.env.useAppli = process.env.USE_APPLI ? true : false;

cypress/helpers/util.ts

@@ -10,7 +10,7 @@ interface CypressConfig {
 type CypressMermaidConfig = MermaidConfig & CypressConfig;
 
 interface CodeObject {
-  code: string;
+  code: string | string[];
   mermaid: CypressMermaidConfig;
 }
 
@@ -25,7 +25,7 @@ const batchId: string =
     : Cypress.env('CYPRESS_COMMIT') || Date.now().toString());
 
 export const mermaidUrl = (
-  graphStr: string,
+  graphStr: string | string[],
   options: CypressMermaidConfig,
   api: boolean
 ): string => {
@@ -82,7 +82,7 @@ export const urlSnapshotTest = (
 };
 
 export const renderGraph = (
-  graphStr: string,
+  graphStr: string | string[],
   options: CypressMermaidConfig = {},
   api = false
 ): void => {

cypress/integration/other/configuration.spec.js

@@ -117,7 +117,6 @@ describe('Configuration', () => {
     });
     it('should not taint the initial configuration when using multiple directives', () => {
       const url = 'http://localhost:9000/regression/issue-1874.html';
-      cy.viewport(1440, 1024);
       cy.visit(url);
 
       cy.get('svg');