ssokolow · ssokolow · Sep 7, 2025 · Sep 7, 2025 · Sep 7, 2025 · Sep 7, 2025
diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml
@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: awalsh128/cache-apt-pkgs-action@latest
         with:
-          packages: python3 python3-pip python3-setuptools python3-pytest python3-pytest-cov python3-gi python3-xlib python3-dbus gir1.2-glib-2.0 gir1.2-gtk-3.0 gir1.2-wnck-3.0
+          packages: python3 python3-pip python3-setuptools python3-pytest python3-pytest-cov python3-pytest-xvfb python3-gi python3-xlib python3-dbus xvfb openbox zenity gir1.2-glib-2.0 gir1.2-gtk-3.0 gir1.2-wnck-3.0
           version: 1.0
       - uses: actions/setup-python@v5
         with:
@@ -38,6 +38,6 @@ jobs:
           ruff check . --exit-zero --output-format=grouped
       - name: Test with PyTest
         run: |
-          pytest
+          python3 -m pytest
       - name: Coveralls
         uses: coverallsapp/github-action@v2
diff --git a/dev_requirements.txt b/dev_requirements.txt
@@ -1,6 +1,7 @@
 mypy
 pytest
 pytest-cov
+pytest-xvfb
 ruff
 sphinx
 sphinx-autodoc-typehints[type_comment]

diff --git a/docs/apidocs/functional_harness/env_general.rst b/docs/apidocs/functional_harness/env_general.rst
@@ -1,5 +1,5 @@
 Environment Management (``functional_harness/env_general.py``)
 ==============================================================
 
-.. automodule:: functional_harness.env_general
+.. automodule:: tests.functional_harness.env_general
    :members:
diff --git a/docs/apidocs/functional_harness/x_server.rst b/docs/apidocs/functional_harness/x_server.rst
diff --git a/docs/apidocs/test_functional.rst b/docs/apidocs/test_functional.rst
@@ -1,7 +1,7 @@
 Functional Tests (``test_functional.py``)
 =========================================
 
-.. automodule:: test_functional
+.. automodule:: tests.test_functional
    :members:
    :exclude-members: TEST_SCRIPT
 
@@ -10,4 +10,4 @@ Functional Tests (``test_functional.py``)
 Pending proper tests and assertions, the following sequence of commands is
 executed as an attempt to elicit uncaught exceptions.
 
-.. pprint:: test_functional.TEST_SCRIPT
+.. pprint:: tests.test_functional.TEST_SCRIPT
diff --git a/docs/apidocs/tests.rst b/docs/apidocs/tests.rst
@@ -11,5 +11,4 @@ rest of the code.
 
    test_util
    test_functional
-   functional_harness/x_server
    functional_harness/env_general
diff --git a/docs/developing.rst b/docs/developing.rst
@@ -31,6 +31,9 @@ On the operating system you intend to use for development:
 
 2. Install the :ref:`runtime dependencies <Dependencies>`.
 
+3. Install Xvfb, Openbox, and Zenity (eg. ``sudo apt install xvfb openbox
+   zenity``) for the functional tests.
+
 3. Either use the following command to install QuickTile's additional
    development-time dependencies, or manually install the dependencies listed
    therein:
@@ -41,8 +44,8 @@ On the operating system you intend to use for development:
 
    These dependencies fall into one of two categories:
 
