Merge pull request #1272 from cloudinary/develop

3.3.8 (develop to uat)

Author: gabrielcld2

.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,30 +80,140 @@ jobs:
       - name: Run PHPStan
         run: composer phpstan
 
+  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-file: '.nvmrc'
+
+      - 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 (from Composer) and the wp-env
+      # CLI. A full `npm ci` pulls ~2,200 packages and has taken anywhere from
+      # 36s to 7 minutes on hosted runners; @wordpress/env alone is ~400
+      # packages and installs in ~30s. It is installed into a scratch prefix
+      # outside the repo so npm does not reconcile against package-lock.json
+      # and pull the whole tree anyway. The version is read from the lockfile
+      # so it cannot drift from what developers run locally.
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --no-progress
+
+      - name: Install wp-env
+        run: |
+          version=$(node -p "require('./package-lock.json').packages['node_modules/@wordpress/env'].version")
+          echo "Installing @wordpress/env@$version"
+          npm install --prefix "$RUNNER_TEMP/wp-env" --no-audit --no-fund "@wordpress/env@$version"
+          echo "$RUNNER_TEMP/wp-env/node_modules/.bin" >> "$GITHUB_PATH"
+
+      # 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.
+      - name: Start wp-env
+        run: wp-env start
+
+      - name: Run unit tests
+        run: wp-env run tests-cli --env-cwd="wp-content/plugins/$(basename "$PWD")" vendor/bin/phpunit
+
+      - name: Stop wp-env
+        if: always()
+        run: wp-env stop
+
   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: '22'
+          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: Install Playwright browsers
-        run: npx playwright install --with-deps chromium
+      - name: Get Playwright version
+        id: playwright-version
+        run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
 
-      - name: Build assets
-        run: npm run build
-
-      - name: Start wp-env
-        run: npm run env:start
+      - 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: |
+          npm run env:start > 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
 
       - name: Run E2E tests
         env:

.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

@@ -62,5 +62,9 @@ package/dist
 # PHPStan result cache
 /.phpstan-cache/
 
+# PHPUnit
+/.phpunit.result.cache
+/phpunit.xml
+
 # Generated docs (published to gh-pages by workflow)
 /docs/

.wp-env.json

