Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The project includes frontend test tooling for the React admin interface:

## Documentation Language

All specs and planning artifacts are written in English — OpenSpec proposals, delta specs, design docs and task lists under `openspec/changes/`, PRDs, plans and analysis docs under `.claude/tasks/`, plus the changelog and README. This holds regardless of the language of the conversation that produced them: chat may be in Russian, the written artifact is English.
All specs and planning artifacts are written in English — OpenSpec proposals, delta specs, design docs and task lists under `openspec/changes/`, PRDs, plans and analysis docs under `.claude/tasks/`, plus the changelog and README. Chat is in English as well.

## Version Bump

Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -423,7 +423,7 @@ Yes. Turn on product IDs in WooCommerce Settings and choose the format that matc

### Can I stop admins and staff being tracked?

Yes. Under Advanced Settings, choose any user roles (Administrator, Editor, Shop manager and more) that should not have the tracking script loaded.
Yes. Under Advanced Settings, choose any user roles (Administrator, Editor, Shop manager and more) that should not be tracked. The tracking script is not loaded for them, and their form and WooCommerce events are not sent while they are signed in. A Purchase can still be sent when a payment gateway, automation or another staff member changes the order's status, and a tracking script added to the site by hand is not affected.

### Is PixelFlow GDPR compliant?

Expand Down Expand Up @@ -469,6 +469,9 @@ Documentation, video tutorials and email support on all plans. Ask a question in

## Changelog

### 1.2.3
Excluded user roles now also stop WooCommerce AddToCart, InitiateCheckout and Purchase events from their own signed-in requests, so sites that exclude roles may see lower event counts

### 1.2.2
WooCommerce: optional setting to send Purchase only for a customer's first paid order, so subscription renewals and repeat orders stop counting as new purchases. Forms: events now include city, state, postcode and country from the visitor's location when the form has no such fields.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -177,12 +177,45 @@ describe('AdvancedSettings — excluded roles and WooCommerce event sending', ()
Object.keys(contextOverrides).forEach((key) => delete contextOverrides[key]);
});

