bec_widgets/tests/unit_tests/test_tour_guide.py

"""Tests of the tour guide (short tours, progress, welcome, hints, What's this and both overlays)."""

# pylint: disable=redefined-outer-name,protected-access

import pytest
from qtpy.QtCore import QPoint, QRect, QSettings, QSize
from qtpy.QtWidgets import QLabel, QMainWindow, QPushButton, QVBoxLayout, QWidget

from bec_widgets.utils.tour_guide.geometry import interaction_region, place_card, target_rect
from bec_widgets.utils.tour_guide.guide import TourGuide, tour_ui_from_env
from bec_widgets.utils.tour_guide.model import Tour, TourProgress, TourStep


@pytest.fixture
def settings(tmp_path):
    return QSettings(str(tmp_path / "tours.ini"), QSettings.Format.IniFormat)


class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        central = QWidget()
        layout = QVBoxLayout(central)
        self.first = QPushButton("First")
        self.second = QPushButton("Second")
        self.hidden = QPushButton("Hidden")
        self.help = QPushButton("Help")
        for widget in (self.first, self.second, self.hidden, QLabel("text"), self.help):
            layout.addWidget(widget)
        self.hidden.hide()
        self.setCentralWidget(central)
        self.view = "main"


@pytest.fixture(params=["qwidget", "qml"])
def guide(request, qtbot, settings):
    window = Window()
    qtbot.addWidget(window)
    window.resize(900, 600)
    window.show()
    qtbot.waitExposed(window)
    switched = []

    def switch(view):
        switched.append(view)
        window.view = view

    guide = TourGuide(
        window,
        ui=request.param,
        settings=settings,
        view_switcher=switch,
        current_view=lambda: window.view,
    )
    guide.switched = switched
    guide.register_tour(
        Tour(
            id="basics",
            title="Basics",
            summary="The buttons.",
            order=0,
            steps=[
                TourStep("First", "The first button.", target=window.first, hint="Click it."),
                TourStep("Hidden", "Never visible.", target=window.hidden),
                TourStep("Second", "The second button.", target=lambda: window.second),
                TourStep("Overview", "No target, centred card."),
            ],
        )
    )
    guide.register_tour(
        Tour(
            id="other",
            title="Other view",
            summary="Lives in another view.",
            view="other",
            order=1,
            steps=[TourStep("Help", "The help button.", target=window.help, view="other")],
        )
    )
    guide.register_tour(
        Tour(
            id="unavailable",
            title="Never",
            summary="No available step.",
            steps=[TourStep("x", "y", target=window.first, available=lambda: False)],
        )
    )
    guide.set_help_anchor(window.help)
    yield guide
    guide.close()
    guide.cleanup()


def test_progress_store_round_trip(settings):
    progress = TourProgress(settings)
    assert progress.completed() == []
    assert progress.position("a") is None
    progress.save_position("a", 3)
    assert progress.position("a") == 3
    progress.mark_completed("a")
    assert progress.is_completed("a")
    assert progress.position("a") is None
    progress.welcome_dismissed = True
    progress.mark_offered("b")
    again = TourProgress(settings)
    assert again.welcome_dismissed
    assert again.offered() == ["b"]
    again.reset()
    assert not again.welcome_dismissed and again.completed() == []


def test_tours_hide_tours_without_available_steps(guide):
    assert [tour.id for tour in guide.tours()] == ["basics", "other"]


def test_tour_skips_invisible_steps_and_counts_correctly(guide):
    assert guide.start_tour("basics")
    state = guide.state()
    assert state["mode"] == "step"
    assert state["title"] == "First"
    assert state["hint"] == "Click it."
    assert state["count"] == 4
    assert state["spot"].contains(guide._window.first.geometry().center())
    guide.next_step()
    state = guide.state()
    assert state["title"] == "Second"  # the hidden button is skipped ...
    assert state["count"] == 3  # ... and no longer counted
    assert state["index"] == 1
    guide.next_step()
    assert guide.state()["spot"] is None
    guide.prev_step()
    assert guide.state()["title"] == "Second"


def test_close_keeps_position_and_resume_continues(guide):
    guide.start_tour("basics")
    guide.next_step()
    guide.close()
    assert guide.mode == "hidden"
    status = guide.tour_status(guide.tour("basics"))
    assert status["status"] == "in_progress"
    assert status["label"].startswith("Step 2")
    guide.resume_tour("basics")
    assert guide.current_index == 1


def test_finish_marks_done_and_suggests_next(guide):
    guide.start_tour("basics", 3)
    guide.next_step()
    assert guide.mode == "done"
    state = guide.state()
    assert state["finished"] == "Basics"
    assert state["next"]["id"] == "other"
    assert guide.tour_status(guide.tour("basics"))["status"] == "done"


def test_step_in_other_view_switches_view(guide):
    guide.start_tour("other")
    assert guide.switched == ["other"]
    assert guide.state()["title"] == "Help"


def test_welcome_is_shown_until_dismissed(guide, settings):
    assert guide.maybe_show_welcome()
    state = guide.state()
    assert state["mode"] == "welcome"
    assert [tour["id"] for tour in state["tours"]] == ["basics", "other"]
    assert state["anchor"] is not None
    guide._on_overlay_action("never", "")
    assert guide.mode == "hidden"
    assert TourProgress(settings).welcome_dismissed
    assert not guide.maybe_show_welcome()


def test_view_hint_is_offered_once(guide):
    guide.notify_view_entered("other")
    assert guide.mode == "hint"
    assert guide.state()["tour"]["id"] == "other"
    guide.close()
    guide.notify_view_entered("other")
    assert guide.mode == "hidden"


