Staging Initial Foundational commits by johnny9 · Pull Request #871 · bitcoin-core/gui-qml

johnny9 · 2026-08-19T04:01:13Z

This is the first in a series of staging PRs for the new QML-based Bitcoin Core GUI.

This PR adds the minimum application, build, lifecycle, and test foundation needed by later PRs. The UI is limited to a small window that shows node status.

Main decisions

Make QML the default GUI. BUILD_GUI builds QML as bitcoin-qt. With IPC enabled, it also builds bitcoin-gui using QML.
Keep the old GUI during migration. BUILD_GUI_LEGACY builds the Widgets GUI as bitcoin-qt-legacy and bitcoin-gui-legacy. It will be removed near the end of the staging series.
Use the standard test name for QML. BUILD_GUI_TESTS builds the QML test_bitcoin-qt. Legacy tests use BUILD_GUI_LEGACY_TESTS and test_bitcoin-qt-legacy.
Keep current dependencies separate. QML uses Qt QML, Quick, Quick Controls, and Network. Widgets, QR, and DBus stay with the legacy build for now. QR and DBus will move when their QML support is added.
Keep QML code under src/qml. This includes the application, models, resources, UI, and tests.
Reuse Bitcoin Core interfaces. The QML GUI uses the existing configuration, logging, node, wallet, and IPC interfaces.
New Shared Application Lifecycle class Production and integration tests use the same BitcoinQmlApplication class.
Keep node work off the GUI thread. Node startup and shutdown run on a worker thread. NodeModel exposes node state and block progress to QML.
QML Test Bridge for release binary functional testing The test bridge is part of standard builds, but it is disabled by default and restricted to regtest. The bridge accepts one local client and limits command size, JSON depth, and object-tree traversal.

Test frameworks and coverage

The PR uses three test frameworks across four test levels.

C++ unit tests

Qt Test checks individual C++ classes. These tests are fast and make failures easy to locate. Every cpp module should have a QtTest module to go with it. Mocks/fakes are used at the boundaries.

QML component tests

QML is Qt's language for defining UI components and their behavior. Qt Quick Test checks those components without starting the full application. These should verify the components signals/slots, state changes, input validations, etc. Any QML warnings should cause the tests to fail.

Current coverage:

Loads the production MainWindow.qml.
Checks the window name and title.
Checks the initial disconnected state.

Application integration tests

These tests run the application code and a regtest node in the same process.

This level:

Uses Core interfaces instead of mocks.
Tests Core, models, and QML together.
Directly checks signals, model state, QML properties, and RPC results.
Runs faster and is easier to debug than a full process test.

Current coverage:

Creates the production BitcoinQmlApplication.
Starts a real regtest node.
Loads the production QML window.
Waits for NodeModel to enter the running state.
Checks that QML shows "Node is running."
Calls getblockchaininfo and checks the regtest chain.
Shuts down cleanly.

End-to-end functional tests

The Python functional-test framework starts the real GUI executable as separate processes. These will target key user flows

This level tests:

Real executable startup and exit.
Command-line rules and isolated configuration.
Monolithic and multiprocess GUI builds.
Process and transport cleanup.
Validation of key user flows

Current coverage:

Runs bitcoin-qt and, when IPC is enabled, bitcoin-gui.
Rejects test automation outside regtest.
Lists QML objects and reads window properties.
Checks bridge error handling.
Closes the application and checks its exit status.
Checks QML-only TestShell startup and cleanup.
Keeps coverage for the existing two-node TestShell flow.

The functional test suite checks that the internal application parts work together. The functional suite checks the complete application across real process and operating-system boundaries.

Test runner

The first three levels use one test_bitcoin-qt executable:

test_bitcoin-qt --suite=unit
test_bitcoin-qt --suite=qml
test_bitcoin-qt --suite=integration

Build qtdeclarative and qtshadertools for the target and host. Keep qlalr available and link Xau for static XCB builds.

hebasto · 2026-08-24T16:08:29Z

+#ifdef WIN32
+    common::WinCmdLineArgs win_args;
+    std::tie(argc, argv) = win_args.get();
+#endif