it('states the limitation when WooCommerce tracking is on', () => {
it('states what the setting excludes under its new title', () => {
Object.assign(contextOverrides, { availableRoles: roles });
render(<AdvancedSettings />);

expect(screen.getByText('Exclude Tracking for User Roles')).toBeInTheDocument();
expect(
screen.getByText(
/tracking script is not loaded for them, and their form and WooCommerce events are not sent/
)
).toBeInTheDocument();
});

it('states the hand-added script limit once a role is selected', () => {
Object.assign(contextOverrides, {
availableRoles: roles,
generalOptions: { ...generalOptions, excluded_user_roles: ['administrator'] },
});
render(<AdvancedSettings />);

expect(
screen.getByText(/tracking script added to the site by hand is not affected/)
).toBeInTheDocument();
});

it('does not state the hand-added script limit with no role selected', () => {
Object.assign(contextOverrides, { availableRoles: roles });
render(<AdvancedSettings />);

expect(
screen.queryByText(/tracking script added to the site by hand is not affected/)
).not.toBeInTheDocument();
});

it('states the Purchase limit when WooCommerce tracking is on', () => {
Object.assign(contextOverrides, { availableRoles: roles });
render(<AdvancedSettings />);

expect(screen.getByTestId('excluded-roles-woo-note')).toHaveTextContent(
'not applied to WooCommerce event sending'
"A Purchase can still be sent when a payment gateway, automation or another staff member changes the order's status"
);
});

Expand Down
16 changes: 9 additions & 7 deletions app/source/src/features/settings/components/AdvancedSettings.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -133,11 +133,12 @@ export function AdvancedSettings() {
{availableRoles.length > 0 && (
<section>
<h3 className="text-base font-semibold mb-2 !text-foreground">
Exclude Script for User Roles
Exclude Tracking for User Roles
</h3>
<p className="text-sm text-foreground ml-12">
Select user roles that should NOT have the tracking script injected when they visit
the site. Useful for excluding administrators, editors, or other internal users.
Select user roles that should not be tracked while signed in. The tracking script is
not loaded for them, and their form and WooCommerce events are not sent. Useful for
excluding administrators, editors, or other internal users.
</p>
<div className="space-y-2">
{availableRoles.map((role) => {
Expand All @@ -162,14 +163,15 @@ export function AdvancedSettings() {
</div>
{excludedRoles.length > 0 && (
<p className="text-xs text-gray-600 mt-3">
<strong>Note:</strong> Users with excluded roles will not have tracking script
injected.
<strong>Note:</strong> A tracking script added to the site by hand is not affected
by this setting.
</p>
)}
{isWooCommerceActive && generalOptions.woo_enabled === 1 && (
<p className="text-xs text-gray-600 mt-2" data-testid="excluded-roles-woo-note">
This setting is not applied to WooCommerce event sending: add to cart, checkout
and purchase events are still sent for these roles. Form events are not.
A Purchase can still be sent when a payment gateway, automation or another staff
member changes the order's status, because that request does not belong to the
excluded user.
</p>
)}
</section>
Expand Down
33 changes: 25 additions & 8 deletions docs/test-scenarios.html
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>PixelFlow 1.2.2 — Test Scenario Matrix</title>
<title>PixelFlow 1.2.3 — Test Scenario Matrix</title>
<style>
:root {
--bg: #f7f7f5;
Expand Down Expand Up @@ -86,15 +86,15 @@
<div class="wrap">

<header>
<h1>PixelFlow 1.2.2 — Test Scenario Matrix</h1>
<p class="sub">What the plugin's behaviour is actually verified against, organised by capability rather than by test file. Generated 2026-10-11 from <code>feat/wordpress-first-purchase</code>, for the OpenSpec changes <code>add-woo-first-purchase-only</code> and <code>add-form-location-from-cookie</code>.</p>
<p class="sub"><strong>Last full run:</strong> 2026-10-11 on <code>c52533c</code> — PHP 482/482 (35 files, on PHP 8.3; not rerun on PHP 7.4) · component tests 72/72 · admin E2E 7/7 (these three on <code>8ce5a6f</code>; later commits change no PHP or admin code) · live storefront matrix 133/134 in one run, with the browser leaving through an EU address. The one failure, the Elementor Pro case of the form hold spec, came from the suite itself (a click before Elementor bound its submit, and a repeat window the reset no longer cleared); after the fix in <code>9059e44</code> that case passed five times in a row.</p>
<h1>PixelFlow 1.2.3 — Test Scenario Matrix</h1>
<p class="sub">What the plugin's behaviour is actually verified against, organised by capability rather than by test file. Generated 2026-11-01 from <code>fix/woo-excluded-roles</code>, for the OpenSpec change <code>fix-woo-excluded-roles</code>.</p>
<p class="sub"><strong>Last full run:</strong> 2026-11-01 on <code>4ecfab8</code> — PHP 512/512 (38 files, on PHP 8.5.4; not rerun on PHP 7.4) · component tests 80/80 · admin E2E 7/7 · live storefront matrix 140/140 in one run, with the browser leaving through an EU address.</p>

<div class="stats">
<div class="stat"><b>207</b><span>scenarios in this matrix</span></div>
<div class="stat"><b>192</b><span>covered</span></div>
<div class="stat"><b>217</b><span>scenarios in this matrix</span></div>
<div class="stat"><b>202</b><span>covered</span></div>
<div class="stat"><b>15</b><span>partial or uncovered</span></div>
<div class="stat"><b>695</b><span>automated cases (482 PHP · 72 vitest · 7 admin E2E · 134 live E2E)</span></div>
<div class="stat"><b>739</b><span>automated cases (512 PHP · 80 vitest · 7 admin E2E · 140 live E2E)</span></div>
</div>

<div class="legend">
Expand Down Expand Up @@ -402,7 +402,7 @@ <h2 id="form-events"><a class="anchor" href="#form-events">17. Form events</a> <
<tr><td class="id">FRM-26</td><td>A form the listing missed</td><td>Sends with its computed configuration; adds no row</td><td class="where">tests/test-form-adapters.php</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-27</td><td>Configured form deleted, trashed, unpublished or deactivated</td><td>Deleted or trashed: missing, locked, config kept, nothing sent; unpublished or deactivated: not missing; reappearing form resumes its config</td><td class="where">tests/test-form-missing.php</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-28</td><td>Forms tab in the settings page</td><td>Plugin status line, single double-count warning, switches, events, mapping panel, stale-choice highlight, save-only-what-changed</td><td class="where">app/source/src/test/forms-settings.test.tsx · e2e/tests/forms-settings.spec.ts</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-29</td><td>Excluded-roles note</td><td>Shown only with WooCommerce tracking on</td><td class="where">app/source/src/features/settings/components/AdvancedSettings.test.tsx</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-29</td><td>Excluded-roles Purchase note</td><td>Shown only with WooCommerce active and its tracking on</td><td class="where">app/source/src/features/settings/components/AdvancedSettings.test.tsx</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-30</td><td>Site without WooCommerce</td><td>Form flush script loads; send, hold and replay work; nothing reaches the WooCommerce queue</td><td class="where">tests/test-form-*.php <em>(no WC())</em> · e2e/live/tests/forms-without-woo.spec.ts</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-31</td><td>Two concurrent requests of one double click</td><td>The request whose repeat-window insert loses sends nothing; closed windows are deleted by the next claim</td><td class="where">tests/test-form-skips.php <em>(the lost insert is simulated)</em></td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">FRM-32</td><td>An older held recipe when a later hold saves the queue again; a hint cookie whose queue is gone</td><td>Each recipe expires 48 h after it was stored; the state route removes the stale cookie</td><td class="where">tests/test-form-hold.php</td><td><span class="tag ok">Covered</span></td></tr>
Expand Down Expand Up @@ -450,6 +450,23 @@ <h2 id="load-first-purchase-lookup"><a class="anchor" href="#load-first-purchase
</table></div>
<p class="note">The former <code>exclude</code> argument (a <code>NOT IN</code> clause) cost 2–6 ms of the 40–65 ms legacy query at 50,000 orders. The cost is paid once per order, in the request that moves it to processing or completed, and only on stores that turn the setting on. Accepted and documented; an indexed email lookup for legacy storage would be a separate change.</p>

<h2 id="excluded-user-roles"><a class="anchor" href="#excluded-user-roles">20. Excluded user roles</a> <span class="count">— what a signed-in user with an excluded role still sends</span></h2>
<div class="scroll"><table>
<thead><tr><th>ID</th><th>Scenario</th><th>Expected behaviour</th><th>Verified in</th><th>Status</th></tr></thead>
<tbody>
<tr><td class="id">ROLE-01</td><td>A signed-in administrator with the role excluded opens a storefront page</td><td>None of the plugin's scripts are on the page</td><td class="where">e2e/live/tests/excluded-role.spec.ts</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-02</td><td>That user adds to cart and goes to checkout</td><td>No <code>AddToCart</code> or <code>InitiateCheckout</code> and no <code>/blocked-events</code> report; the debug log records <code>USER ROLE IS EXCLUDED FROM TRACKING</code></td><td class="where">tests/test-woo-excluded-roles.php · e2e/live/tests/excluded-role.spec.ts</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-03</td><td>The same events under an unanswered banner or declined consent</td><td>Nothing is held and no blocked report is sent</td><td class="where">tests/test-woo-excluded-roles.php</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-04</td><td>A user with several roles, one of them excluded</td><td>Excluded</td><td class="where">tests/test-woo-excluded-roles.php</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-05</td><td>The excluded user's own checkout</td><td>No <code>Purchase</code>; the order is not recorded as delivered (<code>_pf_purchase_sent</code> stays unset)</td><td class="where">tests/test-woo-excluded-roles.php · e2e/live/tests/excluded-role.spec.ts</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-06</td><td>A later request that is not theirs moves that order: a gateway webhook, automation or another staff member <em>(accepted limit)</em></td><td>The skipped <code>Purchase</code> is sent once, because that request does not belong to the excluded user; the settings page states this</td><td class="where">tests/test-woo-excluded-roles.php · e2e/live/tests/excluded-role.spec.ts <em>(status change over WP-CLI)</em></td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-07</td><td>An excluded administrator completes a real customer's order in wp-admin</td><td>The customer's <code>Purchase</code> is sent</td><td class="where">tests/test-woo-excluded-roles.php · e2e/live/tests/excluded-role.spec.ts</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-08</td><td>A role that is not excluded, a guest, or no roles excluded at all</td><td>Events are sent as before; on the storefront the tracking script is present</td><td class="where">tests/test-woo-excluded-roles.php · e2e/live/tests/excluded-role.spec.ts <em>(guest and customer)</em></td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-09</td><td>Events held earlier are replayed on an excluded user's request</td><td>They are sent; the replay is not judged by the current user's role</td><td class="where">tests/test-woo-excluded-roles.php</td><td><span class="tag ok">Covered</span></td></tr>
<tr><td class="id">ROLE-10</td><td>The setting on the settings page</td><td>Titled <code>Exclude Tracking for User Roles</code>; says a tracking script added by hand is not affected once a role is selected</td><td class="where">app/source/src/features/settings/components/AdvancedSettings.test.tsx</td><td><span class="tag ok">Covered</span></td></tr>
</tbody>
</table></div>

<footer>
<p><strong>How to run.</strong> PHP suites are plain scripts: <code>php tests/test-&lt;name&gt;.php</code> (exit 0 = green). Component tests: <code>npm run test</code> from <code>app/source/</code>. Local admin E2E: Playwright from <code>e2e/</code>. The live storefront suite runs against the live test site — invoke it through the <code>test-live-woo-events</code> skill rather than by hand, since it builds and installs the plugin first.</p>
<p>“Partial” means the behaviour is touched by a test that asserts something else; “Not covered” means no automated test exercises it today.</p>
Expand Down
7 changes: 7 additions & 0 deletions e2e/live/helpers/debug-log.ts
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,13 @@ export function skippedRecords(records: EventRecord[], name: string): EventRecor
);
}

/** Records for one event name that the plugin skipped because the user's role is excluded. */
export function excludedRoleRecords(records: EventRecord[], name: string): EventRecord[] {
return recordsNamed(records, name).filter(
(record) => record.response === 'USER ROLE IS EXCLUDED FROM TRACKING'
);
}

/**
* Blocked-events beacons for one event name.
*
Expand Down
7 changes: 7 additions & 0 deletions e2e/live/pages/settings-page.ts
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,13 @@ export class SettingsPage {
await this.openWooTab();
}

/** One role's switch under "Exclude Tracking for User Roles". */
async setRoleExcluded(role: string, excluded: boolean): Promise<void> {
await this.openAdvancedTab();
await this.setSwitch(`exclude-role-${role}`, excluded);
await this.openWooTab();
}

private excludedSkuChip(sku: string): Locator {
return this.page.getByRole('button', { name: `Remove SKU ${sku}` });
}
Expand Down
10 changes: 10 additions & 0 deletions e2e/live/presets.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ export interface SettingsState {
/** "Enable <event> event for free products". Defaults to all enabled. */
freebies?: Partial<Record<EventKey, boolean>>;
excludedSkus?: string[];
/** Role keys under "Exclude Tracking for User Roles". None unless given, so every preset restores it. */
excludedRoles?: string[];
/** "Only the customer's first purchase". Off unless given, so every preset restores it. */
firstPurchase?: {
lookback?: 'all' | 'days';
Expand All @@ -40,6 +42,10 @@ export async function applySettings(page: Page, state: SettingsState): Promise<v
}

await settings.setDebugLogging(state.debugLogging);
await settings.setRoleExcluded(
'administrator',
(state.excludedRoles ?? []).includes('administrator')
);

for (const event of EVENTS) {
await settings.setEventEnabled(event, state.events?.[event] ?? true);
Expand Down Expand Up @@ -98,3 +104,7 @@ export const FIRST_PURCHASE_ONLY: SettingsState = {
export function skusExcluded(...skus: string[]): SettingsState {
return { wooIntegration: true, debugLogging: true, excludedSkus: skus };
}

export function rolesExcluded(...roles: string[]): SettingsState {
return { wooIntegration: true, debugLogging: true, excludedRoles: roles };
}
Loading
Loading