Logitune tests are behavioral, not structural. Tests verify that features work end-to-end through the real signal chains, not that individual functions return specific values. The principle: tests fail until the feature works.

This means:

• Tests exercise AppRoot through its real signal connections (not mocked)
• Tests simulate user actions (focus changes, button presses, UI interactions) and verify the observable results (mock injector calls, profile state, model data)
• The only mocked components are hardware boundaries: MockDesktop, MockInjector, MockTransport, MockDevice
• Internal implementation details can change freely without breaking tests

graph TB
    subgraph "Tier 1: C++ Mock Tests (CI)"
        UnitTests[Unit Tests<br/>Profile, Action, Button, Transport, Features]
        IntegTests[Integration Tests<br/>AppRoot, ProfileSwitching, ThumbWheel]
        ModelTests[Model Tests<br/>DeviceModel, ButtonModel, ProfileModel, ActionModel]
    end

    subgraph "Tier 2: QML Tests (CI)"
        QMLTests[QML Component Tests<br/>ButtonCallout, BatteryChip, SideNav, etc.]
    end

    subgraph "Tier 3: Tray Tests (CI)"
        TrayTests[Tray Manager Tests<br/>Menu, actions, battery display]
    end

    subgraph "Tier 4: Hardware Tests (Manual)"
        HWTests[Hardware Integration<br/>ThumbWheel, Sleep/Wake, Settings, Features]
    end

    UnitTests --> IntegTests
    IntegTests --> QMLTests
    QMLTests --> TrayTests
    TrayTests --> HWTests

make test-all

This runs all three CI tiers in sequence.

# C++ unit/integration tests
make test

# QML component tests
make test-qml

# Tray manager tests
make test-tray

Hardware tests require BUILD_HW_TESTING=ON and a connected device:

cmake -B build -DBUILD_HW_TESTING=ON
cmake --build build
./build/tests/hw/logitune-hw-tests

The HardwareFixture waits up to 10 seconds for a device to connect. If no device is found, the test fails with a descriptive message.

# Run a single test by name
QT_QPA_PLATFORM=offscreen ./build/tests/logitune-tests --gtest_filter="ProfileSwitchTest.FocusChangeAppliesAppProfile"

# Run all tests matching a pattern
QT_QPA_PLATFORM=offscreen ./build/tests/logitune-tests --gtest_filter="ThumbWheel*"

# List all available tests
QT_QPA_PLATFORM=offscreen ./build/tests/logitune-tests --gtest_list_tests

Note: QT_QPA_PLATFORM=offscreen is required when running without a display (CI, SSH, containers).

tests/helpers/AppRootFixture.h is the primary integration test fixture. It provides:

classDiagram
    class AppRootFixture {
        #MockDesktop* m_desktop
        #MockInjector* m_injector
        #MockDevice m_device
        #unique_ptr~AppRoot~ m_ctrl
        #QString m_profilesDir
        #QTemporaryDir m_tmpDir
        
        +SetUp()
        +TearDown()
        +createAppProfile(wmClass, profileName, dpi, ...)
        +setProfileButton(profileName, buttonIdx, action)
        +setProfileGesture(profileName, direction, keystroke)
        +focusApp(wmClass)
        +pressButton(controlId)
        +releaseButton(controlId)
        +gestureXY(dx, dy)
        +thumbWheel(delta)
        +profileEngine() ProfileEngine&
        +profileModel() ProfileModel&
        +buttonModel() ButtonModel&
        +deviceModel() DeviceModel&
        +actionModel() ActionModel&
    }

SetUp creates:

1. MockDesktop and MockInjector (raw pointers, not owned by AppRoot)
2. AppRoot with injected mocks
3. Temporary profile directory with a seeded default.conf
4. MockDevice with MX Master 3S controls
5. Sets thumbWheelDefaultDirection = 1 (neutral, no direction normalization)

Helper methods:

Friend access: AppRootFixture is a friend of AppRoot, giving it access to private members for state inspection and direct manipulation (e.g., setting m_thumbWheelDefaultDirection).

Implements IDesktopIntegration with:

• simulateFocus(wmClass, title) — emits activeWindowChanged signal
• setRunningApps(apps) — sets the list returned by runningApplications()
• blockCount() — tracks how many times blockGlobalShortcuts() was called

Implements IInputInjector and records all calls:

• hasCalled(method) — check if a method was called (e.g., "injectKeystroke")
• lastArg(method) — get the last argument passed to a method
• calls() — full call log as QVector<Call> (method + arg pairs)
• clear() — reset call log

Implements ITransport with:

• setResponse(featureIndex, report) — set a canned response for a feature index
• simulateNotification(report) — emit notificationReceived signal
• simulateDisconnect() — emit deviceDisconnected signal
• sentRequests() — log of all sent requests

Implements IDevice with all fields as public member variables for direct manipulation. Used by AppRootFixture to supply a synthetic device to the controller under test; it is not used for device-descriptor tests (those load real JSON fixtures via DeviceRegistry).

A simpler fixture in tests/helpers/TestFixtures.h for profile-specific tests. Provides:

• QTemporaryDir for profile file I/O
• makeDefaultProfile() — returns a pre-populated Profile struct
• ensureApp() — creates a static QCoreApplication (required for Qt event loop)

Suppose you've added a new "DPI shift" button action that temporarily sets DPI to a low value while held. Here is how you would test it:

Since this involves AppRoot signal flow (button press -> action execution), use AppRootFixture:

// tests/test_dpi_shift.cpp
#include "helpers/AppRootFixture.h"

