minor #3086 Add doc for E2E steps + minor modifications (raphael-geffroy)

This PR was merged into the 2.x branch.

Discussion
----------

 Add doc for E2E steps + minor modifications

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Docs?         | yes
| Issues        | Fix #3039
| License       | MIT

Commits
-------

ceefa1d [Docs] Add doc for E2E steps + minor modifications

Author: Kocal

CONTRIBUTING.md

@@ -83,18 +83,64 @@ To help you with assets, you can run the following commands in a specific packag
   - `pnpm run watch`: watch for modifications and rebuild assets from the package,
   - `pnpm run test`: run the tests from the package,
   - `pnpm run test:unit`: run the Unit tests from the package,
-  - `pnpm run test:browser`: run the Browser tests from the package,
+  - `pnpm run test:browser`: run the Browser tests from the package, in a headless browser
+  - `pnpm run test:browser:ui`: run the Browser tests from the package in interactive mode, allowing you to see the tests running in a browser window and debug them if needed
   - `pnpm run check`: run the formatter, linter, and sort imports, and fails if any modifications
   - `pnpm run check --write`: run the formatter, linter, imports sorting, and write modifications
 
 Thanks to [PNPM Workspaces](https://pnpm.io/workspaces), you can also run these commands from the root directory of the project:
   - `pnpm run build`: build (compile) assets from **all** packages,
   - `pnpm run test`: run the tests from **all** packages,
   - `pnpm run test:unit`: run the Unit tests from **all** packages,
-  - `pnpm run test:browser`: run the Browser tests from **all** packages,
+  - `pnpm run test:browser`: run the Browser tests from **all** packages, in a headless browser
   - `pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fails if any modifications
   - `pnpm run check --write`: run the formatter, linter, imports sorting for **all** packages, and write modifications
 
+#### Working with Unit tests
+
+We use [Vitest](https://vitest.dev/) for unit testing of the assets,
+and tests files are located in the `assets/test/unit/` directory of each UX package,
+for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
+
+**Running tests:**
+- At the project's root, you can run the following commands:
+  - `pnpm run test:unit`: runs the unit tests for **all** UX packages
+- Inside the `assets/` directory of each UX package, you can run the following commands:
+  - `pnpm run test:unit`: runs the unit tests for the package
+
+> [!IMPORTANT]
+> The command `pnpm run test:unit` ensure that each possible combination of dependencies is tested
+> (e.g., `"chart.js": "^3.4.1 || ^4.0"` for UX Chartjs).
+> Thus it may take some time to run, and it may be not recommended to use watch mode.
+
+#### Working with End-to-End (E2E) tests
+
+> [!NOTE]
+> E2E tests simulate real user interactions in a browser, to ensure that the
+> UX packages work as expected in a real-world scenario.
+
+Symfony UX use [Playwright](https://playwright.dev/) for browser automation and testing,
+and a dedicated Symfony application located in the [`apps/e2e/`](./apps/e2e/) directory,
+which contains many examples of Symfony UX packages usage.
+
+Tests files are located in the `assets/test/browser/` directory of each UX package,
+for example: `src/Vue/assets/test/browser/vue.test.ts`.
+
+**Setup:**
+1. Ensure to have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section
+2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file,
+
+**Running tests:**
+- At the project's root, you can run the following commands:
+  - `pnpm run test:browser`: runs the browser tests for **all** UX packages, using a headless browser
+- Inside the `assets/` directory of each UX package, you can run the following commands:
+  - `pnpm run test:browser`: runs browser tests for the package, using a headless browser
+  - `pnpm run test:browser:ui`: runs the browser tests in interactive mode, allowing you to see the tests running in a browser window and debug them if needed
+
+> [!IMPORTANT]
+> Due to their nature, E2E tests may be slower to run than unit tests.
+> During the development, we recommend to run `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package.
+
 ### Working on documentation
 
 Symfony UX documentation is written in ReStructuredText (`.rst`) and is located in the `docs/` directory

bin/test_package.sh

@@ -40,9 +40,11 @@ fi
 runTestSuite() {
     if [ "$testType" == "unit" ]; then
       echo -e "🧪  Running unit tests for $workspace...\n"
+      # Using "cd" instead of "pnpm --filter" prevent rendering issues in GitHub Actions that does not support nested groups
       (cd "$location"; pnpm exec vitest --run "${args[@]}") || { all_tests_passed=false; }
     elif [ "$testType" == "browser" ]; then
       echo -e "🧪  Running browser tests for $workspace...\n"
+      # Using "cd" instead of "pnpm --filter" prevent rendering issues in GitHub Actions that does not support nested groups
       (cd "$location"; pnpm exec playwright test "${args[@]}") || { all_tests_passed=false; }
     fi
 }
@@ -67,6 +69,12 @@ processWorkspace() {
 
     echo -e "⏳  Processing workspace $workspace at location $location...\n"
 
+    # TODO: Refactor the `test_package.sh` script to its simple form:  only run unit tests for a given UX package,
+    # The rest will be moved to `pnpm` scripts or other CI checks
+    if [ "$testType" == "browser" ]; then
+      runTestSuite
+    fi
+
     echo "⚙️  Checking '$package_json_path' for peerDependencies and importmap dependencies to have the same version"
     deps=$(jq -r '.peerDependencies | keys[]' "$package_json_path")
     for library in $deps; do

playwright.config.base.ts

@@ -6,7 +6,7 @@
  * ```typescript
  * // src/Autocomplete/assets/playwright.config.ts
  *
- * import baseConfig from '../../../../../../playwright.config.base';
+ * import baseConfig from '../../../playwright.config.base';
  *
  * export default baseConfig;
  * ```

src/Autocomplete/assets/package.json

@@ -20,6 +20,7 @@
         "test": "pnpm run test:unit && pnpm run test:browser",
         "test:unit": "../../../bin/test_package.sh . --unit",
         "test:browser": "../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },

src/Chartjs/assets/package.json

@@ -20,6 +20,7 @@
         "test": "pnpm run test:unit && pnpm run test:browser",
         "test:unit": "../../../bin/test_package.sh . --unit",
         "test:browser": "../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },

src/Cropperjs/assets/package.json

@@ -23,6 +23,7 @@
         "test": "pnpm run test:unit && pnpm run test:browser",
         "test:unit": "../../../bin/test_package.sh . --unit",
         "test:browser": "../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },

src/Dropzone/assets/package.json

@@ -23,6 +23,7 @@
         "test": "pnpm run test:unit && pnpm run test:browser",
         "test:unit": "../../../bin/test_package.sh . --unit",
         "test:browser": "../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },

src/LiveComponent/assets/package.json

@@ -25,6 +25,7 @@
         "test": "pnpm run test:unit && pnpm run test:browser",
         "test:unit": "../../../bin/test_package.sh . --unit",
         "test:browser": "../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },

src/Map/src/Bridge/Google/assets/package.json

@@ -21,6 +21,7 @@
         "watch": "tsx ../../../../../../bin/build_package.ts . --watch",
         "test": "pnpm run test:browser",
         "test:browser": "../../../../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },

src/Map/src/Bridge/Leaflet/assets/package.json

@@ -21,6 +21,7 @@
         "watch": "tsx ../../../../../../bin/build_package.ts . --watch",
         "test": "pnpm run test:browser",
         "test:browser": "../../../../../../bin/test_package.sh . --browser",
+        "test:browser:ui": "../../../../../../bin/test_package.sh . --browser --ui",
         "check": "biome check",
         "ci": "biome ci"
     },