Add browser tests for JavaScript loaders

Author: Tsvetan Stoychev

.github/dependabot.yml

@@ -1,6 +1,15 @@
 version: 2
 
 updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "04:30"
+      timezone: Europe/Berlin
+    open-pull-requests-limit: 5
+
   - package-ecosystem: composer
     directory: /plugins/basicrum
     schedule:

.github/workflows/ci.yml

@@ -64,6 +64,31 @@ jobs:
       - name: Check for stale translation artifacts
         run: git diff --exit-code -- plugins/basicrum/languages
 
+  javascript:
+    name: JavaScript loader behavior
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install JavaScript dependencies
+        run: npm ci
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Test JavaScript loaders
+        run: npm run test:js
+
   unit:
     name: Unit (PHP ${{ matrix.php }})
     runs-on: ubuntu-latest
@@ -164,6 +189,7 @@ jobs:
     needs:
       - quality
       - translations
+      - javascript
       - unit
       - integration
 

.gitignore

@@ -12,6 +12,9 @@
 
 # Node
 /node_modules/
+/playwright-report/
+/test-results/
+/blob-report/
 
 # PHPUnit
 .phpunit.result.cache

.nvmrc

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -40,6 +40,7 @@ make analyse
 make composer-validate
 make composer-audit
 make unit
+make js-test
 make integration-setup
 make integration
 make translations

Makefile

@@ -3,6 +3,7 @@ PHP_SERVICE = php
 WP_SERVICE = wordpress
 DB_SERVICE = db
 WPCLI_SERVICE = wpcli
+JS_SERVICE = javascript
 WPCLI_PLUGIN_WORKDIR = /var/www/html/wp-content/plugins/basicrum
 PLUGIN_DIR = plugins/basicrum
 PLUGIN_WORKDIR = /workspace
@@ -12,7 +13,7 @@ TEST_DB_PASS = root
 TEST_DB_HOST = db
 WP_TEST_VERSION ?= latest
 
-.PHONY: help build up down restart logs shell composer-install wp-install lint lint-fix lint-php analyse composer-validate composer-audit translations integration-setup integration test package package-verify package-smoke clean
+.PHONY: help build up down restart logs shell composer-install wp-install lint lint-fix lint-php analyse composer-validate composer-audit translations js-install js-test integration-setup integration test package package-verify package-smoke clean
 
 help:
 	@echo "Targets:"
@@ -31,6 +32,8 @@ help:
 	@echo "  composer-validate  Validate Composer metadata and lock file"
 	@echo "  composer-audit     Audit locked Composer dependencies"
 	@echo "  translations       Update POT, PO, and MO translation catalogs"
+	@echo "  js-install         Install locked JavaScript test dependencies"
+	@echo "  js-test            Run loader behavior tests in Chromium"
 	@echo "  unit               Run unit tests"
 	@echo "  integration-setup  Install WordPress test suite inside containers"
 	@echo "  integration        Run integration tests"
@@ -85,6 +88,12 @@ composer-audit:
 translations:
 	$(COMPOSE) run --rm --no-deps --user "$$(id -u):$$(id -g)" -e HOME=/tmp -w $(WPCLI_PLUGIN_WORKDIR) $(WPCLI_SERVICE) sh /tools/update-translations.sh .
 
+js-install:
+	$(COMPOSE) run --rm --no-deps --user "$$(id -u):$$(id -g)" -e HOME=/tmp $(JS_SERVICE) npm ci --no-audit --no-fund
+
+js-test: js-install
+	$(COMPOSE) run --rm --no-deps --user "$$(id -u):$$(id -g)" -e HOME=/tmp $(JS_SERVICE) npm run test:js
+
 unit:
 	$(COMPOSE) run --rm -w $(PLUGIN_WORKDIR) $(PHP_SERVICE) composer unit
 
@@ -95,7 +104,7 @@ integration-setup:
 integration:
 	$(COMPOSE) run --rm -w $(PLUGIN_WORKDIR) $(PHP_SERVICE) composer integration
 
-test: unit integration
+test: unit integration js-test
 
 package:
 	$(COMPOSE) run --rm --no-deps -w /repo $(PHP_SERVICE) sh /tools/build-release.sh /repo/$(PLUGIN_DIR) /repo/release

README.md

@@ -26,6 +26,7 @@ make analyse
 make composer-validate
 make composer-audit
 make translations
