PyQGIS Engineering & Automation

Mocking the QGIS iface Object in Unit Tests

Unit-test plugin code that depends on the QGIS iface without a running desktop — use pytest-qgis's mock iface or unittest.mock to stub messageBar, mapCanvas,…

TL;DR: The QgisInterface (iface) only exists inside QGIS Desktop, so it is None in a headless test runner. Either request pytest-qgis’s qgis_iface fixture for a faithful stand-in, or wrap iface behind a thin adapter and inject a unittest.mock.MagicMock, then assert on interactions such as mock.messageBar.return_value.pushMessage.assert_called_once() and addVectorLayer(...).

This page is part of the Testing PyQGIS with pytest-qgis guide, which sits inside the broader Headless Automation, CI/CD & Testing for PyQGIS reference. If you have not yet written a test, start with writing your first pytest-qgis test and return here when you need to exercise UI-touching code.

The problem in one sentence

The single global object iface — an instance of QgisInterface — is injected into your plugin’s __init__ by the QGIS Desktop application at load time. In a pytest process there is no desktop, so nothing injects it. Any plugin method that reaches for iface.messageBar(), iface.mapCanvas(), or iface.addVectorLayer() will raise AttributeError: 'NoneType' object has no attribute ... the moment it runs under test. Mocking iface is how you break that dependency.

Complete Runnable Example

The example below is a self-contained drop-in. It defines a small plugin action that loads a layer and reports the result on the message bar, then tests it two ways: once with the qgis_iface fixture from pytest-qgis, and once with a bare MagicMock. The class accepts iface through its constructor — that dependency injection is what makes both tests possible.

python
"""
layer_loader.py

A minimal plugin component that depends on the QGIS interface but
receives it via the constructor, so it can be unit-tested without a
running QGIS Desktop. Compatible with QGIS 3.28+ / Python 3.9+.
"""
from __future__ import annotations

from qgis.core import Qgis, QgsVectorLayer
from qgis.gui import QgisInterface


class LayerLoader:
    """Load a vector layer and report the outcome on the message bar.

    Args:
        iface: The QGIS interface. In production this is the global
            ``iface`` handed to the plugin; in tests it is a stub.
    """

    def __init__(self, iface: QgisInterface) -> None:
        self._iface = iface

    def load(self, path: str, name: str) -> QgsVectorLayer | None:
        """Load an OGR vector layer and add it to the canvas.

        Returns the layer on success, ``None`` on failure. Either way,
        a message is pushed to the message bar for the user.
        """
        layer = QgsVectorLayer(path, name, "ogr")
        if not layer.isValid():
            self._iface.messageBar().pushMessage(
                "Error", f"Could not load {name}", level=Qgis.Critical
            )
            return None

        self._iface.addVectorLayer(path, name, "ogr")
        self._iface.messageBar().pushMessage(
            "Success", f"Loaded {name}", level=Qgis.Success
        )
        return layer
python
"""
test_layer_loader.py

Two strategies for supplying iface to LayerLoader under test:
  1. The pytest-qgis ``qgis_iface`` fixture (faithful stand-in).
  2. A unittest.mock.MagicMock (pure interaction assertions).
"""
from __future__ import annotations

from unittest.mock import MagicMock

from layer_loader import LayerLoader


def test_load_invalid_layer_with_qgis_iface(qgis_iface) -> None:
    """The bundled mock iface accepts calls without a live desktop."""
    loader = LayerLoader(qgis_iface)

    # A bogus path yields an invalid layer, so load() returns None.
    result = loader.load("/does/not/exist.shp", "ghost")

    assert result is None
    # qgis_iface records pushed messages; inspect the last one.
    title, text, level = qgis_iface.messageBar().get_text()[-1][:3]
    assert title == "Error"


def test_load_invalid_layer_with_magicmock() -> None:
    """A MagicMock records every attribute access and call for free."""
    mock_iface = MagicMock()
    loader = LayerLoader(mock_iface)

    result = loader.load("/does/not/exist.shp", "ghost")

    assert result is None
    # messageBar() returns a child mock; pushMessage was called once.
    mock_iface.messageBar.return_value.pushMessage.assert_called_once()
    # An invalid layer must NOT be added to the canvas.
    mock_iface.addVectorLayer.assert_not_called()


def test_message_arguments_with_magicmock() -> None:
    """Assert on the exact arguments passed through the interface."""
    mock_iface = MagicMock()
    loader = LayerLoader(mock_iface)

    loader.load("/does/not/exist.shp", "parcels")

    push = mock_iface.messageBar.return_value.pushMessage
    args, kwargs = push.call_args
    assert args[0] == "Error"
    assert "parcels" in args[1]

How iface and its stand-ins fit together