-   * Source code verification (Flake8_ for static analysis and code style,
-     MyPy_ for checking type hints, Nose_ for test discovery, and
+   * Source code verification (Ruff_ for static analysis and code style,
+     MyPy_ for checking type hints, PyTest_ for test discovery, and
      `Coverage.py`_ for determining test coverage)
    * Documentation generation (Sphinx_, `sphinx-autodoc-typehints`_, and
      `sphinxcontrib-autoprogram`_)
@@ -90,9 +93,7 @@ be searched for by running the following command in the project root:
 
 .. code-block:: sh
 
-    grep -E 'XXX|TODO|FIXME' -nR *.py quicktile functional_harness
-
-PyLint_ should also report these.
+    grep -E 'XXX|TODO|FIXME' -nR *.py quicktile tests
 
 Regenerating Documentation Graphics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -175,10 +176,6 @@ Quirks of the Codebase's Structure
   commands and the shared setup code for them (lumped into a single class) as
   well as all of the commands themselves.
 
-* The :mod:`quicktile.version` module exists only to allow :file:`setup.py` and
-  the rest of QuickTile to share a single definition of the version number
-  without :file:`setup.py` having to import actual QuickTile code.
-
 .. todo:: Figure out a way to get URLs working in Sphinx's Graphviz_ extension
    that doesn't break when the default CSS downscales the diagram to keep it
    fitting in the document and then diagram QuickTile's functional
@@ -203,8 +200,8 @@ revise them:
 * All function arguments should bear complete type annotations which pass
   MyPy's scrutiny and use of :any:`typing.Any` or ``# type: ignore`` must be
   approved on a case-by-case basis.
-* All Flake8_ and PyLint_ complaints must either be resolved or whitelisted.
-  New ``NOQA`` or ``pylint: disable=`` annotations must include comments
+* All Ruff_ complaints must either be resolved or whitelisted.
+  New whitelisting annotations must include comments
   justifying their presence, except in self-evident cases such as URLs in
   docstrings which exceed the line-length limit.
 * All code within the ``quicktile`` package must have complete API
@@ -217,10 +214,10 @@ revise them:
   not be feasible until further refactoring and test harness work is
   completed.)
 
-Once your changes are ready, the recommended way to submit them is via
-`pull request`_, as this will automatically submit them to the various
-continuous testing services that run on the QuickTile repository, as well
-as making it as simple as possible for me to examine and accept them.
+Once your changes are ready, the standard way to submit them is via `pull
+request`_ against the ``master`` branch, as this will automatically trigger
+a test run, as well as making it as simple as possible for me to examine and
+accept them.
 
 .. _testing-quicktile:
 
@@ -230,7 +227,9 @@ Testing Your Changes
 Testing Environment Concerns
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-QuickTile's current minimum compatibility target is Kubuntu Linux 20.04 LTS.
+As of this writing, QuickTile's current minimum compatibility target is Kubuntu
+Linux 24.04 LTS. This may be broadened as the testing infrastructure is
+modernized.
 
 If this is not what you are running, I suggest using VirtualBox_ for
 compatibility testing, as it is easy to set up and has support for virtual
@@ -275,54 +274,22 @@ For best results, configure your virtual desktop with the following characterist
 Automated Testing
 ^^^^^^^^^^^^^^^^^
 
-To run a complete set of everything that can be completed quickly, please use
+To run a complete set of all tests, please use
 the following command from the root of the project:
 
 .. code-block:: sh
 
     ./run_tests.sh
 
-It will perform the majority of the tests which will be run by Travis-CI when
-you open a pull request, while still completing in under 5 seconds with a hot
-cache on an old 2-core Althon with no SSD.
-
 The following will be run:
 
 * MyPy_ to check for violations of the type annotations.
-* Flake8_ for basic static analysis and code style checking
-* Nose_ and doctest_ to run the unit tests (currently of limited scope)
+* Ruff_ for basic static analysis and code style checking
+* PyTest_ and doctest_ to run the unit tests (currently of limited scope)
 * doctest_ to check for broken code examples in the API documentation
 * Sphinx_'s ``make coverage`` to check documentation coverage
   (currently of questionable reliability)
 
