Playwright setup

.distignore

@@ -6,6 +6,7 @@
 .phpstan.neon.dist
 .scrutinizer.yml
 .wp-env.json
+/.claude
 /.git
 /.github
 /.idea

.github/dependabot.yml

@@ -13,6 +13,11 @@ updates:
       interval: weekly
     open-pull-requests-limit: 10
     target-branch: 'master'
+    ignore:
+      # @wordpress/e2e-test-utils-playwright peer-requires @types/node ^20.x;
+      # block major bumps that would re-create the ERESOLVE conflict.
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: composer
     directory: '/'

.github/workflows/e2e.yml

@@ -0,0 +1,51 @@
+name: E2E Tests
+permissions:
+  contents: read
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  playwright:
+    name: Playwright (local project)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@v7
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          cache: 'npm'
+      - name: Node dependencies
+        run: npm ci
+      # The plugin requires vendor/autoload.php for PHP-DI, and the Gutenberg
+      # block is not committed — both have to exist before wp-env loads the
+      # plugin from the mapped checkout.
+      - name: Composer dependencies
+        run: composer install --no-dev --no-interaction --optimize-autoloader
+      - name: Build assets
+        run: npm run build
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+      - name: Start WordPress multisite
+        run: npx wp-env start
+      # Seeds the de/it subsites and the linked demo posts via global-setup,
+      # then runs the admin and frontend specs. Visual specs are excluded —
+      # their baselines are only stable inside the Playwright Linux image.
+      - name: Run Playwright
+        run: npm run playwright:local
+      - name: Upload report
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-report
+          path: |
+            tests/playwright/artifacts/html-report
+            tests/playwright/artifacts/test-results
+          retention-days: 7

.gitignore

@@ -5,9 +5,12 @@
 .phpunit.cache
 .phpunit.result.cache
 .vscode/
+assets/css/msls.css
+assets/js/msls-quick-create.js
+assets/js/msls-translation-picker.js
 assets/js/msls-widget-block/
 assets/js/msls.js
-composer.lock
+build/translations.json
 composer.phar
 multisite-language-switcher.zip
 multisite-language-switcher/
@@ -16,7 +19,5 @@ out/
 phpunit.xml.bak
 tests/coverage.xml
 tests/coverage/
-tests/playwright-report/
-tests/playwright-results/
-tests/playwright/.env.local
+tests/playwright/artifacts/
 vendor/

.wp-env.json