@@ -1,6 +1,6 @@
 {
-  "core": "WordPress/WordPress#7.0",
-  "phpVersion": "8.2",
+  "core": "WordPress/WordPress#7.1",
+  "phpVersion": "8.5",
   "plugins": ["."],
   "config": {
     "WP_DEBUG": true,

.wp-env/mu-plugins/analytics-capture.php

@@ -11,23 +11,101 @@
  * proceed, which meant every local/CI test run was quietly leaking synthetic
  * events (and deactivation "feedback") into the real production collector.
  *
+ * Two additions support running the e2e suite in parallel Playwright
+ * workers against this single WordPress install: the capture log is
+ * per-worker (see cld_analytics_capture_worker_marker()), and Admin API
+ * calls made with the fake e2e credentials are answered locally (see
+ * cld_e2e_fake_cloud_intercept()).
+ *
  * @package Cloudinary
  */
 
 defined( 'ABSPATH' ) || exit;
 
 /**
- * Returns the path to the capture log file.
+ * Returns the e2e worker marker for the current request, if any.
+ *
+ * Playwright runs spec files in parallel workers against this single
+ * WordPress install. Each worker tags its browser/REST traffic with a
+ * `cld_e2e_worker` cookie and its WP-CLI calls with a `CLD_E2E_WORKER`
+ * env var, so every worker gets its own capture log and one worker's
+ * events (or `--clear`) can't leak into another worker's assertions.
+ *
+ * Requests without a marker (manual QA, fire-and-forget loopback threads
+ * spawned by the sync queue) fall back to the shared, unsuffixed log.
+ *
+ * @return string Sanitized marker, or empty string when none is present.
+ */
+function cld_analytics_capture_worker_marker() {
+	$marker = '';
+
+	// Dev/CI-only mu-plugin with no page cache in front of it, so the VIP
+	// cache-constraints sniff on $_COOKIE does not apply.
+	if ( ! empty( $_COOKIE['cld_e2e_worker'] ) ) { // phpcs:ignore WordPressVIPMinimum.Variables.RestrictedVariables.cache_constraints___COOKIE
+		$marker = wp_unslash( $_COOKIE['cld_e2e_worker'] ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPressVIPMinimum.Variables.RestrictedVariables.cache_constraints___COOKIE
+	} elseif ( false !== getenv( 'CLD_E2E_WORKER' ) && '' !== getenv( 'CLD_E2E_WORKER' ) ) {
+		$marker = getenv( 'CLD_E2E_WORKER' );
+	}
+
+	return preg_replace( '/[^A-Za-z0-9_-]/', '', (string) $marker );
+}
+
+/**
+ * Returns the path to the capture log file for the current worker.
  *
  * @return string
  */
 function cld_analytics_capture_log_path() {
 	$upload = wp_upload_dir();
+	$marker = cld_analytics_capture_worker_marker();
+	$suffix = '' !== $marker ? '-' . $marker : '';
 
-	return $upload['basedir'] . '/analytics-capture.log';
+	return $upload['basedir'] . '/analytics-capture' . $suffix . '.log';
 }
 
 add_filter( 'pre_http_request', 'cld_analytics_capture_intercept', 10, 3 );
+add_filter( 'pre_http_request', 'cld_e2e_fake_cloud_intercept', 10, 3 );
+
+/**
+ * Cloud name used by `fakeCloudinaryConnected()` in tests/e2e/utils/connection.js.
+ */
+const CLD_E2E_FAKE_CLOUD = 'e2e-fake-cloud';
+
+/**
+ * Short-circuits Cloudinary Admin API calls made with the fake e2e
+ * credentials.
+ *
+ * Analytics specs fake a connection so `Connect::is_connected()` is true.
+ * The dashboard then still calls the real Admin API for usage stats and
+ * per-day history (`Connect::history()` issues one request per day, and the
+ * 401 responses it gets are never cached because `is_wp_error()` entries
+ * are refetched). Each real round-trip is ~1s, so one `page=cloudinary`
+ * load can exceed Playwright's navigation timeout, and parallel workers
+ * multiply the load. Answer those calls locally with the same 401 the real
+ * API would return so the plugin's error handling still runs.
+ *
+ * @param false|array|WP_Error $preempt     Whether to preempt the request.
+ * @param array                $parsed_args Parsed request arguments.
+ * @param string               $url         The request URL.
+ *
+ * @return false|array|WP_Error
+ */
+function cld_e2e_fake_cloud_intercept( $preempt, $parsed_args, $url ) {
+	if ( false === strpos( $url, 'api.cloudinary.com/v1_1/' . CLD_E2E_FAKE_CLOUD . '/' ) ) {
+		return $preempt;
+	}
+
+	return array(
+		'headers'  => array( 'content-type' => 'application/json' ),
+		'body'     => wp_json_encode( array( 'error' => array( 'message' => 'Invalid credentials (e2e fake cloud)' ) ) ),
+		'response' => array(
+			'code'    => 401,
+			'message' => 'Unauthorized',
+		),
+		'cookies'  => array(),
+		'filename' => null,
+	);
+}
 
 /**
  * Logs outgoing analytics/deactivation-reason requests and preempts them

README.md

@@ -37,8 +37,8 @@ Stay tuned for updates, tips and tutorials: [Blog](https://cloudinary.com/blog),
 
 ### Prerequisites
 
--   [Node.js](https://nodejs.org/) v16+ (see `.nvmrc`)
--   [npm](https://www.npmjs.com/) v6.9+
+-   [Node.js](https://nodejs.org/) v22+ (see `.nvmrc`)
+-   [npm](https://www.npmjs.com/) v10+
 -   [Composer](https://getcomposer.org/)
 -   [Docker](https://www.docker.com/) (required for the WordPress local environment via `wp-env`)
 

composer.json

@@ -7,15 +7,17 @@
     "ext-json": "*"
   },
   "require-dev": {
-    "dealerdirect/phpcodesniffer-composer-installer": "^0.7.0",
-    "phpcompatibility/phpcompatibility-wp": "dev-master",
-    "phpcompatibility/php-compatibility": "dev-develop as 9.99.99",
+    "dealerdirect/phpcodesniffer-composer-installer": "^1.2.1",
+    "phpcompatibility/phpcompatibility-wp": "^2.1.8",
+    "phpcompatibility/php-compatibility": "^9.3.5",
     "automattic/vipwpcs": "^3.0",
     "wp-coding-standards/wpcs": "^3.0",
     "phpstan/phpstan": "^2.0",
     "szepeviktor/phpstan-wordpress": "^2.0",
     "php-stubs/wp-cli-stubs": "^2.10",
-    "php-stubs/woocommerce-stubs": "^9.0"
+    "php-stubs/woocommerce-stubs": "^11.0",
+    "phpunit/phpunit": "^9.6@stable",
+    "yoast/phpunit-polyfills": "^4.0@stable"
   },
   "config": {
     "platform": {
@@ -34,7 +36,11 @@
     ],
     "phpstan": [
       "phpstan analyse --memory-limit=-1"
+    ],
+    "test": [
+      "phpunit"
     ]
   },
-  "minimum-stability": "dev"
+  "minimum-stability": "dev",
+  "prefer-stable": true
 }