dev: use E2E fixtures

Author: Soare Robert-Daniel

bin/e2e-after-setup.sh

@@ -1,5 +1,6 @@
-# Run after `npm run wp-env start`
-
-# Add some woocommerce products.
-npm run wp-env run tests-cli bash ./wp-content/plugins/woocommerce-product-addon/bin/env/create-products.sh
+#!/usr/bin/env bash
 
+# Run after `npm run wp-env start`
+#
+# E2E setup is fixture-driven now, so no shared catalog bootstrap is required here.
+exit 0

tests/e2e/AGENTS.md

@@ -0,0 +1,81 @@
+# E2E Test Guidance
+
+This folder contains Playwright tests for PPOM behavior in WordPress/WooCommerce.
+
+## Default Approach
+
+- Prefer stable server-side setup over admin UI setup.
+- Use the `fixtures/` helpers for storefront, cart, checkout, rendering, pricing, and conditional-logic tests.
+- Use `utils.js` only when the admin builder UI or attach modal UI is the feature under test.
+- Keep UI setup smoke coverage thin. Do not make every E2E test create fields by clicking through the dashboard.
+
+## Use `fixtures/` When
+
+- The test only needs PPOM data to exist.
+- You are validating product-page rendering, defaults, conditions, add-to-cart behavior, or checkout behavior.
+- You need products or categories created quickly and deterministically.
+
+Current fixture modules are split by concern:
+
+- `fixtures/woocommerce.js` for WooCommerce entities
+- `fixtures/ppom.js` for PPOM setup and attachments
+- `fixtures/fields.js` for PPOM field builders
+- `fixtures/internal.js` for shared request plumbing
+- `fixtures/index.js` as the public entrypoint
+
+Current fixture helpers support:
+
+- WooCommerce product creation through `wc/v3/products`
+- Product category creation through `wc/v3/products/categories`
+- PPOM group creation through `ppom_save_form_meta`
+- PPOM attachment through `ppom_attach_ppoms`
+
+## Use `utils.js` When
+
+- The admin builder itself is under test.
+- The attach modal behavior itself is under test.
+- The test needs to verify drag/drop, field ordering, modal controls, or admin-only interactions.
+
+## Setup Rules
+
+- Do not create products through wp-admin UI unless the UI is the thing being tested.
+- For product setup, prefer authenticated REST requests through `requestUtils`.
+- For PPOM group setup, prefer admin AJAX through the existing plugin callbacks instead of direct DB writes.
+- Do not persist raw fixture assumptions that bypass plugin save hooks unless the test explicitly targets a lower layer.
+- Admin UI specs can still use WooCommerce fixtures for prerequisite products and categories.
+
+## Nonce Notes
+
+- `ppom_form_nonce` is available on `wp-admin/admin.php?page=ppom&action=new`.
+- `ppom_attached_nonce` is not present on the main PPOM index page.
+- To attach groups, fetch the popup HTML from:
+  `wp-admin/admin-ajax.php?action=ppom_get_products&ppom_id=<ppomId>`
+- Scrape the attach nonce from that response before calling `ppom_attach_ppoms`.
+
+## Flake Reduction
+
+- Avoid using `waitForTimeout()` for state setup unless there is no deterministic alternative.
+- Prefer request-level setup plus direct storefront assertions.
+- Keep random data unique enough to avoid collisions across reruns.
+- Avoid `console.log` in committed specs unless it is intentionally diagnostic.
+- Assert fixture write success before navigating to the storefront.
+
+## Test Design
+
+- Separate admin smoke tests from storefront behavior tests.
+- For conditions, pricing, and defaults, build the smallest field schema needed for the assertion.
+- Prefer one clear behavior per test.
+- If a flow depends on quantity, coupons, restore-from-session, or uploads, seed only the minimum data needed and assert the exact WooCommerce outcome.
+
+## Verification
+
+- If local E2E fails before tests start, check whether the WordPress env is reachable before debugging the spec.
+- The current suite expects the wp-env site to be available and global setup to authenticate successfully.
+- When changing fixtures, run the smallest spec set that exercises the changed helper first.
+- If `wp-admin/admin.php?page=ppom` returns `403` while `wp-admin/profile.php` still works, treat that as an environment bootstrap issue first.
+- In practice that usually means WooCommerce or PPOM is inactive in the local env, not that Playwright logged the user out.
+
+## Practical Rule Of Thumb
+
+- If the question is "does the product page behave correctly?", use fixtures.
+- If the question is "does the PPOM admin interface work correctly?", use UI helpers.

tests/e2e/config/global-setup.ts