def test_hub_lists_status_and_actions_route(guide):
    guide.open_hub()
    state = guide.state()
    assert state["mode"] == "hub"
    assert state["done"] == 0 and state["total"] == 2
    guide._on_overlay_action("start", "basics")
    assert guide.is_active
    guide._on_overlay_action("hub", "")
    assert guide.mode == "hub"


def test_whats_this_collects_visible_documented_controls(guide):
    guide._window.view = "main"
    guide.toggle_whats_this()
    state = guide.state()
    titles = [anchor["title"] for anchor in state["anchors"]]
    assert titles == ["First", "Second"]  # hidden, other-view and target-less steps are left out
    guide.select_anchor(1)
    state = guide.state()
    assert state["selected"] == 1
    assert state["spot"] is not None
    guide.toggle_whats_this()
    assert guide.mode == "hidden"


def test_palette_and_welcome_hooks(guide):
    commands = guide.palette_commands()
    uids = [command["uid"] for command in commands]
    assert uids == ["tour:hub", "tour:whatsthis", "tour:basics", "tour:other"]
    commands[2]["callback"]()
    assert guide.is_active
    items = guide.welcome_items()
    assert items[0]["id"] == "basics" and items[0]["steps"] == 4
    guide.close()
    items[1]["start"]()
    assert guide.current_tour.id == "other"


def test_overlay_masks_let_the_app_work(guide, qtbot):
    window = guide._window
    guide.maybe_show_welcome()
    qtbot.wait(100)
    overlay = guide.overlay
    center = window.rect().center()
    # the welcome card only takes clicks on itself
    assert not overlay.mask().contains(QPoint(center.x(), 5))
    guide.start_tour("basics")
    qtbot.wait(100)
    spot = guide.state()["spot"]
    # the highlighted control stays clickable during a step, the rest is blocked
    assert not overlay.mask().contains(spot.center())
    assert overlay.mask().contains(QPoint(window.width() - 5, window.height() - 5))


def test_keyboard_shortcuts_only_while_blocking(guide):
    assert not any(shortcut.isEnabled() for shortcut in guide._shortcuts)
    guide.start_tour("basics")
    assert all(shortcut.isEnabled() for shortcut in guide._shortcuts)
    guide.close()
    guide.maybe_show_welcome()
    assert not any(shortcut.isEnabled() for shortcut in guide._shortcuts)


def test_place_card_avoids_spot():
    bounds = QRect(0, 0, 1000, 700)
    spot = QRect(10, 10, 100, 40)
    position, side = place_card(spot, QSize(300, 200), bounds)
    assert side == "right"
    assert not QRect(position, QSize(300, 200)).intersects(spot)
    position, side = place_card(QRect(850, 300, 140, 40), QSize(300, 200), bounds)
    assert side == "left"
    position, side = place_card(None, QSize(300, 200), bounds)
    assert side == "center" and abs(position.x() - 350) <= 1 and abs(position.y() - 250) <= 1


def test_interaction_region_modes():
    bounds = QRect(0, 0, 400, 300)
    spot = QRect(10, 10, 50, 50)
    card = QRect(100, 100, 100, 100)
    step = interaction_region("step", bounds, spot, [card])
    assert not step.contains(QPoint(20, 20)) and step.contains(QPoint(300, 250))
    welcome = interaction_region("welcome", bounds, None, [card])
    assert welcome.contains(QPoint(150, 150)) and not welcome.contains(QPoint(300, 250))
    assert not interaction_region("hint", bounds, None, []).isEmpty()


def test_target_rect_handles_hidden_and_callables(qtbot):
    window = Window()
    qtbot.addWidget(window)
    window.show()
    qtbot.waitExposed(window)
    assert target_rect(window.hidden, window) is None
    assert target_rect(lambda: (window.first, "text"), window) is not None
    assert target_rect(QRect(1, 1, 20, 20), window) == QRect(1, 1, 20, 20)


def test_tour_ui_from_env(monkeypatch):
    monkeypatch.delenv("BEC_TOUR_UI", raising=False)
    assert tour_ui_from_env() is None
    monkeypatch.setenv("BEC_TOUR_UI", "QML")
    assert tour_ui_from_env() == "qml"
    monkeypatch.setenv("BEC_TOUR_UI", "nope")
    assert tour_ui_from_env() is None


@pytest.mark.parametrize("ui", ["qwidget", "qml"])
def test_main_app_entry_points(qtbot, mocked_client, settings, ui):
    # pylint: disable=import-outside-toplevel
    from qtpy.QtWidgets import QMenu

    from bec_widgets.applications.main_app import BECMainApp

    app = BECMainApp(client=mocked_client, anim_duration=10)
    qtbot.addWidget(app)
    app._setup_tour_guide(ui, settings=settings, first_run=False)
    app.show()
    qtbot.waitExposed(app)
    guide = app.tour_guide
    assert {tour.id for tour in guide.tours()} >= {"first_steps", "workspace", "device_config"}
    assert "help" in app.sidebar.components
    help_menu = next(menu for menu in app.menuBar().findChildren(QMenu) if menu.title() == "Help")
    shortcuts = {action.text(): action.shortcut().toString() for action in help_menu.actions()}
    assert shortcuts["Tours…"] == "F1"
    assert shortcuts["What's This?"] == "Shift+F1"
    assert "Classic Guided Tour" in shortcuts
    app.sidebar.components["help"].activated.emit()
    assert guide.mode == "hub"
    assert guide.start_tour("workspace")
    assert guide.state()["spot"] is not None
    devices = next(tour for tour in guide.tours() if tour.id == "device_config")
    guide.start_tour(devices.id)
    assert app._current_view_id == devices.view
    guide.close()