namespace logitune::test {

class DpiShiftTest : public AppRootFixture {};

TEST_F(DpiShiftTest, HoldDpiShiftLowersDpi) {
    // Set up: assign DPI shift to button 2 (middle click, CID 0x0052)
    setProfileButton("default", 2, {ButtonAction::DpiShift, "400"});

    // Simulate button press
    pressButton(0x0052);

    // Verify DPI was changed
    // (check DeviceModel or MockInjector depending on implementation)
    EXPECT_EQ(deviceModel().currentDPI(), 400);

    // Simulate button release
    releaseButton(0x0052);

    // Verify DPI restored
    EXPECT_EQ(deviceModel().currentDPI(), 1000);  // default profile DPI
}

TEST_F(DpiShiftTest, DpiShiftUsesHardwareProfile) {
    // DPI shift should use the hardware profile's DPI, not the display profile's
    createAppProfile("firefox", "Firefox", /*dpi=*/2000);
    focusApp("firefox");

    setProfileButton("Firefox", 2, {ButtonAction::DpiShift, "400"});
    pressButton(0x0052);
    EXPECT_EQ(deviceModel().currentDPI(), 400);

    releaseButton(0x0052);
    EXPECT_EQ(deviceModel().currentDPI(), 2000);
}

} // namespace logitune::test

# In tests/CMakeLists.txt
add_executable(logitune-tests
    # ... existing files ...
    test_dpi_shift.cpp
)

cmake --build build
QT_QPA_PLATFORM=offscreen ./build/tests/logitune-tests --gtest_filter="DpiShift*"

Device tests load a JSON fixture through DeviceRegistry; there is no per-device mock class to extend.

1. Drop a fixture at tests/fixtures/<slug>/descriptor.json (plus placeholder images if the test exercises image paths).

2. In your test, point XDG_DATA_HOME at the directory containing your fixture tree and construct a DeviceRegistry -- the constructor loads all devices it finds under the XDG paths automatically:

   QTemporaryDir tmp;
   qputenv("XDG_DATA_HOME", tmp.path().toUtf8());
   // copy your fixture into tmp.path() + "/logitune/devices/<slug>/"
   DeviceRegistry registry;
   const IDevice *dev = registry.findBySourcePath(
       tmp.path() + "/logitune/devices/<slug>");
   ASSERT_NE(dev, nullptr);

3. Use the parameterized DeviceSpec pattern in tests/test_device_registry.cpp for smoke-testing every bundled descriptor. Add your device to the kDevices array with its expected field values.

Hardware tests use HardwareFixture (tests/hw/HardwareFixture.h) which:

1. Creates a real DeviceManager with a real DeviceRegistry
2. Calls start() and waits for deviceSetupComplete signal (up to 10 seconds)
3. Records initial device state (DPI, SmartShift, thumb wheel) in SetUp
4. Restores initial state in TearDown

QML tests use Qt Quick Test (qml6-module-qttest). Each test file is a .qml file that creates the component under test and verifies its behavior.

QML tests run with QT_QPA_PLATFORM=offscreen. A common pattern wraps the component in an Item to provide a parent context:

import QtQuick
import QtTest
import Logitune

TestCase {
    name: "BatteryChipTest"
    when: windowShown

    Item {
        id: wrapper
        width: 200
        height: 50

        BatteryChip {
            id: chip
            level: 75
            charging: false
        }
    }

    function test_displayLevel() {
        compare(chip.level, 75)
    }

    function test_chargingState() {
        chip.charging = true
        // verify visual change
    }
}

Qt Quick Test's mouseClick requires the target item to be within a Window or have a valid parent. If mouseClick fails silently, wrap the component in an Item with explicit dimensions.

hooks/pre-push (auto-activated by cmake -B build via core.hooksPath) runs five stages before allowing a push:

graph LR
    Push[git push] --> Lint{README devices table<br/>matches descriptors?}
    Lint -->|No| Abort0[Abort: README regenerated,<br/>amend + retry]
    Lint -->|Yes| Build{Build OK?}
    Build -->|No| Abort1[Abort: build failed]
    Build -->|Yes| CPP{C++ tests pass?}
    CPP -->|No| Abort2[Abort: C++ tests failed]
    CPP -->|Yes| Tray{Tray tests pass?}
    Tray -->|No| Abort3[Abort: tray tests failed]
    Tray -->|Yes| QML{QML tests pass?}
    QML -->|No| Abort4[Abort: QML tests failed]
    QML -->|Yes| Py{Extractor pytest?}
    Py -->|No| Abort5[Abort: extractor pytest failed]
    Py -->|Yes| Push2[Push proceeds]

No install step needed — cmake -B build sets core.hooksPath=hooks in the repo's local git config during configure, so the tracked hooks/pre-push runs automatically on every git push.

The GitHub Actions CI workflow (.github/workflows/ci.yml) runs on every push to master and every pull request:

1. Install dependencies (Qt 6, GTest, libudev) on Ubuntu 24.04
2. Configure CMake with Ninja and BUILD_TESTING=ON
3. Build all targets
4. Run C++ tests (logitune-tests)
5. Run tray tests (logitune-tray-tests)
6. Run QML tests (logitune-qml-tests)

All tests run with QT_QPA_PLATFORM=offscreen (no display server required).

Catchable crashes (SIGSEGV, SIGABRT, SIGFPE, SIGBUS, and uncaught C++ exceptions) show the Crash Report dialog at the moment they happen, via CrashHandler installed during startup. The app does not show a recovery dialog on the next launch: uncatchable exits (SIGKILL, OOM, power loss, reboot) leave a lock file behind, but the user already knows those happened, so the lock is silently cleaned up.

When testing crash paths, expect the dialog to appear in the same session; do not test for a recovery-on-startup dialog.