@@ -41,4 +41,4 @@ async function globalSetup( config: FullConfig ) {
 	await requestContext.dispose();
 }
 
-export default globalSetup;
+export default globalSetup;

tests/e2e/fixtures/fields.js

@@ -0,0 +1,49 @@
+function buildField( type, { title, dataName, ...overrides } ) {
+	return {
+		type,
+		title,
+		data_name: dataName,
+		description: '',
+		placeholder: '',
+		error_message: '',
+		width: '12',
+		visibility: 'everyone',
+		visibility_role: '',
+		status: 'on',
+		...overrides,
+	};
+}
+
+function buildOption( label, value, overrides = {} ) {
+	return {
+		option: label,
+		id: value,
+		price: '',
+		...overrides,
+	};
+}
+
+function buildTextField( args ) {
+	return buildField( 'text', args );
+}
+
+function buildSelectField( { options = [], ...args } ) {
+	return buildField( 'select', {
+		...args,
+		options: options.map( ( option ) =>
+			buildOption( option.label, option.value, option.overrides )
+		),
+	} );
+}
+
+function buildCheckboxField( { options = [], checked = [], ...args } ) {
+	return buildField( 'checkbox', {
+		...args,
+		checked: checked.join( '\r\n' ),
+		options: options.map( ( option ) =>
+			buildOption( option.label, option.value, option.overrides )
+		),
+	} );
+}
+
+export { buildCheckboxField, buildSelectField, buildTextField };

tests/e2e/fixtures/index.js

@@ -0,0 +1,12 @@
+export {
+	attachPpomGroupToCategories,
+	attachPpomGroupToProducts,
+	createPpomGroup,
+	createSimpleTextGroup,
+} from './ppom.js';
+export {
+	buildCheckboxField,
+	buildSelectField,
+	buildTextField,
+} from './fields.js';
+export { createProductCategory, createSimpleProduct } from './woocommerce.js';

tests/e2e/fixtures/internal.js

@@ -0,0 +1,100 @@
+function uniqueSuffix() {
+	return `${ Date.now() }-${ Math.floor( Math.random() * 100000 ) }`;
+}
+
+function appendNestedParams( params, prefix, value ) {
+	if ( value === undefined || value === null ) {
+		return;
+	}
+
+	if ( Array.isArray( value ) ) {
+		value.forEach( ( item, index ) => {
+			appendNestedParams( params, `${ prefix }[${ index }]`, item );
+		} );
+		return;
+	}
+
+	if ( typeof value === 'object' ) {
+		Object.entries( value ).forEach( ( [ key, nestedValue ] ) => {
+			appendNestedParams( params, `${ prefix }[${ key }]`, nestedValue );
+		} );
+		return;
+	}
+
+	params.append( prefix, String( value ) );
+}
+
+async function getAdminNonce( requestUtils, path, fieldName ) {
+	const response = await requestUtils.request.get( path, {
+		failOnStatusCode: false,
+	} );
+	const html = await response.text();
+
+	if ( ! response.ok() ) {
+		const summary = html.replace( /\s+/g, ' ' ).trim().slice( 0, 160 );
+		const environmentHint = html.includes(
+			'Sorry, you are not allowed to access this page.'
+		)
+			? ' Ensure WooCommerce and PPOM are active in the E2E environment.'
+			: '';
+
+		throw new Error(
+			`Failed to load admin nonce source "${ path }": ${ response.status() } ${ response.statusText() }. ${ summary }${ environmentHint }`
+		);
+	}
+
+	const matcher = new RegExp(
+		`name=["']${ fieldName }["'][^>]*value=["']([^"']+)["']`
+	);
+	const nonce = html.match( matcher )?.[ 1 ];
+
+	if ( ! nonce ) {
+		const summary = html.replace( /\s+/g, ' ' ).trim().slice( 0, 160 );
+
+		throw new Error(
+			`Failed to find admin nonce "${ fieldName }" on "${ path }". Response started with: ${ summary }`
+		);
+	}
+
+	return nonce;
+}
+
+async function getAttachNonce( requestUtils, ppomId ) {
+	return getAdminNonce(
+		requestUtils,
+		`wp-admin/admin-ajax.php?action=ppom_get_products&ppom_id=${ ppomId }`,
+		'ppom_attached_nonce'
+	);
+}
+
+async function postAdminAjax( requestUtils, params ) {
+	const response = await requestUtils.request.fetch(
+		'wp-admin/admin-ajax.php',
+		{
+			method: 'POST',
+			failOnStatusCode: true,
+			headers: {
+				'content-type':
+					'application/x-www-form-urlencoded; charset=UTF-8',
+			},
+			data: params.toString(),
+		}
+	);
+	const payload = await response.json();
+
+	if ( payload?.status !== 'success' ) {
+		throw new Error(
+			`Admin AJAX request failed: ${ JSON.stringify( payload ) }`
+		);
+	}
+
+	return payload;
+}
+
+export {
+	appendNestedParams,
+	getAdminNonce,
+	getAttachNonce,
+	postAdminAjax,
+	uniqueSuffix,
+};

