Add support of the QT_API env. var.

CHANGELOG.rst

@@ -1,6 +1,7 @@
 UNRELEASED
 ----------
 
+- Added support for QT_API environment variable.
 - Added official support for Python 3.14.
 - Python 3.15 is now tested in CI.
 

docs/intro.rst

@@ -91,6 +91,6 @@ To force a particular API, set the configuration variable ``qt_api`` in your ``p
     qt_api=pyqt5
 
 
-Alternatively, you can set the ``PYTEST_QT_API`` environment
-variable to the same values described above (the environment variable wins over the configuration
+Alternatively, you can set one of the ``PYTEST_QT_API`` or ``QT_API`` environment
+variables to the same values described above (the environment variable wins over the configuration
 if both are set).

src/pytestqt/qt_compat.py

@@ -44,14 +44,14 @@ class _QtApi:
     def __init__(self):
         self._import_errors = {}
 
-    def _get_qt_api_from_env(self):
-        api = os.environ.get("PYTEST_QT_API")
+    def _get_qt_api_from_env(self, variable_name):
+        api = os.environ.get(variable_name)
         supported_apis = QT_APIS.keys()
 
         if api is not None:
             api = api.lower()
             if api not in supported_apis:  # pragma: no cover
-                msg = f"Invalid value for $PYTEST_QT_API: {api}, expected one of {supported_apis}"
+                msg = f"Invalid value for ${variable_name}: {api}, expected one of {supported_apis}"
                 raise pytest.UsageError(msg)
         return api
 
@@ -79,7 +79,8 @@ def _can_import(name):
 
     def set_qt_api(self, api):
         self.pytest_qt_api = (
-            self._get_qt_api_from_env()
+            self._get_qt_api_from_env("PYTEST_QT_API")
+            or self._get_qt_api_from_env("QT_API")
             or api
             or self._get_already_loaded_backend()
             or self._guess_qt_api()

tests/test_basics.py

@@ -423,6 +423,7 @@ def test_qt_api_ini_config(pytester, monkeypatch, option_api):
     from pytestqt.qt_compat import qt_api
 
     monkeypatch.delenv("PYTEST_QT_API", raising=False)
+    monkeypatch.delenv("QT_API", raising=False)
 
     pytester.makeini(
         """
@@ -453,7 +454,8 @@ def test_foo(qtbot):
 
 
 @pytest.mark.parametrize("envvar", ["pyqt5", "pyqt6", "pyside6"])
-def test_qt_api_ini_config_with_envvar(pytester, monkeypatch, envvar):
+@pytest.mark.parametrize("envvar_name", ["PYTEST_QT_API", "QT_API"])
+def test_qt_api_ini_config_with_envvar(pytester, monkeypatch, envvar, envvar_name):
     """ensure environment variable wins over config value if both are present"""
     pytester.makeini(
         """
@@ -462,7 +464,9 @@ def test_qt_api_ini_config_with_envvar(pytester, monkeypatch, envvar):
     """.format(option_api="piecute")
     )
 
-    monkeypatch.setenv("PYTEST_QT_API", envvar)
+    monkeypatch.delenv("PYTEST_QT_API", raising=False)
+    monkeypatch.delenv("QT_API", raising=False)
+    monkeypatch.setenv(envvar_name, envvar)
 
     pytester.makepyfile("""
         import pytest
@@ -485,7 +489,8 @@ def test_foo(qtbot):
             result.stderr.fnmatch_lines(["*ModuleNotFoundError:*"])
 
 
-def test_invalid_qt_api_envvar(pytester, monkeypatch):
+@pytest.mark.parametrize("envvar_name", ["PYTEST_QT_API", "QT_API"])
+def test_invalid_qt_api_envvar(pytester, monkeypatch, envvar_name):
     """
     Make sure the error message with an invalid PYQTEST_QT_API is correct.
     """
@@ -495,10 +500,12 @@ def test_invalid_qt_api_envvar(pytester, monkeypatch):
         def test_foo(qtbot):
             pass
     """)
-    monkeypatch.setenv("PYTEST_QT_API", "piecute")
+    monkeypatch.delenv("PYTEST_QT_API", raising=False)
+    monkeypatch.delenv("QT_API", raising=False)
+    monkeypatch.setenv(envvar_name, "piecute")
     result = pytester.runpytest_subprocess()
     result.stderr.fnmatch_lines(
-        ["* Invalid value for $PYTEST_QT_API: piecute, expected one of *"]
+        [f"* Invalid value for ${envvar_name}: piecute, expected one of *"]
     )
 
 
@@ -543,6 +550,7 @@ def _fake_is_library_loaded(name, *args):
         return False
 
     monkeypatch.delenv("PYTEST_QT_API", raising=False)
+    monkeypatch.delenv("QT_API", raising=False)
     monkeypatch.setattr(qt_compat, "_import", _fake_import)
     monkeypatch.setattr(qt_compat, "_is_library_loaded", _fake_is_library_loaded)
 
@@ -614,6 +622,7 @@ def _fake_is_library_loaded(name, *args):
         return name == backend
 
     monkeypatch.delenv("PYTEST_QT_API", raising=False)
+    monkeypatch.delenv("QT_API", raising=False)
     monkeypatch.setattr(qt_compat, "_is_library_loaded", _fake_is_library_loaded)
     monkeypatch.setattr(builtins, "__import__", _fake_import)