-While the dependency on system packages such as PyGObject limits its utility,
-you may also use tox_ to test that QuickTile's ``setup.py`` packaging process
-works properly. (However, bear in mind that you will need to edit ``tox.ini``
-if your system Python is not version 3.8 as found on Kubuntu Linux 20.04 LTS.)
-
-Bear in mind that, while not yet incorporated into convenient scripts, the
-following tests will also be run by the ALE_ analysis plugin for my text editor
-when I examine your contribution:
-
-* Bandit_ (You can run this as ``bandit quicktile`` after installation.)
-* PyLint_ (Assuming you have your system configured to complain about
-  deprecation warnings as I do, I suggest running PyLint as
-  ``pylint3 --rcfile=pylintrc quicktile 2>/dev/null``)
-
-While it currently relies on an ugly hack which hard-codes Openbox and
-Zenity as dependencies, and does not yet assert that windows wind up
-in the expected states, you may also find the beginnings of a functional
-test suite useful as a way to exercise the code and check for uncaught
-exceptions:
-
-.. code-block:: sh
-
-    ./test_functional.py -v
-
-Bear in mind that, even once it is more mature, it will remain excluded
-from :file:`run_tests.sh` because it takes too long to be part of a
-comfortable edit-test cycle.
-
 In lieu of a proper functional test suite, please manually execute all tiling
 commands which rely on code you've touched and watch for misbehaviour.
 
@@ -381,17 +348,16 @@ A Bad Example::
 .. _Bandit: https://github.com/PyCQA/bandit
 .. _Coverage.py: https://coverage.readthedocs.io/
 .. _doctest: https://docs.python.org/3/library/doctest.html
-.. _Flake8: https://pypi.org/project/flake8/
+.. _Ruff: https://docs.astral.sh/ruff/
 .. _Gifsicle: https://www.lcdf.org/gifsicle/
 .. _GNU Make: https://www.gnu.org/software/make/
 .. _Graphviz: https://www.graphviz.org/
 .. _ImageMagick: https://imagemagick.org/
 .. _Inkscape: https://inkscape.org/
 .. _issue tracker: https://github.com/ssokolow/quicktile/issues
 .. _MyPy: http://mypy-lang.org/
-.. _Nose: https://nose.readthedocs.io/
+.. _PyTest: https://docs.pytest.org/
 .. _OptiPNG: http://optipng.sourceforge.net/
-.. _PyLint: https://www.pylint.org/
 .. _pull request: https://github.com/ssokolow/quicktile/pulls
 .. _simple past tense: https://en.wikipedia.org/wiki/Simple_past
 .. _Sphinx: https://www.sphinx-doc.org/

diff --git a/functional_harness/x_server.py b/functional_harness/x_server.py
diff --git a/quicktile/wm.py b/quicktile/wm.py
@@ -83,7 +83,7 @@ def __init__(self,
         self.gdk_display = self.gdk_screen.get_display()
 
         try:
-            self.x_display = x_display or XDisplay()
+            self.x_display = x_display or XDisplay(self.gdk_display.get_name())
         except (UnicodeDecodeError, DisplayConnectionError) as err:
             raise XInitError("python-xlib failed with %s when asked to open"
                              " a connection to the X server. Cannot bind keys."

diff --git a/run_tests.sh b/run_tests.sh
@@ -1,14 +1,16 @@
 #!/bin/bash
 
 cd -- "$(dirname -- "$(readlink -f -- "$0")")" || exit 1
-echo "--== Sphinx (documentation syntax) ==--"
-cd docs || exit 1
-make -s SPHINXOPTS=-q coverage | grep -v '+--------------------------------+----------+--------------+'
-echo "--== Sphinx (doctests) ==--"
-make -s doctest
+(
+    echo "--== Sphinx (documentation syntax) ==--"
+    cd docs || exit 1
+    make -s SPHINXOPTS=-q coverage | grep -v '+--------------------------------+----------+--------------+'
+    echo "--== Sphinx (doctests) ==--"
+    make -s doctest
+)
 echo "--== MyPy ==--"
 mypy --exclude=build --warn-unused-ignores .
 echo " --== Ruff (static analysis) ==--"
 ruff check .
 echo "--== PyTest (unit tests) ==--"
-pytest "$@"
+python3 -m pytest "$@"