Release testing instructions for WC Payments 10.9.0 - Automattic/woocommerce-payments GitHub Wiki

Reports area — Balance & Fees tabs (feature-flagged)

Feature flag: _wcpay_feature_reports_area (off by default). Adds a new Payments → Reports admin area with two tabs: Balance (reconciliation) and Fees (ledger).

Prerequisites

• A store connected to a WooPayments test/sandbox account.
• The account should have transaction + fee history and at least one payout / balance activity in a recent month, so both reports have data. (A brand-new account with no activity is fine for empty-state checks but won't exercise the happy path.)
• Admin user with the manage_woocommerce capability.

Enable the feature flag

Use either method:

WP-CLI

wp option update _wcpay_feature_reports_area 1

Code snippet (e.g. via a mu-plugin or Code Snippets)

add_filter( 'pre_option__wcpay_feature_reports_area', fn() => '1' );

To return to the default (disabled) state: wp option delete _wcpay_feature_reports_area (or set it back to 0).

---

1. Flag gating

1. With the flag off (default), go to Payments in the admin menu.
   • ✅ There is no “Reports” submenu item.
   • ✅ Visiting admin.php?page=wc-admin&path=/payments/reports directly does not render the Reports page.
2. Enable the flag and reload wp-admin.
   • ✅ A “Reports” item now appears under Payments.

2. Navigation & tabs

1. Open Payments → Reports.
   • ✅ The page loads with two tabs: Balance and Fees.
   • ✅ Balance is selected by default.
2. Click the Fees tab.
   • ✅ The URL updates to include &tab=fees.
3. Reload the page on the Fees tab, then use the browser Back button.
   • ✅ Deep-linking to &tab=fees opens directly on the Fees tab.
   • ✅ Back/forward navigation switches tabs correctly (no blank panel).

3. Balance tab

1. On the Balance tab, observe the date control.
   • ✅ The date range filter is open/expanded by default (it's the report's only control — this is intentional and differs from the Fees tab).
   • ✅ It defaults to the previous full calendar month (e.g. "Date between (inc): 1 May 2026 and 31 May 2026").
2. Pick a date range with known activity using a preset (see §5) or Custom.
   • ✅ A Balance summary table renders with a starting balance, categorized activity, and an ending balance. Typical rows (vary by account activity):
     • Starting balance – {date} UTC
     • Total charges captured (n items)
     • Fees — with sub-rows Charge fees, Dispute fees, Fee refunds
     • Refunds (n items), Refund failures (n items)
     • Disputes (n items)
     • Financing payout / Financing paydown (Capital — only when present)
     • Net balance change in the period
     • Payouts (n items)
     • Ending balance – {date} UTC
   • ✅ Subcategory rows like Reader fees / Network costs appear only when their value is non-zero for the period (expected to be absent for standard merchants).
3. Select a range with no balance activity (e.g. the previous year on a newer account), or click Reset to clear the date filter entirely.
   • ✅ The summary is replaced by an empty state: heading "No balance activity" + "Your Balance summary will appear here once there's enough data to display."
   • ✅ Print and Export become disabled.
4. The Export/Print buttons sit in the page header (above the tabs). When there's no usable data they are visibly disabled (greyed out), and the report body shows the "No balance activity" empty state (or a loading state while fetching).
   • Note: the specific reason is announced to screen readers only — exposed via aria-describedby to a visually-hidden (screen-reader-text) element, not a hover tooltip. To verify the exact wording, use a screen reader (e.g. VoiceOver) or inspect the button's aria-describedby target in DevTools. The three messages are:
     • No date range applied → "Select a date range to enable Print and Export."
     • Still loading → "Print and Export are available once the Balance report finishes loading."
     • Selected range has no activity (empty result) → "Print and Export are unavailable when the selected range has no Balance activity."

4. Fees tab

1. On the Fees tab, observe the toolbar.
   • ✅ No filters are applied by default — the report shows all-time fees (unlike Balance, which defaults to the previous month). Only an Add filter button (collapsed) and a Search fees box are shown.
2. Confirm the default-visible columns (in this order): Date & time, Transaction ID, Method, Type, Order ID, Currency, Gross amount, Fees total.
   • Note: Settlement date and Payout ID are hidden by default — turn them on via View options (the column-visibility control).
3. Open Add filter — the available filters are Date, Method, and Type (Gross amount / Fees total / Settlement date filters were intentionally removed).
4. Apply a Date filter.
   • ✅ Conditions: On / Before / After / Between (inc).
   • ✅ Presets resolve correctly (see §5).
5. Type into Search fees.
   • ✅ The ledger filters to matching rows.
6. Sort by Date & time, Gross amount, and Fees total.
   • ✅ Sorting works for each.
7. Page through results using the pagination control (Page X of N, Previous/Next).
   • ✅ Navigation works and the page indicator updates.
8. Toggle column visibility via View options, then reload the page.
   • ✅ Column visibility persists (stored per user).
9. Click links in Transaction ID and Order ID cells (and Payout ID once enabled via View options).
   • ✅ Each navigates to the correct destination (transaction details / order edit / payout details).
10. Apply filters/sort, then copy the URL into a new tab.

• ✅ The view is reproduced from the URL (filter + sort state is URL-synced; e.g. a Between range adds &date_between[0]=…&date_between[1]=…).

5. Date presets (shared by both tabs — same DataViews date filter)

The presets shown depend on the selected Condition:

• Between (inc) → Previous month, Previous year, Last 7 days, Last 30 days, Month to date, Last year, Year to date, Custom.
• On / Before / After (single date) → Today, Yesterday, Past week, Past month, Custom.

("Previous month" and "Previous year" are the newly-added WooPayments presets; the others come from the native DataViews date filter.)

1. Try each preset and verify the resolved range, e.g.:
   • ✅ Previous month = the full previous calendar month (1st → last day).
   • ✅ Previous year = Jan 1 → Dec 31 of last year (e.g. 2025-01-01 → 2025-12-31).
   • ✅ Month to date = 1st of this month → today; Year to date = Jan 1 → today.
2. Re-open the popover after applying a preset.
   • ✅ The active preset chip is highlighted; a hand-entered range shows as Custom.

6. Feedback survey (Balance tab)

1. On the Balance tab, locate the inline feedback prompt: “Did this report give you the information you needed?” with thumbs up/down.
2. Click thumbs up → optional comment (“What did you use this report for?”); click thumbs down → optional comment (“What's missing?”).
3. Add a comment and click Send.
   • ✅ A success notice (“Thanks for your feedback!”) appears.
   • ✅ The privacy disclaimer link points to the Automattic privacy policy.
4. Dismiss the survey with the close (✕) control.
   • ✅ It dismisses cleanly.

7. CSV export & Print

Fees export

1. On the Fees tab, click Export (primary button in the page header — the Fees tab has no Print button).
   • ✅ A CSV downloads containing the currently filtered rows.

Balance export & print

1. On the Balance tab with a range that has activity, click Export.
   • ✅ A CSV downloads. The header row is: business_name,woopayments_account_id,row_key,label,amount,count,currency,period_start,period_end
   • ✅ The first two columns are business_name and woopayments_account_id on every row, followed by the balance rows (amounts in minor units / cents).
2. Click Print.
   • ✅ The browser print dialog opens with a print-styled layout (not the raw admin chrome).

8. Tracks / analytics events (optional — needs a Tracks inspector)

Requires a way to observe Tracks events (e.g. Tracks Vigilante 2). Each event should fire once per action.

Action	Event(s) expected
Open the Reports page	page_view (path payments_reports) + a load event for the active tab
Switch between tabs	wcpay_reports_tab_change
Balance loads / fails	wcpay_reports_balance_load_success / wcpay_reports_balance_load_error
Change Balance date filter	wcpay_reports_balance_date_filter_change
Balance reload	wcpay_reports_balance_reload_click
Balance Export	wcpay_reports_balance_export_click → wcpay_reports_balance_export_success (or …_export_error)
Balance Print	wcpay_reports_balance_print_click
Fees loads / fails	wcpay_reports_fees_load_success / wcpay_reports_fees_load_error
Change Fees date filter	wcpay_reports_fees_date_filter_change
Change other Fees filter	wcpay_reports_fees_filter_change
Search the Fees ledger	wcpay_reports_fees_search
Fees reload	wcpay_reports_fees_reload_click
Fees Export	wcpay_csv_export_click → wcpay_reports_fees_export_success (or …_export_error)
Feedback survey shown	wcpay_reports_feedback_view
Click thumbs up / down	wcpay_reports_feedback_thumbs_up / wcpay_reports_feedback_thumbs_down
Submit / cancel / dismiss feedback	wcpay_reports_feedback_submit (or …_submit_error) / …_feedback_cancel / …_feedback_dismiss

---

Notes / troubleshooting

• Balance data comes from the server. If the Balance tab shows an error or stays empty for a range that clearly has activity, the Transact Platform balance-summary endpoint may not yet be available for that account — confirm with the server team rather than treating it as a client bug.
• The Balance-open / Fees-collapsed default filter difference is intentional by design — not an inconsistency to report.
• The flag must be disabled before release sign-off (it ships off by default).