Build/Test Tools: Harden visual regression test stability.

Add network-idle wait with timeout fallback, jQuery animation guard,
mask selector validation warnings, and teardown error logging. Update
README to reflect the current local-only workflow.

Author: josephfusco

tests/visual-regression/README.md

@@ -1,11 +1,14 @@
 # Visual Regression Tests in WordPress Core
 
-These tests make use of Playwright, with a setup very similar to that of the e2e tests.
+These tests use Playwright to capture full-page screenshots of WordPress admin
+screens and compare them against baseline snapshots.
 
 ## How to Run the Tests Locally
 
-1. Check out trunk.
-2. Run `npm run test:visual` to generate some base snapshots.
-3. Check out the feature branch to be tested.
-4. Run `npm run test:visual` again. If any tests fail, the diff images can be found in `artifacts/`
-
+1. Start the local environment: `npm run env:start`
+2. Generate baseline snapshots: `npm run test:visual -- --update-snapshots`
+3. Make your changes.
+4. Run `npm run test:visual` — any visual differences will fail and produce
+   diff images in `artifacts/`.
+5. Open the HTML report for a side-by-side comparison (opens automatically
+   after a local run, or see `artifacts/visual-report/`).

tests/visual-regression/specs/visual-snapshots.test.js

@@ -19,15 +19,44 @@
 import { test, expect } from '@wordpress/e2e-test-utils-playwright';
 
 /**
- * Waits for resources and fonts to finish loading.
+ * Waits for network activity, fonts, and jQuery animations to settle.
  *
  * @param {import('@playwright/test').Page} page
  */
 async function waitForPageReady( page ) {
 	await page.waitForLoadState( 'load' );
+
+	// Wait for in-flight requests (AJAX heartbeat, dashboard widgets) to
+	// finish. The 5 s timeout keeps the suite moving when a long-poll
+	// endpoint (e.g. heartbeat-tick) holds the connection open.
+	await page
+		.waitForLoadState( 'networkidle', { timeout: 5000 } )
+		.catch( () => {} );
+
 	// If a webfont fails to load (network issue, Docker DNS), this resolves
 	// with fallback fonts and the diff will surface the discrepancy.
 	await page.evaluate( () => document.fonts.ready );
+
+	// Wait for jQuery animations (e.g. dashboard widget slide-in) to
+	// complete. CSS animations are already disabled in the Playwright config,
+	// but jQuery .animate() bypasses that setting.
+	await page.evaluate( () => {
+		if ( typeof jQuery === 'undefined' ) {
+			return;
+		}
+		return new Promise( ( resolve ) => {
+			if ( jQuery.active === 0 && jQuery( ':animated' ).length === 0 ) {
+				resolve();
+				return;
+			}
+			const interval = setInterval( () => {
+				if ( jQuery.active === 0 && jQuery( ':animated' ).length === 0 ) {
+					clearInterval( interval );
+					resolve();
+				}
+			}, 100 );
+		} );
+	} );
 }
 
 /**
@@ -247,9 +276,21 @@ test.describe( 'Admin Visual Snapshots', () => {
 
 				let screenshotOptions = {};
 				if ( Array.isArray( masks ) ) {
-					screenshotOptions = {
-						mask: masks.map( ( s ) => page.locator( s ) ),
-					};
+					const locators = masks.map( ( s ) => page.locator( s ) );
+
+					// Warn when a mask selector matches nothing — the volatile
+					// element may have been removed or renamed, causing false diffs.
+					for ( let i = 0; i < locators.length; i++ ) {
+						const count = await locators[ i ].count();
+						if ( count === 0 ) {
+							// eslint-disable-next-line no-console
+							console.warn(
+								`[${ name }] mask selector "${ masks[ i ] }" matched 0 elements`
+							);
+						}
+					}
+
+					screenshotOptions = { mask: locators };
 				} else if ( typeof masks === 'function' ) {
 					screenshotOptions = { mask: masks( page ) };
 				}
@@ -260,7 +301,16 @@ test.describe( 'Admin Visual Snapshots', () => {
 				);
 			} finally {
 				if ( teardown ) {
-					await teardown( requestUtils, data );
+					try {
+						await teardown( requestUtils, data );
+					} catch ( err ) {
+						// Log but don't mask the original assertion failure.
+						// eslint-disable-next-line no-console
+						console.error(
+							`[${ name }] teardown failed:`,
+							err.message
+						);
+					}
 				}
 			}
 		} );