3.3.8

.github/workflows/build-docs.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - name: Install dependencies

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php-version: [ '7.4', '8.3' ]
+        php-version: [ '7.4', '8.5' ]
 
     steps:
       - name: Checkout repository
@@ -25,7 +25,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - name: Cache Composer
@@ -55,7 +55,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: '8.5'
 
       - name: Cache Composer
         uses: actions/cache@v4
@@ -80,39 +80,159 @@ jobs:
       - name: Run PHPStan
         run: composer phpstan
 
-  e2e:
-    name: E2E (Playwright)
+  unit:
+    name: Unit (PHPUnit)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
+      - name: Cache Composer
+        uses: actions/cache@v4
+        with:
+          path: ~/.composer/cache
+          key: ${{ runner.os }}-composer-unit-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-composer-unit-
+
+      # This job only needs vendor/bin/phpunit and the wp-env CLI, so it used to
+      # install @wordpress/env on its own into a scratch prefix rather than run
+      # a full `npm ci`. That install resolved dependency ranges fresh against
+      # npm instead of obeying package-lock.json, which made the job depend on
+      # whatever upstream had published that day: a broken @wp-playground/cli
+      # release, pulled in transitively by @wordpress/env, failed every run
+      # while the lockfile-based jobs were unaffected.
+      #
+      # `npm ci` installs the locked tree, so the job can no longer break
+      # because of a third-party release. The postinstall hook runs
+      # `patch-package && composer install`, which is what provides
+      # vendor/bin/phpunit, so this single step covers both toolchains.
+      #
+      # Deliberately not `--ignore-scripts`, for the same reason as the e2e
+      # job below: besides skipping the Composer install, that flag made this
+      # step take 1m30s instead of ~36s from a cold cache.
       - name: Install dependencies
         run: npm ci
 
-      - name: Install Playwright browsers
-        run: npx playwright install --with-deps chromium
+      # The wp-env sources directory is deliberately not cached. A restored
+      # ~/.wp-env carries the previous run's install state, which skipped the
+      # plugin's activation hook and left the relationships table missing.
+      # .wp-env.ci.json omits the HTTPS URLs and the proxy lifecycle script
+      # that .wp-env.json uses for local development. Runners have no local CA
+      # and no proxy container, so they serve the site over plain HTTP.
+      - name: Start wp-env
+        run: npx wp-env start --config .wp-env.ci.json
 
-      - name: Build assets
-        run: npm run build
+      - name: Run unit tests
+        run: npx wp-env run tests-cli --config .wp-env.ci.json --env-cwd="wp-content/plugins/$(basename "$PWD")" vendor/bin/phpunit
 
-      - name: Start wp-env
-        run: npm run env:start
+      - name: Stop wp-env
+        if: always()
+        run: npx wp-env stop --config .wp-env.ci.json
+
+  e2e:
+    name: E2E (Playwright)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
+      # Not needed by Playwright, but every job that has this step completes
+      # `npm ci` in ~35s while this job, without it, took 2.5 to 4 minutes on
+      # the same runs (same npm, same cache hit). setup-php also installs
+      # Composer, which the postinstall hook calls.
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Cache Composer
+        uses: actions/cache@v4
+        with:
+          path: ~/.composer/cache
+          key: ${{ runner.os }}-composer-e2e-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-composer-e2e-
+
+      # Deliberately not `--ignore-scripts`: with the npm 10 that ships with
+      # the pinned Node, that flag made this step take 4 to 7 minutes instead
+      # of ~36s (a known npm 10 reify stall around lifecycle-script nodes).
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Get Playwright version
+        id: playwright-version
+        run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Cache Playwright browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ steps.playwright-version.outputs.version }}
+
+      # wp-env spends most of its time pulling Docker images and installing
+      # WordPress, none of which depends on the Node-side steps. Run it in the
+      # background while the browser install and asset build proceed, then
+      # wait for it. All of this has to live in one step because `wait` only
+      # sees children of the same shell. wp-env output goes to a file and is
+      # printed afterwards so the interleaved log stays readable.
+      - name: Start wp-env, install browsers, build assets
+        env:
+          PLAYWRIGHT_CACHE_HIT: ${{ steps.playwright-cache.outputs.cache-hit }}
+        run: |
+          npx wp-env start --config .wp-env.ci.json > wp-env-start.log 2>&1 &
+          wp_env_pid=$!
+
+          if [ "$PLAYWRIGHT_CACHE_HIT" = "true" ]; then
+            # Browser binaries came from cache; only the apt packages they
+            # need are missing on a fresh runner.
+            npx playwright install-deps chromium
+          else
+            npx playwright install --with-deps chromium
+          fi
+
+          npm run build
+
+          echo "::group::wp-env start"
+          if wait "$wp_env_pid"; then
+            cat wp-env-start.log
+            echo "::endgroup::"
+          else
+            cat wp-env-start.log
+            echo "::endgroup::"
+            exit 1
+          fi
+
+      # Runners have no local CA and no HTTPS proxy, so the suite talks to
+      # wp-env's published port directly over plain HTTP. WP_BASE_URL is the
+      # single switch for this; see tests/e2e/playwright.config.js.
       - name: Run E2E tests
         env:
           CLOUDINARY_E2E_URL: ${{ secrets.CLOUDINARY_E2E_URL }}
