Add optional step screenshots to QML E2E tests

Add a --screenshot-dir option to the onboarding and send/receive QML E2E tests and capture screenshots at major checkpoints using a shared StepScreenshotRecorder helper in the test harness.

Wait for known StackView instances to report busy == false before capturing screenshots so step images are less likely to catch page transitions mid-animation. Add objectName values for the main and onboarding page stacks so the bridge can observe their busy state.

Document the screenshot-dir test option in doc/test-bridge.md.

Author: johnny9

doc/test-bridge.md

@@ -235,6 +235,14 @@ python3 test/functional/qml_test_onboarding.py
 python3 test/functional/qml_test_send_receive.py
 ```
 
+To save step screenshots during the onboarding/send/receive E2E tests, pass a
+directory path:
+
+```bash
+python3 test/functional/qml_test_onboarding.py --screenshot-dir /tmp/qml-shots
+python3 test/functional/qml_test_send_receive.py --screenshot-dir /tmp/qml-shots
+```
+
 The harness starts `bitcoin-core-app` with `QT_QPA_PLATFORM=offscreen`,
 `-resetguisettings`, and a temporary datadir. Some tests (for example
 `qml_test_send_receive.py`) opt in to `-skiponboard` for faster deterministic

qml/pages/main.qml

@@ -34,6 +34,7 @@ ApplicationWindow {
 
     PageStack {
         id: main
+        objectName: "mainStack"
         initialItem: {
             if (needOnboarding) {
                 onboardingWizard
@@ -147,6 +148,7 @@ ApplicationWindow {
         id: node
         PageStack {
             id: nodeStack
+            objectName: "nodeStack"
             vertical: true
             initialItem: node
             Component {

qml/pages/onboarding/OnboardingWizard.qml

@@ -9,6 +9,7 @@ import "../../controls"
 
 PageStack {
     id: root
+    objectName: "onboardingWizardStack"
 
     signal finished()
     initialItem: cover
@@ -54,4 +55,4 @@ PageStack {
             onNext: root.finished()
         }
     }
-}
+}

test/functional/qml_test_harness.py

@@ -10,6 +10,7 @@
 
 import argparse
 import os
+import re
 import shutil
 import signal
 import socket
@@ -90,9 +91,59 @@ def parse_args():
              "this Unix socket path instead of launching a new one.  "
              "Start the app with: bitcoin-core-app -test-automation=<path>",
     )
+    parser.add_argument(
+        "--screenshot-dir",
+        help="If set, save step screenshots (PNG) into this directory.",
+    )
     return parser.parse_args()
 
 
+class StepScreenshotRecorder:
+    """Optional helper for saving labeled screenshots during tests."""
+
+    BUSY_STACK_OBJECTS = (
+        "mainStack",
+        "onboardingWizardStack",
+        "walletSendPage",
+    )
+
+    def __init__(self, driver, screenshot_dir=None):
+        self.driver = driver
+        self._counter = 0
+        self.screenshot_dir = (
+            os.path.abspath(screenshot_dir) if screenshot_dir else None
+        )
+        if self.screenshot_dir:
+            os.makedirs(self.screenshot_dir, exist_ok=True)
+
+    def capture(self, label):
+        if not self.screenshot_dir:
+            return None
+        # Screenshots taken immediately after a click/page change can catch
+        # StackView transitions mid-animation. Wait for known page stacks to
+        # finish transitioning (`busy == false`) before capturing.
+        for object_name in self.BUSY_STACK_OBJECTS:
+            try:
+                self.driver.wait_for_property(
+                    object_name, "busy", timeout_ms=5000, value=False
+                )
+            except QmlDriverError:
+                # Ignore missing objects/properties so the recorder remains
+                # compatible with tests that don't use a given stack.
+                pass
+        self._counter += 1
+        slug = re.sub(r"[^A-Za-z0-9._-]+", "_", label).strip("._-")
+        if not slug:
+            slug = "step"
+        path = os.path.join(self.screenshot_dir, f"{self._counter:02d}_{slug}.png")
+        info = self.driver.save_screenshot(path)
+        print(
+            f"  screenshot: {info.get('path', path)} "
+            f"({info.get('width', '?')}x{info.get('height', '?')})"
+        )
+        return path
+
+
 class QmlTestHarness:
     """Test harness that launches the GUI and connects the test bridge.
 

test/functional/qml_test_onboarding.py

@@ -13,7 +13,13 @@
 import sys
 import time
 
-from qml_test_harness import QmlTestHarness, QmlDriverError, dump_qml_tree, parse_args
+from qml_test_harness import (
+    QmlTestHarness,
+    QmlDriverError,
+    StepScreenshotRecorder,
+    dump_qml_tree,
+    parse_args,
+)
 
 
 def run_tests():
@@ -22,13 +28,15 @@ def run_tests():
     try:
         harness.start()
         gui = harness.driver
+        shots = StepScreenshotRecorder(gui, args.screenshot_dir)
 
         # The app starts fresh (-resetguisettings), so we should land on
         # the onboarding cover page.
         page = gui.get_current_page()
         print(f"Initial page: {page}")
         assert "onboardingCover" in page or "Cover" in page, \
             f"Expected to start on onboardingCover, got: {page}"
+        shots.capture("onboarding_cover")
 
         # Define the expected progression through onboarding.
         # Each entry is (button_to_click, expected_next_page).
@@ -48,6 +56,7 @@ def run_tests():
             assert expected_page in current, \
                 f"Expected {expected_page}, got: {current}"
             print(f"  -> page: {current}")
+            shots.capture(current)
 
         # Click Next on the final connection page to finish onboarding.
         print("Click onboardingConnectionButton (finish onboarding) ...")
@@ -61,6 +70,7 @@ def run_tests():
         print(f"  -> post-onboarding page: {final_page}")
         assert "onboarding" not in final_page.lower(), \
             f"Still on an onboarding page after finishing: {final_page}"
+        shots.capture(f"post_onboarding_{final_page}")
 
         print("\n" + "=" * 50)
         print("All tests PASSED")

test/functional/qml_test_send_receive.py

@@ -18,7 +18,7 @@
 from pathlib import Path
 from urllib.parse import quote
 
-from qml_test_harness import QmlTestHarness, dump_qml_tree
+from qml_test_harness import QmlTestHarness, StepScreenshotRecorder, dump_qml_tree
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 BITCOIN_FUNCTIONAL_PATH = REPO_ROOT / "bitcoin" / "test" / "functional"
@@ -42,6 +42,10 @@ def parse_args():
         "--socket-path",
         help="Attach to an existing bridge socket. Not supported by this test.",
     )
+    parser.add_argument(
+        "--screenshot-dir",
+        help="If set, save step screenshots (PNG) into this directory.",
+    )
     return parser.parse_args()
 
 
@@ -120,29 +124,34 @@ def run_tests():
     try:
         harness.start()
         gui = harness.driver
+        shots = StepScreenshotRecorder(gui, args.screenshot_dir)
 
         rpc, wallet_rpc = connect_rpc(harness.datadir, harness.rpc_port)
         ensure_wallet_loaded(rpc)
 
         wait_for_gui_wallet_ready(gui)
+        shots.capture("wallet_ready")
 
         # Fund the wallet with mature coinbase funds.
         funding_addr = wallet_rpc.getnewaddress("qml-e2e-funding", "bech32")
         rpc.generatetoaddress(101, funding_addr)
 
         # Capture baseline activity count in UI.
         select_wallet_tab(gui, "walletActivityTab", "activityListView")
+        shots.capture("activity_before")
         activity_count_before = int(gui.get_property("activityListView", "count"))
 
         # Receive flow: create request/address via QML.
         select_wallet_tab(gui, "walletReceiveTab", "walletRequestPaymentPage")
+        shots.capture("receive_page")
         gui.set_text("receiveAmountInput", str(SEND_AMOUNT_BTC))
         gui.set_text("receiveLabelInput", RECEIVE_LABEL)
         gui.set_text("receiveMessageInput", RECEIVE_MESSAGE)
         gui.click("receiveCreateAddressButton")
         receive_address_text = gui.wait_for_property(
             "receiveAddressText", "text", timeout_ms=15000, non_empty=True
         )
+        shots.capture("receive_request_created")
         receive_address = normalize_address(receive_address_text)
         assert receive_address, "Receive address is empty"
         assert rpc.validateaddress(receive_address)["isvalid"], "Receive address is invalid"
@@ -156,10 +165,13 @@ def run_tests():
         gui.set_text("sendAddressInput", receive_address)
         gui.set_text("sendAmountInput", str(SEND_AMOUNT_BTC))
         gui.set_text("sendNoteInput", SEND_NOTE)
+        shots.capture("send_form_filled")
         gui.click("sendContinueButton")
         gui.wait_for_page("walletSendReviewPage", timeout_ms=15000)
+        shots.capture("send_review")
         gui.click("sendConfirmButton")
         gui.wait_for_page("sendResultPopup", timeout_ms=15000)
+        shots.capture("send_result_popup")
         gui.click("sendResultCloseButton")
 
         sent_txid = {"value": None}
@@ -197,6 +209,7 @@ def find_sent_tx():
             lambda: int(gui.get_property("activityListView", "count")) > activity_count_before,
             timeout=30,
         )
+        shots.capture("activity_after")
 
         print("\n" + "=" * 50)
         print("QML send/receive E2E PASSED")