d8c3e4e

This won't compile on Windows after bitcoin/bitcoin#32380.

good reminder. i need to do a check on windows myself to ensure we are windows compatible in this branch from the very begining.

It supposed to be done by the CI, no?

Add the optional bitcoin-qml executable with a minimal Qt Quick window. Build its backend and QML resources in a static library under src/qml. Co-authored-by: Matthew Zipkin <pinheadmz@pm.me> Co-authored-by: Jarol Rodriguez <jarolrod@tutanota.com>

Add Qt Test and Qt Quick Test runners. Load the production MainWindow resource in the Qt Quick smoke test. Co-authored-by: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>

Add an optional local-socket bridge for functional tests. Limit command size, client count, JSON depth, and object traversal. Co-authored-by: epicleafies <lukelpollard@gmail.com>

Add QML driver and process harness modules to the functional test framework. Expose bitcoin-qml capability checks and process management through BitcoinTestFramework and TestShell. Add an interface test for the application window and automation bridge.

Initialize and shut down the node on a worker thread. Expose lifecycle state and block progress through NodeModel, and stop cleanly when the window closes. Co-authored-by: johnny9 <johnny9dev@pm.me> Co-authored-by: João Barbosa <joao.paulo.barbosa@gmail.com> Co-authored-by: Jarol Rodriguez <jarolrod@tutanota.com>

Run BitcoinQmlApplication against a real in-process regtest node. Add an integration suite to the shared test_bitcoin-qt binary and run it in Windows cross CI.

johnny9 force-pushed the qml-foundation-staging branch from a18e63e to fa61bd4 Compare August 19, 2026 04:05

depends: Add Qt QML and Qt Quick modules

d56046f

Build qtdeclarative and qtshadertools for the target and host. Keep qlalr available and link Xau for static XCB builds.

johnny9 force-pushed the qml-foundation-staging branch from fa61bd4 to d8c3e4e Compare August 19, 2026 04:07

hebasto added the Stage label Aug 19, 2026

johnny9 marked this pull request as ready for review August 20, 2026 16:09

hebasto reviewed Aug 24, 2026

View reviewed changes

johnny9 and others added 7 commits August 26, 2026 11:24

init: Parameterize bitcoin-gui executable name

dfc7a4c

qml: Add application shell

4e641ce

Add the optional bitcoin-qml executable with a minimal Qt Quick window. Build its backend and QML resources in a static library under src/qml. Co-authored-by: Matthew Zipkin <pinheadmz@pm.me> Co-authored-by: Jarol Rodriguez <jarolrod@tutanota.com>

test: Add QML test infrastructure

d1ed6b7

Add Qt Test and Qt Quick Test runners. Load the production MainWindow resource in the Qt Quick smoke test. Co-authored-by: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>

qml: Add test automation bridge

172e9fd

Add an optional local-socket bridge for functional tests. Limit command size, client count, JSON depth, and object traversal. Co-authored-by: epicleafies <lukelpollard@gmail.com>

test: Add QML application integration tests

ceddd88

Run BitcoinQmlApplication against a real in-process regtest node. Add an integration suite to the shared test_bitcoin-qt binary and run it in Windows cross CI.

johnny9 force-pushed the qml-foundation-staging branch from d8c3e4e to ceddd88 Compare August 27, 2026 04:48

Navigation Menu

Uh oh!

Staging Initial Foundational commits - #871

Staging Initial Foundational commits#871
johnny9 wants to merge 8 commits into
bitcoin-core:stagingfrom
johnny9:qml-foundation-staging

johnny9 commented Aug 19, 2026 •

edited

Loading

Uh oh!

hebasto Aug 24, 2026

Uh oh!

johnny9 Aug 25, 2026

Uh oh!

hebasto Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

johnny9 commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Main decisions

Test frameworks and coverage

C++ unit tests

QML component tests

Application integration tests

End-to-end functional tests

Test runner

Uh oh!

hebasto Aug 24, 2026

Choose a reason for hiding this comment

Uh oh!

johnny9 Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

hebasto Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

johnny9 commented Aug 19, 2026 •

edited

Loading