[#532] Added support for Functional JS tests.

Author: AlexSkrypnyk

.ahoy.yml

@@ -274,6 +274,11 @@ commands:
   test-functional:
     usage: Run PHPUnit functional tests.
     cmd: ahoy cli vendor/bin/phpunit --testsuite=functional "$@"
+
+  test-functional-javascript:
+    aliases: [test-js]
+    usage: Run PHPUnit functional JavaScript tests.
+    cmd: ahoy cli vendor/bin/phpunit --testsuite=functional-javascript "$@"
   #;> TOOL_PHPUNIT
 
   #;< TOOL_BEHAT

.docker/cli.dockerfile

@@ -39,10 +39,7 @@ ARG VORTEX_FRONTEND_BUILD_SKIP="0"
 ENV VORTEX_FRONTEND_BUILD_SKIP=${VORTEX_FRONTEND_BUILD_SKIP}
 
 ENV COMPOSER_ALLOW_SUPERUSER=1 \
-    COMPOSER_CACHE_DIR=/tmp/.composer/cache \
-    SIMPLETEST_DB=mysql://drupal:drupal@database/drupal \
-    SIMPLETEST_BASE_URL=http://nginx:8080 \
-    SYMFONY_DEPRECATIONS_HELPER=disabled
+    COMPOSER_CACHE_DIR=/tmp/.composer/cache
 
 # Allow custom PHP runtime configuration for Drush CLI commands.
 # The leading colon appends to the default scan directories.

.vortex/.ahoy.yml

@@ -117,12 +117,14 @@ commands:
 
   # If there are changes to the snapshots - this command will re-run twice reporting error the first time.
   update-snapshots:
+    aliases: [us]
     cmd: |
       export XDEBUG_MODE=off
       composer --working-dir=tests update-snapshots
       composer --working-dir=installer update-snapshots
 
   update-snapshots-install:
+    aliases: [usi]
     cmd: |
       ahoy install
       ahoy update-snapshots

.vortex/docs/content/development/phpunit.mdx

@@ -18,6 +18,7 @@ Test types supported:
 1. **Unit tests** - Test isolated PHP classes without Drupal bootstrap
 2. **Kernel tests** - Test with partial Drupal bootstrap (database, services)
 3. **Functional tests** - Test with full Drupal bootstrap including browser simulation
+4. **Functional JavaScript tests** - Test with full Drupal bootstrap and a real browser (Chrome via Selenium) for JavaScript interactions
 
 ## Running tests
 
@@ -35,6 +36,8 @@ import TabItem from '@theme/TabItem';
     ahoy test-kernel
     # Run only Functional tests
     ahoy test-functional
+    # Run only Functional JavaScript tests
+    ahoy test-functional-javascript
     # Run specific test file
     ahoy test tests/phpunit/ExampleTest.php
     # Run tests with filter
@@ -51,6 +54,8 @@ import TabItem from '@theme/TabItem';
     docker compose exec cli vendor/bin/phpunit --testsuite=kernel
     # Run only Functional tests
     docker compose exec cli vendor/bin/phpunit --testsuite=functional
+    # Run only Functional JavaScript tests
+    docker compose exec cli vendor/bin/phpunit --testsuite=functional-javascript
     # Run specific test file
     docker compose exec cli vendor/bin/phpunit tests/phpunit/ExampleTest.php
     # Run tests with filter
@@ -66,6 +71,7 @@ PHPUnit tests are organized into test suites defined in `phpunit.xml`:
 - **unit** - Fast tests that don't require Drupal bootstrap
 - **kernel** - Tests that need database and core services
 - **functional** - Full browser simulation tests
+- **functional-javascript** - Tests requiring a real browser with JavaScript support (Chrome via Selenium)
 
 ## Configuration
 
@@ -97,7 +103,7 @@ continuous integration to track test performance and stability.
 
 ## Boilerplate
 
-**Vortex** provides Unit, Kernel and Functional tests boilerplate for custom [modules](https://github.com/drevops/vortex/blob/main/web/modules/custom/ys_base/tests/src),
+**Vortex** provides Unit, Kernel, Functional and Functional JavaScript tests boilerplate for custom [modules](https://github.com/drevops/vortex/blob/main/web/modules/custom/ys_base/tests/src),
 [themes](https://github.com/drevops/vortex/blob/main/web/themes/custom/your_site_theme/tests/src) and
 [scripts](https://github.com/drevops/vortex/blob/main/tests/phpunit).
 

.vortex/docs/content/tools/behat.mdx

@@ -77,6 +77,19 @@ default:
         - '%paths.base%/web/modules/custom/mymodule/tests/behat/features'
 ```
 
+### Chrome session flags
+
+The [`behat.yml`](https://github.com/drevops/vortex/blob/main/behat.yml)
+configuration passes the following flags to Chrome via `goog:chromeOptions`
+to ensure stable and deterministic test execution in the container environment:
+
+| Flag                             | Purpose                                                          |
+|----------------------------------|------------------------------------------------------------------|
+| `--disable-extensions`           | Prevents interference from browser extensions                    |
+| `--disable-translate`            | Prevents the translation bar from appearing on non-English pages |
+| `--force-prefers-reduced-motion` | Disables CSS animations and transitions for test stability       |
+| `--test-type`                    | Suppresses error dialogs and crash recovery prompts              |
+
 ### Contexts and extensions
 
 The configuration uses the following contexts and extensions:

.vortex/docs/content/tools/phpunit.mdx

@@ -21,14 +21,16 @@ import TabItem from '@theme/TabItem';
     ahoy test-unit                              # Run Unit tests.
     ahoy test-kernel                            # Run Kernel tests.
     ahoy test-functional                        # Run Functional tests.
+    ahoy test-functional-javascript             # Run Functional JavaScript tests.
     ```
   </TabItem>
   <TabItem value="docker-compose" label="Docker Compose">
     ```shell
-    docker compose exec cli vendor/bin/phpunit                          # Run all tests.
-    docker compose exec cli vendor/bin/phpunit --testsuite=unit         # Run Unit tests.
-    docker compose exec cli vendor/bin/phpunit --testsuite=kernel       # Run Kernel tests.
-    docker compose exec cli vendor/bin/phpunit --testsuite=functional   # Run Functional tests.
+    docker compose exec cli vendor/bin/phpunit                                        # Run all tests.
+    docker compose exec cli vendor/bin/phpunit --testsuite=unit                       # Run Unit tests.
+    docker compose exec cli vendor/bin/phpunit --testsuite=kernel                     # Run Kernel tests.
+    docker compose exec cli vendor/bin/phpunit --testsuite=functional                 # Run Functional tests.
+    docker compose exec cli vendor/bin/phpunit --testsuite=functional-javascript      # Run Functional JavaScript tests.
     ```
   </TabItem>
 </Tabs>
@@ -102,6 +104,34 @@ Run checks against platform version specified in `composer.json` key `config.pla
 <config name="testVersion" value="8.1"/>
 ```
 
+### Chrome session flags
+
+Functional JavaScript tests use a Chrome browser running in the
+[`selenium/standalone-chromium`](https://hub.docker.com/r/selenium/standalone-chromium)
+container. The following flags are passed via `MINK_DRIVER_ARGS_WEBDRIVER`
+in `phpunit.xml` to ensure stable and deterministic test execution:
+
+| Flag                             | Purpose                                                          |
+|----------------------------------|------------------------------------------------------------------|
+| `--disable-extensions`           | Prevents interference from browser extensions                    |
+| `--disable-translate`            | Prevents the translation bar from appearing on non-English pages |
+| `--force-prefers-reduced-motion` | Disables CSS animations and transitions for test stability       |
+| `--test-type`                    | Suppresses error dialogs and crash recovery prompts              |
+| `--window-size=1920,1080`        | Sets a deterministic viewport size for consistent screenshots    |
+
+The `w3c: true` option is required for compatibility with Selenium 4.
+
+### Bootstrap
+
+The custom [`tests/phpunit/bootstrap.php`](https://github.com/drevops/vortex/blob/main/tests/phpunit/bootstrap.php)
+file runs before tests to:
+
+1. Set `BROWSERTEST_OUTPUT_BASE_URL` from the `VORTEX_LOCALDEV_URL` environment
+   variable so that HTML output links are accessible from the host machine.
+2. Create the `web/sites/simpletest/browser_output` directory required by the
+   `HtmlOutputLogger` extension before it initializes
+   (see [Drupal core issue #2992069](https://www.drupal.org/project/drupal/issues/2992069)).
+
 ## Coverage
 
 PHPUnit is configured to generate code coverage reports. The reports are stored

.vortex/docs/cspell.json

@@ -8,6 +8,7 @@
     ],
     "words": [
         "Asciinema",
+        "BROWSERTEST",
         "Buildx",
         "Diffy",
         "GHSA",
@@ -19,8 +20,8 @@
         "acquia",
         "amazee",
         "amazeeio",
-        "automations",
         "apikey",
+        "automations",
         "behat",
         "bootstrappable",
         "calver",
@@ -73,6 +74,7 @@
         "runsheets",
         "seckit",
         "shellvar",
+        "simpletest",
         "standardise",
         "updatedb",
         "uselagoon",

.vortex/installer/src/Prompts/Handlers/Theme.php

@@ -207,6 +207,8 @@ protected function removeThemeConfigLines(string $tmpDir): void {
     File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom/**/tests/src/Kernel</directory>');
     File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom/*/tests/src/Functional</directory>');
     File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom/**/tests/src/Functional</directory>');
+    File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom/*/tests/src/FunctionalJavascript</directory>');
+    File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom/**/tests/src/FunctionalJavascript</directory>');
     File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom</directory>');
     File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory suffix="Test.php">web/themes/custom</directory>');
     File::removeLineInFile($tmpDir . '/phpunit.xml', '<directory>web/themes/custom/*/node_modules</directory>');

.vortex/installer/tests/Fixtures/handler_process/_baseline/.ahoy.yml

@@ -235,6 +235,11 @@ commands:
     usage: Run PHPUnit functional tests.
     cmd: ahoy cli vendor/bin/phpunit --testsuite=functional "$@"
 
+  test-functional-javascript:
+    aliases: [test-js]
+    usage: Run PHPUnit functional JavaScript tests.
+    cmd: ahoy cli vendor/bin/phpunit --testsuite=functional-javascript "$@"
+
   test-bdd:
     usage: Run BDD tests.
     aliases: [test-behat]

.vortex/installer/tests/Fixtures/handler_process/_baseline/.docker/cli.dockerfile

@@ -39,10 +39,7 @@ ARG VORTEX_FRONTEND_BUILD_SKIP="0"
 ENV VORTEX_FRONTEND_BUILD_SKIP=${VORTEX_FRONTEND_BUILD_SKIP}
 
 ENV COMPOSER_ALLOW_SUPERUSER=1 \
-    COMPOSER_CACHE_DIR=/tmp/.composer/cache \
-    SIMPLETEST_DB=mysql://drupal:drupal@database/drupal \
-    SIMPLETEST_BASE_URL=http://nginx:8080 \
-    SYMFONY_DEPRECATIONS_HELPER=disabled
+    COMPOSER_CACHE_DIR=/tmp/.composer/cache
 
 # Allow custom PHP runtime configuration for Drush CLI commands.
 # The leading colon appends to the default scan directories.