tests/e2e/fixtures/ppom.js

@@ -0,0 +1,116 @@
+import { buildTextField } from './fields.js';
+import {
+	appendNestedParams,
+	getAdminNonce,
+	getAttachNonce,
+	postAdminAjax,
+	uniqueSuffix,
+} from './internal.js';
+
+async function createPpomGroup( requestUtils, { groupName, fields } ) {
+	const formNonce = await getAdminNonce(
+		requestUtils,
+		'wp-admin/admin.php?page=ppom&action=new',
+		'ppom_form_nonce'
+	);
+
+	const ppomFields = new URLSearchParams();
+	fields.forEach( ( field, index ) => {
+		appendNestedParams( ppomFields, `ppom[${ index + 1 }]`, field );
+	} );
+
+	const params = new URLSearchParams();
+	params.append( 'action', 'ppom_save_form_meta' );
+	params.append( 'ppom_form_nonce', formNonce );
+	params.append( 'productmeta_id', '' );
+	params.append( 'product_id', '0' );
+	params.append( 'productmeta_name', groupName );
+	params.append( 'dynamic_price_hide', 'no' );
+	params.append( 'send_file_attachment', '' );
+	params.append( 'show_cart_thumb', 'no' );
+	params.append( 'aviary_api_key', '' );
+	params.append( 'productmeta_style', '' );
+	params.append( 'productmeta_js', '' );
+	params.append( 'ppom', ppomFields.toString() );
+
+	const payload = await postAdminAjax( requestUtils, params );
+	const ppomId = Number( payload.productmeta_id );
+
+	if ( ! Number.isInteger( ppomId ) || ppomId <= 0 ) {
+		throw new Error(
+			`PPOM save did not return a valid productmeta_id: ${ JSON.stringify(
+				payload
+			) }`
+		);
+	}
+
+	return {
+		...payload,
+		ppomId,
+	};
+}
+
+async function createSimpleTextGroup(
+	requestUtils,
+	{
+		groupName,
+		fieldsNumber = 2,
+		titlePrefix = 'Test',
+		dataNamePrefix = 'test',
+	} = {}
+) {
+	const suffix = uniqueSuffix();
+	const fields = Array.from( { length: fieldsNumber }, ( _, index ) =>
+		buildTextField( {
+			title: `${ titlePrefix } ${ index + 1 } ${ suffix }`,
+			dataName: `${ dataNamePrefix }_${ index + 1 }_${ suffix }`,
+		} )
+	);
+
+	return createPpomGroup( requestUtils, {
+		groupName: groupName ?? `PPOM Group ${ suffix }`,
+		fields,
+	} );
+}
+
+async function attachPpomGroupToProducts( requestUtils, { ppomId, productIds } ) {
+	const attachNonce = await getAttachNonce( requestUtils, ppomId );
+
+	const params = new URLSearchParams();
+	params.append( 'action', 'ppom_attach_ppoms' );
+	params.append( 'ppom_attached_nonce', attachNonce );
+	params.append( 'ppom_id', String( ppomId ) );
+	params.append( 'ppom-attach-to-products-initial', '' );
+
+	productIds.forEach( ( productId ) => {
+		params.append( 'ppom-attach-to-products[]', String( productId ) );
+	} );
+
+	return postAdminAjax( requestUtils, params );
+}
+
+async function attachPpomGroupToCategories(
+	requestUtils,
+	{ ppomId, categorySlugs }
+) {
+	const attachNonce = await getAttachNonce( requestUtils, ppomId );
+
+	const params = new URLSearchParams();
+	params.append( 'action', 'ppom_attach_ppoms' );
+	params.append( 'ppom_attached_nonce', attachNonce );
+	params.append( 'ppom_id', String( ppomId ) );
+	params.append( 'ppom-attach-to-products-initial', '' );
+
+	categorySlugs.forEach( ( slug ) => {
+		params.append( 'ppom-attach-to-categories[]', slug );
+	} );
+
+	return postAdminAjax( requestUtils, params );
+}
+
+export {
+	attachPpomGroupToCategories,
+	attachPpomGroupToProducts,
+	createPpomGroup,
+	createSimpleTextGroup,
+};