@@ -1,9 +1,7 @@
 {
   "phpVersion": "8.3",
   "multisite": true,
-  "plugins": [
-    "."
-  ],
+  "plugins": [],
   "env": {
     "tests": {
       "config": {
@@ -12,7 +10,6 @@
     },
     "development": {
       "plugins": [
-        ".",
         "https://downloads.wordpress.org/plugin/query-monitor.zip"
       ]
     }

CLAUDE.md

@@ -32,15 +32,30 @@ npm run build-msls-block            # Build only the Gutenberg block
 
 ### E2E Tests
 ```bash
-npx playwright test                 # Run Playwright tests (against msls.co)
+npx wp-env start                    # Required first: the local suite runs against wp-env
+npm run playwright:local            # Admin + frontend specs (skips visual)
+npm run playwright:visual           # Visual specs inside the Playwright Linux image
+npm run playwright:docker           # Whole local suite inside that image
+npm run playwright:update-snapshots # Regenerate visual baselines
+npm run playwright:live             # Only specs/live, against msls.co
 npx playwright test --ui            # Run with UI
 ```
+Visual baselines are committed and only pixel-stable when generated inside the container —
+always use the `:visual` / `:update-snapshots` scripts, never a bare `npx playwright test`
+for them.
 
 ### Local Development Environment
 ```bash
 npx wp-env start                    # Start WordPress multisite via wp-env (PHP 8.3)
 npx wp-env stop
+npx wp-env reset tests              # Wipe the tests database (fresh-install check)
+npx wp-env run cli wp plugin activate multisite-language-switcher --network
 ```
+The plugin reaches the container through `mappings` in `.wp-env.json`, not through
+`plugins` — mounting it both ways created a duplicate `Multisite-Language-Switcher`
+plugin directory and made `wp-env start` fail. Consequence: wp-env does not auto-activate
+it, so activate it once per fresh **development** environment with the command above. The
+**tests** environment is network-activated by the Playwright global setup.
 
 ## Architecture
 
@@ -80,7 +95,15 @@ npx wp-env stop
 
 ## CI
 
-GitHub Actions runs PHPStan, PHPCS, PHPUnit, and Playwright on every pull request.
+GitHub Actions workflows:
+
+- `test.yml` — PHPUnit on every push (plus Codecov upload on `master`)
+- `e2e.yml` — the Playwright `local` project (admin + frontend specs) on pull requests and
+  pushes to `master`; visual specs and the `live` project are not run in CI
+- `plugin-check.yml` — WordPress.org Plugin Check on pull requests and `master`
+- `deploy.yml` — WordPress.org deploy on tags
+
+PHPStan and PHPCS are not wired into CI yet — run them locally via `composer qa`.
 
 ## Conventions
 

assets/css-flags/flags.php

@@ -33,30 +33,30 @@
 	'cy'             => 'flag-icon-gb-wls',
 	'da_DK'          => 'flag-icon-dk',
 	'de_AT'          => 'flag-icon-at',
-	'de_DE'          => 'flag-icon-de',
-	'de_DE_formal'   => 'flag-icon-de',
 	'de_CH'          => 'flag-icon-ch',
 	'de_CH_informal' => 'flag-icon-ch',
+	'de_DE'          => 'flag-icon-de',
+	'de_DE_formal'   => 'flag-icon-de',
 	'dzo'            => 'flag-icon-bt',
 	'el'             => 'flag-icon-gr',
-	'en_ZA'          => 'flag-icon-za',
+	'en_AU'          => 'flag-icon-au',
 	'en_GB'          => 'flag-icon-gb',
+	'en_ZA'          => 'flag-icon-za',
 	'en_NZ'          => 'flag-icon-nz',
-	'en_AU'          => 'flag-icon-au',
 	'en_CA'          => 'flag-icon-ca',
 	'eo'             => 'flag-icon-eu',
-	'es_CL'          => 'flag-icon-cl',
-	'es_CO'          => 'flag-icon-co',
-	'es_MX'          => 'flag-icon-mx',
-	'es_ES'          => 'flag-icon-es',
-	'es_CR'          => 'flag-icon-cr',
 	'es_AR'          => 'flag-icon-ar',
+	'es_CR'          => 'flag-icon-cr',
+	'es_ES'          => 'flag-icon-es',
+	'es_MX'          => 'flag-icon-mx',
+	'es_CO'          => 'flag-icon-co',
 	'es_PE'          => 'flag-icon-pe',
 	'es_VE'          => 'flag-icon-ve',
 	'es_EC'          => 'flag-icon-ec',
 	'es_DO'          => 'flag-icon-do',
 	'es_UY'          => 'flag-icon-uy',
 	'es_PR'          => 'flag-icon-pr',
+	'es_CL'          => 'flag-icon-cl',
 	'es_GT'          => 'flag-icon-gt',
 	'et'             => 'flag-icon-ee',
 	'eu'             => 'flag-icon-es',
@@ -99,17 +99,17 @@
 	'nb_NO'          => 'flag-icon-no',
 	'ne_NP'          => 'flag-icon-np',
 	'nl_NL'          => 'flag-icon-nl',
-	'nl_BE'          => 'flag-icon-be',
 	'nl_NL_formal'   => 'flag-icon-nl',
+	'nl_BE'          => 'flag-icon-be',
 	'nn_NO'          => 'flag-icon-no',
 	'oci'            => 'flag-icon-es-ca',
 	'pa_IN'          => 'flag-icon-in',
 	'pl_PL'          => 'flag-icon-pl',
 	'ps'             => 'flag-icon-af',
-	'pt_PT_ao90'     => 'flag-icon-90',
-	'pt_PT'          => 'flag-icon-pt',
 	'pt_BR'          => 'flag-icon-br',
 	'pt_AO'          => 'flag-icon-ao',
+	'pt_PT'          => 'flag-icon-pt',
+	'pt_PT_ao90'     => 'flag-icon-90',
 	'ro_RO'          => 'flag-icon-ro',
 	'ru_RU'          => 'flag-icon-ru',
 	'sah'            => 'flag-icon-ru',
@@ -134,9 +134,9 @@
 	'ur'             => 'flag-icon-pk',
 	'uz_UZ'          => 'flag-icon-uz',
 	'vi'             => 'flag-icon-vn',
+	'zh_CN'          => 'flag-icon-cn',
 	'zh_TW'          => 'flag-icon-tw',
 	'zh_HK'          => 'flag-icon-hk',
-	'zh_CN'          => 'flag-icon-cn',
 );
 
 /**

assets/flags/flags.php

@@ -33,30 +33,30 @@
 	'cy'             => 'wales.png',
 	'da_DK'          => 'dk.png',
 	'de_AT'          => 'at.png',
-	'de_DE'          => 'de.png',
-	'de_DE_formal'   => 'de.png',
 	'de_CH'          => 'ch.png',
 	'de_CH_informal' => 'ch.png',
+	'de_DE'          => 'de.png',
+	'de_DE_formal'   => 'de.png',
 	'dzo'            => 'bt.png',
 	'el'             => 'gr.png',
-	'en_ZA'          => 'za.png',
+	'en_AU'          => 'au.png',
 	'en_GB'          => 'gb.png',
+	'en_ZA'          => 'za.png',
 	'en_NZ'          => 'nz.png',
-	'en_AU'          => 'au.png',
 	'en_CA'          => 'ca.png',
 	'eo'             => 'europeanunion.png',
-	'es_CL'          => 'cl.png',
-	'es_CO'          => 'co.png',
-	'es_MX'          => 'mx.png',
-	'es_ES'          => 'es.png',
-	'es_CR'          => 'cr.png',
 	'es_AR'          => 'ar.png',
+	'es_CR'          => 'cr.png',
+	'es_ES'          => 'es.png',
+	'es_MX'          => 'mx.png',
+	'es_CO'          => 'co.png',
 	'es_PE'          => 'pe.png',
 	'es_VE'          => 've.png',
 	'es_EC'          => 'ec.png',
 	'es_DO'          => 'do.png',
 	'es_UY'          => 'uy.png',
 	'es_PR'          => 'pr.png',
+	'es_CL'          => 'cl.png',
 	'es_GT'          => 'gt.png',
 	'et'             => 'ee.png',
 	'eu'             => 'es.png',
@@ -99,17 +99,17 @@
 	'nb_NO'          => 'no.png',
 	'ne_NP'          => 'np.png',
 	'nl_NL'          => 'nl.png',
-	'nl_BE'          => 'be.png',
 	'nl_NL_formal'   => 'nl.png',
+	'nl_BE'          => 'be.png',
 	'nn_NO'          => 'no.png',
 	'oci'            => 'catalonia.png',
 	'pa_IN'          => 'in.png',
 	'pl_PL'          => 'pl.png',
 	'ps'             => 'af.png',
-	'pt_PT_ao90'     => '90.png',
-	'pt_PT'          => 'pt.png',
 	'pt_BR'          => 'br.png',
 	'pt_AO'          => 'ao.png',
+	'pt_PT'          => 'pt.png',
+	'pt_PT_ao90'     => '90.png',
 	'ro_RO'          => 'ro.png',
 	'ru_RU'          => 'ru.png',
 	'sah'            => 'ru.png',
@@ -134,9 +134,9 @@
 	'ur'             => 'pk.png',
 	'uz_UZ'          => 'uz.png',
 	'vi'             => 'vn.png',
+	'zh_CN'          => 'cn.png',
 	'zh_TW'          => 'tw.png',
 	'zh_HK'          => 'hk.png',
-	'zh_CN'          => 'cn.png',
 );
 
 /**