+          WP_BASE_URL: http://localhost:8889
         run: npm run test:e2e
 
       - name: Stop wp-env
         if: always()
-        run: npm run env:stop
+        run: npx wp-env stop --config .wp-env.ci.json
 
       - name: Upload Playwright artifacts
         if: failure()

.github/workflows/deploy-to-wp-org.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.3'
+          php-version: '8.5'
           tools: composer:v2
 
       - name: Get Composer cache directory

.gitignore

@@ -46,6 +46,9 @@ coverage/html/
 # wp-env personal overrides
 .wp-env.override.json
 
+# Locally generated TLS certificates and CA for the wp-env HTTPS proxy
+/.wp-env/certs/
+
 # IDE
 .vscode
 
@@ -62,5 +65,9 @@ package/dist
 # PHPStan result cache
 /.phpstan-cache/
 
+# PHPUnit
+/.phpunit.result.cache
+/phpunit.xml
+
 # Generated docs (published to gh-pages by workflow)
 /docs/

.version

@@ -1 +1 @@
-3.3.7
+3.3.8

.wp-env.ci.json

@@ -0,0 +1,26 @@
+{
+  "core": "WordPress/WordPress#7.1",
+  "phpVersion": "8.5",
+  "plugins": ["."],
+  "config": {
+    "WP_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "SCRIPT_DEBUG": true
+  },
+  "mappings": {
+    "wp-content/mu-plugins": "./.wp-env/mu-plugins"
+  },
+  "lifecycleScripts": {
+    "afterStart": "./.wp-env/scripts/fix-loopback.sh"
+  },
+  "env": {
+    "tests": {
+      "phpVersion": "8.2",
+      "config": {
+        "WP_DEBUG": true,
+        "WP_DEBUG_LOG": true,
+        "SCRIPT_DEBUG": true
+      }
+    }
+  }
+}

.wp-env.json

@@ -1,25 +1,35 @@
 {
-  "core": "WordPress/WordPress#7.0",
-  "phpVersion": "8.2",
+  "core": "WordPress/WordPress#7.1",
+  "phpVersion": "8.5",
   "plugins": ["."],
   "config": {
     "WP_DEBUG": true,
     "WP_DEBUG_LOG": true,
-    "SCRIPT_DEBUG": true
+    "SCRIPT_DEBUG": true,
+    "WP_HOME": "https://cloudinary.local.wpenv.net",
+    "WP_SITEURL": "https://cloudinary.local.wpenv.net",
+    "FORCE_SSL_ADMIN": true,
+    "WP_CONTENT_URL": "https://cloudinary.local.wpenv.net/wp-content",
+    "WP_PLUGIN_URL": "https://cloudinary.local.wpenv.net/wp-content/plugins"
   },
   "mappings": {
     "wp-content/mu-plugins": "./.wp-env/mu-plugins"
   },
   "lifecycleScripts": {
-    "afterStart": "./.wp-env/scripts/fix-loopback.sh"
+    "afterStart": "./.wp-env/scripts/after-start.sh"
   },
   "env": {
     "tests": {
       "phpVersion": "8.2",
       "config": {
         "WP_DEBUG": true,
         "WP_DEBUG_LOG": true,
-        "SCRIPT_DEBUG": true
+        "SCRIPT_DEBUG": true,
+        "WP_HOME": "https://tests.cloudinary.local.wpenv.net",
+        "WP_SITEURL": "https://tests.cloudinary.local.wpenv.net",
+        "FORCE_SSL_ADMIN": true,
+        "WP_CONTENT_URL": "https://tests.cloudinary.local.wpenv.net/wp-content",
+        "WP_PLUGIN_URL": "https://tests.cloudinary.local.wpenv.net/wp-content/plugins"
       }
     }
   }

.wp-env/docker/mkcert/Dockerfile

@@ -0,0 +1,16 @@
+FROM golang:1.24-alpine
+
+# Set the version tag to build.
+ENV MKCERT_VERSION="v1.4.4"
+
+RUN apk add --no-cache git
+
+RUN git clone https://github.com/FiloSottile/mkcert /go/mkcert \
+	&& cd /go/mkcert \
+	&& git checkout "tags/$MKCERT_VERSION" -b "build/$MKCERT_VERSION" \
+	&& go build -ldflags "-X main.Version=$MKCERT_VERSION" -o /bin/mkcert
+
+# mkcert reads and writes its CA here. The compose file mounts the project's
+# certificate directory over it, so both the CA and the issued certificates
+# stay inside the repository instead of the developer's global mkcert store.
+WORKDIR /root/.local/share/mkcert