The diagram shows the seam that makes all of this testable: the plugin never talks to iface through a global import; it holds whatever object was passed into its constructor. Production wires up the real QgisInterface; tests wire up a fixture or a mock.

Plugin to iface dependency injection seam A plugin class holds an injected iface reference. At runtime that reference is the real QgisInterface from QGIS Desktop; under test it is the pytest-qgis qgis_iface fixture or a unittest.mock MagicMock. Plugin class holds self._iface injected iface adapter QgisInterface API Real QgisInterface QGIS Desktop qgis_iface fixture pytest-qgis stub MagicMock records calls

Architecture Breakdown

What QgisInterface provides and why it is unavailable headlessly

QgisInterface, exposed to plugins as the global iface, is the plugin author’s gateway to the running application. Through it you reach live GUI singletons: iface.messageBar() for transient notifications, iface.mapCanvas() for the current view and its extent, iface.activeLayer() for the selected layer, iface.layerTreeView() for the legend, and helpers such as iface.addVectorLayer() that both load and register a layer in one call. Every one of these returns a Qt widget or a live QGIS object that only exists once QgisApp has constructed its main window.

That is precisely why iface is unavailable headlessly. A pytest process starts a QgsApplication (which pytest-qgis does for you) but it never constructs the desktop main window, so there is no message bar and no map canvas to hand out. The global iface symbol in qgis.utils is simply None. Code that imports it at module scope — from qgis.utils import iface — captures that None and fails later, far from the import. The fix is structural, not incidental: stop depending on the global.

Dependency injection of iface for testability

The single most valuable change you can make is to accept iface as a constructor argument rather than importing it. This mirrors the discipline covered in plugin lifecycle and resource management: the plugin’s top-level class already receives iface from QGIS in its __init__, so pass that same reference down into every collaborator you create instead of letting each one reach for the global.

python
class MyPlugin:
    """Top-level plugin object; QGIS passes iface here at load time."""

    def __init__(self, iface):
        self.iface = iface

    def initGui(self) -> None:
        # Inject the SAME iface into collaborators — never import the global.
        self._loader = LayerLoader(self.iface)

With this shape, production hands over the real interface and tests hand over a substitute. The class under test cannot tell the difference, because it only ever touches the object it was given. Injection also documents the surface area of QgisInterface your code actually uses, which keeps the eventual mock small and honest.

The qgis_iface fixture vs MagicMock trade-offs

pytest-qgis ships a qgis_iface fixture — a lightweight but behaviour-bearing implementation of the interface. It maintains real-ish state: pushed messages are stored and retrievable with messageBar().get_text(), added layers are tracked, and the active layer can be set and read back. Reach for it when your test asserts on outcomes that depend on the interface behaving like the real thing, and when you would rather not hand-wire the return value of every call.

A unittest.mock.MagicMock takes the opposite stance: it has no behaviour at all. Every attribute access lazily produces another mock, and every call is recorded. That makes it ideal for interaction assertions — “did we push exactly one message?”, “were we careful not to add an invalid layer?” — using assert_called_once(), assert_called_with(...), and call_args. The cost is that it will happily accept nonsense: mock_iface.mesageBar() (a typo) returns a mock too, so a MagicMock cannot catch API misuse the way the fixture’s real method signatures can. As a rule: use qgis_iface when you care what the interface does, and a MagicMock when you care what your code asks it to do.

Registering the injected iface in the real plugin

The wiring that connects test-time injection to run-time reality lives in the QGIS-called __init__. QGIS constructs your plugin’s entry class with the live interface, and from there you thread it through. Nothing about the mock leaks into production:

python
def classFactory(iface):
    """QGIS plugin entry point. QGIS supplies the real iface here."""
    from .plugin import MyPlugin
    return MyPlugin(iface)

Because classFactory is the only place the real iface enters your package, it is also the only place you ever need the desktop. Everything downstream is plain Python that a test can construct with a stub.

Production Best Practices

  • Never from qgis.utils import iface at module scope in testable code. Accept it as a constructor argument so a test can substitute it.
  • Type-hint the parameter as QgisInterface (from qgis.gui). It documents intent and lets static analysis flag misuse, even though the runtime object may be a mock.
  • Prefer qgis_iface for outcome tests, MagicMock for interaction tests. Mixing them in one suite is fine and often ideal.
  • Assert on arguments, not just call counts. call_args catches a wrong message level or a swapped layer name that assert_called_once() would miss.
  • Reset or recreate mocks per test. A fresh MagicMock() in each test (or mock.reset_mock()) prevents call history bleeding across cases; the qgis_iface fixture is function-scoped by default and resets automatically.
  • Keep the mocked surface minimal. If a class touches ten iface methods, that is a signal to split it; a small interface footprint is both easier to test and easier to reason about.
  • Do not mock what you can run. Pure geometry or data logic needs no interface at all — reserve iface mocking for the thin UI-facing seam.