diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db85e4a8c4e..2ea8a360da6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,7 +83,8 @@ 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 @@ -91,10 +92,55 @@ Thanks to [PNPM Workspaces](https://pnpm.io/workspaces), you can also run these - `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 diff --git a/bin/test_package.sh b/bin/test_package.sh index e013d8b0b80..d2b0f71096a 100755 --- a/bin/test_package.sh +++ b/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 diff --git a/playwright.config.base.ts b/playwright.config.base.ts index 2c983f992d4..b13347bef3c 100644 --- a/playwright.config.base.ts +++ b/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; * ``` diff --git a/src/Autocomplete/assets/package.json b/src/Autocomplete/assets/package.json index 40e60e2ce22..38995f7108b 100644 --- a/src/Autocomplete/assets/package.json +++ b/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" }, diff --git a/src/Chartjs/assets/package.json b/src/Chartjs/assets/package.json index 903519080e0..16c2540e259 100644 --- a/src/Chartjs/assets/package.json +++ b/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" }, diff --git a/src/Cropperjs/assets/package.json b/src/Cropperjs/assets/package.json index 70be056b132..b3f8088b9c1 100644 --- a/src/Cropperjs/assets/package.json +++ b/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" }, diff --git a/src/Dropzone/assets/package.json b/src/Dropzone/assets/package.json index e7cd7ea958f..5d9ba1813e0 100644 --- a/src/Dropzone/assets/package.json +++ b/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" }, diff --git a/src/LiveComponent/assets/package.json b/src/LiveComponent/assets/package.json index c293428da8c..6f6b2712e76 100644 --- a/src/LiveComponent/assets/package.json +++ b/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" }, diff --git a/src/Map/src/Bridge/Google/assets/package.json b/src/Map/src/Bridge/Google/assets/package.json index 1055efa25c0..3c5a6c4b4bb 100644 --- a/src/Map/src/Bridge/Google/assets/package.json +++ b/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" }, diff --git a/src/Map/src/Bridge/Leaflet/assets/package.json b/src/Map/src/Bridge/Leaflet/assets/package.json index 9150ad614ca..8fb2a48449e 100644 --- a/src/Map/src/Bridge/Leaflet/assets/package.json +++ b/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" }, diff --git a/src/Notify/assets/package.json b/src/Notify/assets/package.json index 26194742a9d..92658b7950b 100644 --- a/src/Notify/assets/package.json +++ b/src/Notify/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" }, diff --git a/src/React/assets/package.json b/src/React/assets/package.json index 8213e27afbc..1962807ea0d 100644 --- a/src/React/assets/package.json +++ b/src/React/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" }, diff --git a/src/Svelte/assets/package.json b/src/Svelte/assets/package.json index 80b3ffbe11b..1a25f1ff3bd 100644 --- a/src/Svelte/assets/package.json +++ b/src/Svelte/assets/package.json @@ -19,6 +19,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" }, diff --git a/src/Translator/assets/package.json b/src/Translator/assets/package.json index e162cc5aef7..3f9fe4c27a4 100644 --- a/src/Translator/assets/package.json +++ b/src/Translator/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" }, diff --git a/src/Turbo/assets/package.json b/src/Turbo/assets/package.json index 6139f2d20cc..15cbbddab6f 100644 --- a/src/Turbo/assets/package.json +++ b/src/Turbo/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" }, diff --git a/src/Vue/assets/package.json b/src/Vue/assets/package.json index 79b5155525f..9990c9d125e 100644 --- a/src/Vue/assets/package.json +++ b/src/Vue/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" },