+make js-test
 make package
 make package-smoke
 ```
@@ -72,13 +73,25 @@ both files to the GitHub release.
 
 ## Automated Quality Controls
 
+`make js-test` installs the locked root-level Node dependencies and runs the
+standard and consent loader behavior suites in Chromium. The tests execute the
+actual minified and unminified files from `plugins/basicrum/assets/js/loaders/`,
+intercept the synthetic Boomerang request, and block every unexpected network
+request. They cover consent gating, repeated opt-in, opt-out cleanup, and cookie
+behavior on HTTP, HTTPS, localhost, and subdomains.
+
+The JavaScript package, Playwright configuration, and browser tests live at the
+repository root. The release builder copies only `plugins/basicrum/`, and the
+release verifier also rejects Node or Playwright development files if they ever
+appear in the plugin ZIP.
+
 `make analyse` runs PHPStan level 5 with WordPress-aware stubs. The enforced
 configuration is stored in `plugins/basicrum/phpstan.neon.dist`.
 
 `make composer-validate` checks Composer metadata and lock-file consistency in
 strict mode. `make composer-audit` checks the complete lock file against current
 security advisories. CI runs all three checks on every push and pull request.
 
-Dependabot checks Composer dependencies and GitHub Actions weekly. CI workflows
-use a read-only `GITHUB_TOKEN`; release and pre-release workflows receive only
-the `contents: write` permission required to attach release assets.
+Dependabot checks npm, Composer dependencies, and GitHub Actions weekly. CI
+workflows use a read-only `GITHUB_TOKEN`; release and pre-release workflows
+receive only the `contents: write` permission required to attach release assets.

checklist.md

@@ -36,22 +36,22 @@ Acceptance criteria:
 
 ## 3. Add JavaScript consent and loader tests
 
-- [ ] Add a JavaScript test runner and a documented test command.
-- [ ] Test that Boomerang does not load before consent is granted.
-- [ ] Test that opt-in loads Boomerang exactly once.
-- [ ] Test that repeated opt-in calls do not load duplicate scripts.
-- [ ] Test that opt-out disables Boomerang when it is already loaded.
-- [ ] Test removal of Boomerang cookies during opt-out.
-- [ ] Test consent cookie behavior on HTTP and HTTPS.
-- [ ] Test consent cookie behavior for normal hostnames, localhost, and relevant
+- [x] Add a JavaScript test runner and a documented test command.
+- [x] Test that Boomerang does not load before consent is granted.
+- [x] Test that opt-in loads Boomerang exactly once.
+- [x] Test that repeated opt-in calls do not load duplicate scripts.
+- [x] Test that opt-out disables Boomerang when it is already loaded.
+- [x] Test removal of Boomerang cookies during opt-out.
+- [x] Test consent cookie behavior on HTTP and HTTPS.
+- [x] Test consent cookie behavior for normal hostnames, localhost, and relevant
   subdomain cases.
-- [ ] Run the same behavioral assertions against minified and unminified loaders.
-- [ ] Add JavaScript tests to CI.
+- [x] Run the same behavioral assertions against minified and unminified loaders.
+- [x] Add JavaScript tests to CI.
 
 Acceptance criteria:
 
-- [ ] Privacy-critical loader behavior is covered independently of PHP tests.
-- [ ] Minified and unminified loaders pass the same behavior suite.
+- [x] Privacy-critical loader behavior is covered independently of PHP tests.
+- [x] Minified and unminified loaders pass the same behavior suite.
 
 ## 4. Make installation and release artifacts resilient
 
@@ -152,7 +152,7 @@ Acceptance criteria:
 - [ ] PHPCS passes.
 - [ ] PHP unit tests pass across the supported PHP matrix.
 - [ ] WordPress integration tests pass across the supported WordPress matrix.
-- [ ] JavaScript tests pass.
+- [x] JavaScript tests pass.
 - [x] Static analysis passes.
 - [x] Composer validation and audit pass.
 - [ ] Generated asset checks pass.

docker-compose.yml

@@ -77,6 +77,15 @@ services:
       - wp_core:/tmp/wordpress
     tty: true
 
+  javascript:
+    image: mcr.microsoft.com/playwright:v1.61.1-noble
+    working_dir: /workspace
+    environment:
+      HOME: /tmp
+    volumes:
+      - ./:/workspace
+    ipc: host
+
 volumes:
   db_data:
   wordpress_data: