Skip to content

Instantly share code, notes, and snippets.

@Elliria

Elliria/test_or_build_or_try_out_autokey.md

Last active June 24, 2026 20:59
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Elliria/f738069e2f1b7a6fd9bb3ad3fd57fc72 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Elliria/f738069e2f1b7a6fd9bb3ad3fd57fc72 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
test_or_build_or_try_out_autokey.md

Test or build or try out AutoKey

🔴🟡🟢 This is a work-in-progress that's currently rather chaotic. Follow along only if you dare. 🟢🟡🔴

Table of Contents

About

This document provides the steps you can take to build, test, and try out AutoKey in a virtual machine. Each section's steps are done in a fresh Ubuntu virtual machine and finish with a final step to destroy the virtual machine. This type of isolation keeps the state of the machine as a known constant. Note that for those who are new to virtual machines, there's a guide for installing VirtualBox and another for using VirtualBox.

Some of the steps install packages or edit existing AutoKey files. Some of those tweaks may need to become a permanent part of AutoKey, so they're marked with highlights for review. Maybe the whole thing should be self-contained so that there's no need to install or change anything in order to run tests or do builds...

Caution: All copies of AutoKey, whether installed from your operating system's repositories or cloned or downloaded, share the same configuration files on your system. As a result, it's not recommended to do these tests on a production machine! If you'd like to do so anyway, you should back up your AutoKey configuration directory first so you can restore it afterwards if needed.

Goal

The goal is to run AutoKey through its paces in the Ubuntu and Python environments currently supported by GitHub. The GitHub Runners page lists the supported Ubuntu releases in its Image column. Each image's Included software column opens its page that lists the supported Python versions in the Python section at the bottom. Note that the Ubuntu Slim runner can be disregarded since it's exclusively for GitHub's use. Also, similar testing done on Arch, Debian, Fedora, Gentoo, Ubuntu derivatives, etc., is always welcome.

This document will have achieved its goal only when each of these items has a check-mark next to it:

  • A build of an AutoKey clone without errors or warnings:
    • Ubuntu 22.04 under Wayland
    • Ubuntu 22.04 under Xorg
    • ✔ Ubuntu 24.04 under Wayland
    • Ubuntu 24.04 under Xorg
  • An installation from that local build without errors:
    • Ubuntu 22.04 under Wayland
    • Ubuntu 22.04 under Xorg
    • Ubuntu 24.04 under Wayland
    • Ubuntu 24.04 under Xorg
  • A trial-run of that installation with a (mostly) functioning interface:
    • Ubuntu 22.04 under Wayland
    • Ubuntu 22.04 under Xorg
    • Ubuntu 24.04 under Wayland
    • Ubuntu 24.04 under Xorg
  • All pytest tests passing:
    • Ubuntu 22.04 under Wayland
    • Ubuntu 22.04 under Xorg
    • Ubuntu 24.04 under Wayland
    • Ubuntu 24.04 under Xorg
  • All tox tests passing:
    • Ubuntu 22.04 under Wayland
    • Ubuntu 22.04 under Xorg
    • Ubuntu 24.04 under Wayland
    • Ubuntu 24.04 under Xorg
  • A trial-run of an AutoKey clone without installing it with a (mostly) functional interface:
    • Ubuntu 22.04 under Wayland
    • Ubuntu 22.04 under Xorg
    • Ubuntu 24.04 under Wayland
    • Ubuntu 24.04 under Xorg

Xorg

Xorg - Build AutoKey

🔴🟡🟢 TODO 🟢🟡🔴

Xorg - Test AutoKey - pytest

With the following steps, you can clone AutoKey and use pytest to run unit-tests on the raw source code without installing AutoKey:

  1. Create a fresh Ubuntu virtual machine.
  2. Boot the virtual machine.
  3. Log in to a Xorg session.
  4. Update the operating system: 
    sudo apt update
  5. Install the core tools (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      sudo apt install -y git python3-pip python3-setuptools python3-tk python3-venv xvfb
    • If you're using Ubuntu 24.04 LTS: 
      sudo apt install -y git python3-build python3-pip python3-pyasyncore python3-setuptools python3-tk python3-venv xvfb
  6. Create the ~/clones directory: 
    mkdir -p ~/clones
  7. Change to the clones directory: 
    cd clones
  8. Clone AutoKey (pick one):
    • Clone a pull request, replacing 123 with the pull request number: 
      PR=123; git clone https://github.com/autokey/autokey.git && (cd autokey && git fetch origin pull/$PR/head:pull_$PR && git checkout pull_$PR)
    • Clone the current release: 
      git clone https://github.com/autokey/autokey.git
    • Clone the develop branch: 
      git clone --branch develop --single-branch https://github.com/autokey/autokey.git
  9. Change to the autokey sub-directory: 
    cd autokey
  10. Edit the wayland_checks.py file to prevent the error about f-strings not being allowed to contain a backslashes (pick one):
    • If you're using Ubuntu 22.04 LTS:
      1. Open the lib/autokey/wayland_checks.py file in a text editor.
      2. Replace this block at the bottom of the file: 
        # Show popup using kdialog, if it's installed, or zenity, otherwise write the
# message to autokey.log
def __show_popup(title, message):
        try:
            subprocess.run(f"kdialog --error '{message}' --title '{title}'", shell=True, check=True)
        except Exception:
            try:

                subprocess.run(f"zenity --error --title='{title}' --text='{message.replace('<br />', '\n')}'", shell=True, check=True)
            except Exception:
                logger.critical(message)

# For testing purposes
if __name__ == '__main__':
    if not waylandChecks():
        print('waylandChecks() returned False')
        with this block: 
        # Show popup using kdialog, if it's installed, or zenity, otherwise write the
# message to autokey.log
def __show_popup(title, message):
    try:
        subprocess.run(f"kdialog --error '{message}' --title '{title}'", shell=True, check=True)
    except Exception:
        try:
            # Fix: Move the replace call out of the f-string for Python 3.10 compatibility
            clean_message = message.replace('<br />', '\n')
            subprocess.run(f"zenity --error --title='{title}' --text='{clean_message}'", shell=True, check=True)
        except Exception:
            logger.critical(message)

#  For testing purposes
if __name__ == '__main__':
    if not waylandChecks():
        print('waylandChecks() returned False')
    • If you're using Ubuntu 24.04 LTS:
      • Skip this step since it's a Python 3.10 fix that's no longer needed and would break the unit tests in Ubuntu 24.04 LTS.
  11. Install and activate a Python virtual environment to prevent modules needed by AutoKey from being installed to your system:
    1. Create a new virtual environment that has access to your global system packages: 
      python3 -m venv --system-site-packages .venv
    2. Activate the virtual environment (note that your prompt will change to let you know you're in a virtual environment): 
      source .venv/bin/activate
  12. Install AutoKey's apt dependencies: 
    sudo apt install -y $(cat apt-requirements.txt)
  13. Update some testing tools (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      python3 -m pip install --upgrade pip setuptools wheel
    • If you're using Ubuntu 24.04 LTS:
      • Skip this step.
  14. Install AutoKey's pip dependencies (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      python3 -m pip install -r pip-requirements.txt
    • If you're using Ubuntu 24.04 LTS: 
      python3 -m pip install -r pip-requirements.txt --break-system-packages
  15. Install the necessary testing utilities in the virtual environment (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      python3 -m pip install build pyhamcrest pyasyncore pytest pytest-cov pytest-xdist
    • If you're using Ubuntu 24.04 LTS: 
      python3 -m pip install pytest pytest-cov pytest-xdist --break-system-packages
  16. Create the pytest.ini file for additional coverage configuration: 
    echo -e "[pytest]\\naddopts = --cov=lib/autokey\\npythonpath = lib" > pytest.ini
  17. Run the unit tests with the coverage option to see which parts of the code were executed for the tests: 
    xvfb-run -a .venv/bin/python -m pytest --cov=lib/autokey tests -k "not interface and not service"
    Or run the same command and create a log-file: 
    xvfb-run -a .venv/bin/python -m pytest --cov=lib/autokey tests -k "not interface and not service" 2>&1 | tee test_results.log
  18. If you made changes to these steps and took notes, copy your notes out of the virtual machine.
  19. If you created logs that you'd like to reference or share later, copy those logs out of the virtual machine.
  20. Destroy the virtual machine.

Xorg - Test AutoKey - tox

With the following steps, you can clone AutoKey and use tox to run compatibility tests against multiple Python versions if available without installing AutoKey:

🔴🟡🟢 TODO 🟢🟡🔴

Xorg - Try out AutoKey - no install

With the following steps, you can clone AutoKey and try it out from a temporary directory on your computer without installing it:

  1. Create a fresh Ubuntu virtual machine.
  2. Boot the virtual machine.
  3. Log in to a Xorg session.
  4. Update the operating system: 
    sudo apt update
  5. Install the core tools: 
    sudo apt install -y git python3-pip
  6. Clone AutoKey (pick one):
    • Clone a pull request, replacing 123 with the pull request number: 
      PR=123; git clone https://github.com/autokey/autokey.git && (cd autokey && git fetch origin pull/$PR/head:pull_$PR && git checkout pull_$PR)
    • Clone the current release: 
      git clone https://github.com/autokey/autokey.git
    • Clone the develop branch: 
      git clone --branch develop --single-branch https://github.com/autokey/autokey.git
  7. Change to the autokey sub-directory that you created in step 6: 
    cd autokey
  8. Install AutoKey's apt dependencies: 
    sudo apt install -y $(cat apt-requirements.txt)
  9. Install AutoKey's pip dependencies: 
    python3 -m pip install -r pip-requirements.txt
  10. Try out both AutoKey interfaces by repeating these steps with each interface:
    1. Change to the /lib directory: 
      cd lib
    2. Run AutoKey with its configuration open and in verbose mode (pick one):
      • GTK:
        • If you cloned the current release: 
          python3 -m autokey.gtkui -cl
        • If you cloned the develop branch or a pull request: 
          python3 -m autokey.gtkui -cv
      • Qt:
        • If you cloned the current release: 
          python3 -m autokey.qtui -cl
        • If you cloned the develop branch or a pull request: 
          python3 -m autokey.qtui -cv
    3. Try out AutoKey's features:
      1. If you're using Wayland in the Gnome desktop environment, Assistive Technologies must be enabled in the Gnome settings.
      2. Try out AutoKey's basic features:
        • Check the terminal window for traceback errors.
        • Use all of AutoKey's menu entries.
        • Go into all of AutoKey's settings to make sure they're accessible and work and that the version is correctly listed.
        • Run all of AutoKey's default phrases and scripts from the "play" button in the AutoKey interface.
        • Run all of AutoKey's default phrases and scripts from a hotkey.
        • Run all of AutoKey's default phrases and scripts from an abbreviation.
        • Change each of the settings on a phrase and try each of them out.
        • Create and try out a new phrase.
        • Create and try out a new script.
  11. If you made changes to these steps and took notes, copy your notes out of the virtual machine.
  12. If you created logs that you'd like to reference or share later, copy those logs out of the virtual machine.
  13. Destroy the virtual machine.

Wayland

Wayland - Build AutoKey

With the following steps, you can clone AutoKey and build it without testing or installing it:

  1. Create a fresh Ubuntu virtual machine.

  2. Boot the virtual machine.

  3. Log in to a Wayland session.

  4. Update the operating system:

    sudo apt update

  5. Install the core tools (pick one):

    • If you're using Ubuntu 22.04 LTS: 
      sudo apt install -y git python3-pip python3-setuptools python3-venv zip
    • If you're using Ubuntu 24.04 LTS: 
      sudo apt install -y git python3-build python3-pip python3-setuptools python3-venv zip

  6. Create the clones directory:

    mkdir -p ~/clones

  7. Change to the clones directory:

    cd clones

  8. Clone AutoKey (pick one):

    • Clone a pull request, replacing 123 with the pull request number: 
      PR=123; git clone https://github.com/autokey/autokey.git && (cd autokey && git fetch origin pull/$PR/head:pull_$PR && git checkout pull_$PR)
    • Clone the current release: 
      git clone https://github.com/autokey/autokey.git
    • Clone the develop branch: 
      git clone --branch develop --single-branch https://github.com/autokey/autokey.git

  9. Change to the autokey sub-directory:

    cd autokey

  10. Download the PKG-INFO file from the master branch of AutoKey and put it into the ~/clones/autokey directory.

  11. Replace the apt-requirements.txt file's contents with these contents.

  12. Replace the PKG-INFO file's contents with these contents.

  13. Replace the setup.py file's contents with these contents.

  14. Replace the debian/autokey-common.install file's contents with these contents.

  15. Replace the debian/autokey-common.postinst file's contents with these contents.

  16. Replace the debian/autokey-common.prerm file's contents with these contents.

  17. Replace the debian/build_requirements.txt file's contents with these contents.

  18. Replace the debian/control file's contents with these contents.

  19. Replace the debian/rules file's contents with these contents.

  20. Create the debian/autokey-common.manpages file:

    echo "doc/man/autokey-run.1" > debian/autokey-common.manpages

  21. Create the debian/autokey-gtk.manpages file:

    echo "doc/man/autokey-gtk.1" > debian/autokey-gtk.manpages

  22. Create the debian/autokey-qt.manpages file:

    echo "doc/man/autokey-qt.1" > debian/autokey-qt.manpages

  23. Create the debian/not-installed file:

    echo -e "usr/lib/python3*/dist-packages/autokey/__pycache__/\nusr/lib/python3*/dist-packages/autokey/*/__pycache__/" > debian/not-installed

  24. Create the missing autokey-headless and autokey-shell man pages and add them the same way as the others were added above:

    • 🔴🟡🟢 TODO BEFORE RELEASE -- This doesn't need to be done for the build, but does need to be done before the release. Until it's done, the build will give you a no-manual-page warning for autokey-headless and autokey-shell that you can safely ignore since you're aware that those files are missing and will be added. 🟢🟡🔴
      1. Create the doc/man/autokey-headless.1 man page file.
      2. Create the doc/man/autokey-shell.1 man page file.
      3. Write the doc/man/autokey-headless.1 man page.
      4. Write the doc/man/autokey-shell.1 man page.
      5. Add the doc/man/autokey-headless.1 path to the debian/autokey-common.manpages file.
      6. Add the doc/man/autokey-shell.1 path to the debian/autokey-common.manpages file.

  25. Figure out what, exactly, to update in the lib/autokey/configmanager/version_upgrading.py file. 🔴🟡🟢 TODO: This is critical! 🟢🟡🔴

  26. Install and activate a Python virtual environment to prevent modules needed by AutoKey from being installed to your system:

    1. Create a new virtual environment that has access to your global system packages: 
      python3 -m venv --system-site-packages .venv
    2. Activate the virtual environment (note that your prompt will change to let you know you're in a virtual environment): 
      source .venv/bin/activate

  27. Install AutoKey's apt dependencies:

    sudo apt install -y $(cat apt-requirements.txt)

  28. Install AutoKey's build dependencies:

    sudo apt install -y $(cat debian/build_requirements.txt)

  29. Install AutoKey's pip dependencies:

    python3 -m pip install -r pip-requirements.txt

  30. Install the AutoKey Gnome Extension:

    1. Change to the autokey-gnome-extension subdirectory: 
      cd ~/clones/autokey/autokey-gnome-extension
    2. Set up the extension: 
      make
    3. Install the extension: 
      gnome-extensions install autokey-gnome-extension@autokey.zip
    4. Configure your system to allow members of the input user group to use virtual keyboards and mice: 
      sudo cp ~/clones/autokey/config/10-autokey.rules /etc/udev/rules.d/
    5. Add your user account to the input group: 
      sudo usermod -a -G input $(id -un)
    6. Apply the changes by rebooting: 
      sudo reboot
    7. Log back in to a Wayland session.
    8. Turn on the AutoKey Gnome extension: 
      gnome-extensions enable autokey-gnome-extension@autokey
    9. Rename the AutoKey Gnome Extension that you just created so that it's accepted by the build process: 🔴🟡🟢 Figure out how to sort out this conflict so that this hack isn't necessary. 🟢🟡🔴 
      mv ~/clones/autokey/autokey-gnome-extension/autokey-gnome-extension@autokey.zip ~/clones/autokey/autokey-gnome-extension/autokey-gnome-extension@autokey.shell-extension.zip

  31. Change to the autokey directory:

    cd ~/clones/autokey

  32. Make the debian/*.prerm scripts executable:

    chmod +x debian/rules debian/*.prerm

  33. Make the debian/rules script executable:

    chmod +x debian/rules

  34. Make the debian/build.sh script executable:

    chmod +x debian/build.sh

  35. Make the /dev/uinput file executable:

    sudo chmod 0666 /dev/uinput

  36. Build AutoKey (pick one):

    • Run the build command to generate unsigned build files in the parent (clones) directory: 
      debuild -us -uc -b
      🔴🟡🟢 You'll see a maintainer-script-ignores-errors warning that's a minor technicality in how the installer cleans up after itself. You'll also see two no-manual-page warnings that refer to the missing autokey-headless and autokey-shell man pages that are mentioned earlier in these steps as a TODO that will be taken care of before the next release. All three warnings can safely be ignored. 🟢🟡🔴
    • Run the build script to generate unsigned build files in the parent (clones) directory: 
      bash debian/build.sh

  37. Verify the generated packages:

    1. List the generated files (the version in the filename will match the version specified in the lib/autokey/common.py file): 
      ls -l ~/clones/*.deb
    2. Verify that there are Wayland files inside of one of the .deb files since the previous build was for Xorg: 
      dpkg-deb -c ~/clones/autokey-common_0.97.0_all.deb | grep wayland
      If the output contains wayland_checks.py, the build succeeded.

  38. Install the builds:

    sudo apt install -y ~/clones/autokey-common_0.97.0_all.deb ~/clones/autokey-gtk_0.97.0_all.deb ~/clones/autokey-qt_0.97.0_all.deb

    🔴🟡🟢 You can ignore the warning about the download having been performed unsandboxed as root since the file couldn't be accessed by the _apt user. It's the apt command letting you know that since the .deb files it needs to read are in your private home directory and since it doesn't have permission to read your files as the _apt user, it has to fall back to reading them as root instead. 🟢🟡🔴

  39. Verify that the installation succeeded (pick one or more):

    • Display the AutoKey help: 
      autokey --help
    • Display the first line of the changelog file to make sure the most recent entry corresponds to the build you wanted to create: 
      zcat /usr/share/doc/autokey-common/changelog.gz | head -n 1

  40. Optionally, run AutoKey to make sure the build and installation worked (pick one):

    • If this is an Ubuntu 22.04 virtual machine: 
      autokey-gtk -cl
      ...or... 
      autokey-qt -cl
    • If this is an Ubuntu 24.04 virtual machine: 
      autokey-gtk -cv
      ...or... 
      autokey-qt -cv

  41. If you made changes to these steps and took notes, copy your notes out of the virtual machine.

  42. If you created logs that you'd like to reference or share later, copy those logs out of the virtual machine.

  43. Destroy the virtual machine.

Wayland - Test AutoKey - pytest

With the following steps, you can clone AutoKey and use pytest to run unit-tests on the raw source code without installing AutoKey:

  1. Create a fresh Ubuntu virtual machine.
  2. Boot the virtual machine.
  3. Log in to a Wayland session.
  4. Update the operating system: 
    sudo apt update
  5. Install the core tools (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      sudo apt install -y git python3-pip python3-pyasyncore python3-setuptools python3-tk python3-venv weston
    • If you're using Ubuntu 24.04 LTS: 
      sudo apt install -y git python3-build python3-pip python3-pyasyncore python3-setuptools python3-tk python3-venv weston
  6. Create the ${HOME}/clones/autokey directory on your system: 
    mkdir -p ~/clones
  7. Change to the new clones directory: 
    cd clones
  8. Clone AutoKey (pick one):
    • Clone a pull request, replacing 123 with the pull request number: 
      PR=123; git clone https://github.com/autokey/autokey.git && (cd autokey && git fetch origin pull/$PR/head:pull_$PR && git checkout pull_$PR)
    • Clone the current release: 
      git clone https://github.com/autokey/autokey.git
    • Clone the develop branch: 
      git clone --branch develop --single-branch https://github.com/autokey/autokey.git
  9. Change to the autokey sub-directory that you created in step 6: 
    cd autokey
  10. Edit the wayland_checks.py file to prevent the error about f-strings not being allowed to contain a backslashes (pick one):
    • If you're using Ubuntu 22.04 LTS:
      1. Open the lib/autokey/wayland_checks.py file in a text editor.
      2. Replace this block at the bottom of the file: 
        # Show popup using kdialog, if it's installed, or zenity, otherwise write the
# message to autokey.log
def __show_popup(title, message):
        try:
            subprocess.run(f"kdialog --error '{message}' --title '{title}'", shell=True, check=True)
        except Exception:
            try:

                subprocess.run(f"zenity --error --title='{title}' --text='{message.replace('<br />', '\n')}'", shell=True, check=True)
            except Exception:
                logger.critical(message)

# For testing purposes
if __name__ == '__main__':
    if not waylandChecks():
        print('waylandChecks() returned False')
        with this block: 
        # Show popup using kdialog, if it's installed, or zenity, otherwise write the
# message to autokey.log
def __show_popup(title, message):
    try:
        subprocess.run(f"kdialog --error '{message}' --title '{title}'", shell=True, check=True)
    except Exception:
        try:
            # Fix: Move the replace call out of the f-string for Python 3.10 compatibility
            clean_message = message.replace('<br />', '\n')
            subprocess.run(f"zenity --error --title='{title}' --text='{clean_message}'", shell=True, check=True)
        except Exception:
            logger.critical(message)

#  For testing purposes
if __name__ == '__main__':
    if not waylandChecks():
        print('waylandChecks() returned False')
    • If you're using Ubuntu 24.04 LTS:
      • Skip this step since it's a Python 3.10 fix that's no longer needed and would break the unit tests in Ubuntu 24.04 LTS.
  11. Install and activate a Python virtual environment to prevent modules needed by AutoKey from being installed to your system:
    1. Create a new virtual environment that has access to your global system packages: 
      python3 -m venv --system-site-packages .venv
    2. Activate the virtual environment (note that your prompt will change to let you know you're in a virtual environment): 
      source .venv/bin/activate
  12. Install AutoKey's apt dependencies: 
    sudo apt install -y $(cat apt-requirements.txt)
  13. Install AutoKey's pip dependencies: 
    python3 -m pip install -r pip-requirements.txt --break-system-packages
  14. Install the test suite and the coverage plug-in in the virtual environment (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      python3 -m pip install pytest pytest-cov pytest-xdist --break-system-packages
    • If you're using Ubuntu 24.04 LTS: 
      python3 -m pip install build pytest pytest-cov pytest-xdist --break-system-packages
  15. Create the pytest.ini file for additional coverage configuration: 
    echo -e "[pytest]\\naddopts = --cov=lib/autokey\\npythonpath = lib" > pytest.ini
  16. Configure your Wayland system to run AutoKey:
    1. Change to the autokey-gnome-extension subdirectory: 
      cd autokey-gnome-extension
    2. Build the AutoKey extension for Gnome: 
      make
    3. Install the extension: 
      gnome-extensions install autokey-gnome-extension@autokey.shell-extension.zip
    4. Configure your system to allow members of the input user group to use virtual keyboards and mice: 
      sudo cp ~/clones/autokey/config/10-autokey.rules /etc/udev/rules.d/
    5. Add your user-account to the input group: 
      sudo usermod -a -G input $USER
    6. Apply the changes by rebooting: 
      sudo reboot
    7. Log back in to a Wayland session.
    8. Turn on the AutoKey Gnome extension: 
      gnome-extensions enable autokey-gnome-extension@autokey
  17. Change to the AutoKey directory: 
    cd ~/clones/autokey
  18. Activate the virtual environment (note that your prompt will change to let you know you're in a virtual environment): 
    source .venv/bin/activate
  19. Start the Weston reference compositor for Wayland in a background socket: 
    weston --backend=headless-backend.so --socket=wayland-1 &
  20. Press the Enter key to get back to a prompt.
  21. Run the unit tests, pointing them to that socket, with the coverage option to see which parts of the code were executed for the tests: 
    WAYLAND_DISPLAY=wayland-1 XDG_SESSION_TYPE=wayland .venv/bin/python -m pytest --cov=lib/autokey tests
    Or run the same command and create a log-file: 
    WAYLAND_DISPLAY=wayland-1 XDG_SESSION_TYPE=wayland .venv/bin/python -m pytest --cov=lib/autokey tests 2>&1 | tee test_results.log
  22. If you made changes to these steps and took notes, copy your notes out of the virtual machine.
  23. If you created logs that you'd like to reference or share later, copy those logs out of the virtual machine.
  24. Destroy the virtual machine.

Wayland - Test AutoKey - tox

With the following steps, you can clone AutoKey and use tox to run compatibility tests against multiple Python versions if available without installing AutoKey:

  1. Create a fresh Ubuntu virtual machine.
  2. Boot the virtual machine.
  3. Log in to a Wayland session.
  4. Update the operating system: 
    sudo apt update
  5. Install the core tools (pick one):
    • If you're using Ubuntu 22.04 LTS: 
      sudo apt install -y build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev libdbus-1-dev libglib2.0-dev \
libcairo2-dev python3-pyqt5 python3-dbus python3-gi \
gir1.2-gtk-3.0 xvfb xdg-utils python3-pip python3-setuptools \
python3-tk python3-venv
    • If you're using Ubuntu 24.04 LTS: 
      sudo apt install -y build-essential curl gir1.2-gtk-3.0 \
gir1.2-gtksource-3.0 libcairo2-dev libdbus-1-dev \
libgirepository-2.0-dev libglib2.0-dev python3-build \
python3-dbus python3-gi python3-pip python3-pyasyncore \
python3-setuptools python3-tk python3-venv weston xvfb
    • If you're using Ubuntu 24.04 LTS 🔴🔴🔴MAYBE ALSO THIS, BUT TRY IT WITHOUT IT🔴🔴🔴: 
      sudo apt install -y libayatana-appindicator3-dev
  6. Download and set up pyenv: 
    if [ ! -d "$HOME/.pyenv" ]; then
    curl https://pyenv.run | bash
    export PYENV_ROOT="$HOME/.pyenv"
    export PATH="$PYENV_ROOT/bin:$PATH"
    eval "$(pyenv init - bash)"
    echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
    echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
    echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc
fi
  7. Install versions silently if missing 
    pyenv install -s 3.10.20
pyenv install -s 3.11.15
pyenv local system 3.10.20 3.11.15
  8. Create the ~/clones directory: 
    mkdir -p ~/clones
  9. Change to the clones directory: 
    cd clones
  10. Clone AutoKey (pick one):
    • Clone a pull request, replacing 123 with the pull request number: 
      PR=123; git clone https://github.com/autokey/autokey.git && (cd autokey && git fetch origin pull/$PR/head:pull_$PR && git checkout pull_$PR)
    • Clone the current release: 
      git clone https://github.com/autokey/autokey.git
    • Clone the develop branch: 
      git clone --branch develop --single-branch https://github.com/autokey/autokey.git
  11. Change to the autokey sub-directory: 
    cd autokey
  12. Generate the tox.ini file: 
    cat <<EOF > tox.ini
[tox]
envlist = py310, py311, py312
skipsdist = True

[testenv]
sitepackages = True
passenv = DISPLAY, XAUTHORITY, HOME, XDG_RUNTIME_DIR
setenv =
    PYTHONPATH = {toxinidir}/lib
deps = 
    pytest
    pytest-cov
    PyHamcrest
    PyGObject
    dbus-python
    python-magic
    python-xlib
    pyinotify
    PyQt5
commands = pytest
EOF
  13. Edit the wayland_checks.py file to prevent the error about f-strings not being allowed to contain a backslashes (pick one):
    • If you're using Ubuntu 22.04 LTS:
      1. Open the lib/autokey/wayland_checks.py file in a text editor.
      2. Replace this block at the bottom of the file: 
        # Show popup using kdialog, if it's installed, or zenity, otherwise write the
# message to autokey.log
def __show_popup(title, message):
        try:
            subprocess.run(f"kdialog --error '{message}' --title '{title}'", shell=True, check=True)
        except Exception:
            try:

                subprocess.run(f"zenity --error --title='{title}' --text='{message.replace('<br />', '\n')}'", shell=True, check=True)
            except Exception:
                logger.critical(message)

# For testing purposes
if __name__ == '__main__':
    if not waylandChecks():
        print('waylandChecks() returned False')
        with this block: 
        # Show popup using kdialog, if it's installed, or zenity, otherwise write the
# message to autokey.log
def __show_popup(title, message):
    try:
        subprocess.run(f"kdialog --error '{message}' --title '{title}'", shell=True, check=True)
    except Exception:
        try:
            # Fix: Move the replace call out of the f-string for Python 3.10 compatibility
            clean_message = message.replace('<br />', '\n')
            subprocess.run(f"zenity --error --title='{title}' --text='{clean_message}'", shell=True, check=True)
        except Exception:
            logger.critical(message)

#  For testing purposes
if __name__ == '__main__':
    if not waylandChecks():
        print('waylandChecks() returned False')
    • If you're using Ubuntu 24.04 LTS:
      • Skip this step since it's a Python 3.10 fix that breaks the unit tests in Ubuntu 24.04 LTS and will no longer be needed at all once GitHub drops support for Ubuntu 22.04 LTS.
  14. Install and activate a Python virtual environment to prevent modules needed by AutoKey from being installed to your system:
    1. Create a new virtual environment that has access to your global system packages: 
      python3 -m venv --system-site-packages .venv
      ...or maybe... 
      python3 -m venv .venv
    2. Activate the virtual environment (note that your prompt will change to let you know you're in a virtual environment): 
      source .venv/bin/activate
  15. Update pip and tox: 
    python3 -m pip install --upgrade pip tox
  16. Run the compatibility tests with the coverage option to see which parts of the code were executed for the tests:
    • Run the tests: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report
    • Or run the tests in verbose mode: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report -- -v
    • Or run the tests and output the report (including any errors) to the specified file: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report > tox_output.txt 2>&1
    • Or run the tests and output the summary of the report to the specified file: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report && coverage report > tox_summary.txt
    • Or run the tests and override the configuration to output the report to the specified JSON file: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report -- --cov-report=json:coverage.json
    • Or run the tests and override the configuration to output the report to the specified XML file: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report -- --cov-report=xml:coverage.xml
    • Or run the tests and override the configuration to output the report to the specified JSON and XML file: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report -- --cov-report=json:coverage.json --cov-report=xml:coverage.xml
    • Or run the tests and output the table part of the summary to the specified file: 
      xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report | tee tox_summary.txt
  17. Open the report in the browser: 
    TARGET_DIR="test_coverage_report_html"; if [ -f "$TARGET_DIR/index.html" ]; then echo "Opening report..."; xdg-open "$TARGET_DIR/index.html"; echo "Press any key to delete the $TARGET_DIR folder..."; read -n 1 -s; rm -rf "$TARGET_DIR"; echo "Report folder deleted"; else echo "Report not found."; fi
  18. If you created logs that you'd like to reference or share later, copy those logs out of the virtual machine.
  19. Destroy the virtual machine.

Wayland - Try out AutoKey - no install

  1. Create a fresh Ubuntu virtual machine.
  2. Boot the virtual machine.
  3. Log in to a Wayland session.
  4. Update the operating system: 
    sudo apt update
  5. Install the core tools: 
    sudo apt install -y git make build-essential libcairo2-dev python3-pip python3-venv gnome-shell-extension-manager
  6. Create the ${HOME}/clones/autokey directory on your system: 
    mkdir -p ~/clones
  7. Change to the clones directory: 
    cd ~/clones
  8. Clone AutoKey (pick one):
    • Clone a pull request, replacing 123 with the pull request number: 
      PR=123; git clone https://github.com/autokey/autokey.git && (cd autokey && git fetch origin pull/$PR/head:pull_$PR && git checkout pull_$PR)
    • Clone the current release: 
      git clone https://github.com/autokey/autokey.git
    • Clone the develop branch: 
      git clone --branch develop --single-branch https://github.com/autokey/autokey.git
  9. Change to the autokey directory: 
    cd ~/clones/autokey
  10. Install AutoKey's apt dependencies: 
    sudo apt install -y $(cat apt-requirements.txt)
  11. Configure your Wayland system to run AutoKey (Xorg users can skip this step):
    1. Install the AutoKey extension for Gnome:
      1. Change to the autokey-gnome-extension subdirectory: 
        cd ~/clones/autokey/autokey-gnome-extension
      2. Set up the extension: 
        make
      3. Install the extension: 
        gnome-extensions install autokey-gnome-extension@autokey.zip
    2. Configure your system to allow members of the input user group to use virtual keyboards and mice: 
      sudo cp ~/clones/autokey/config/10-autokey.rules /etc/udev/rules.d/
    3. Add your user account to the input group: 
      sudo usermod -a -G input $(id -un)
    4. Apply the changes by rebooting: 
      sudo reboot
    5. Log back in to a Wayland session.
    6. Turn on the AutoKey Gnome extension: 
      gnome-extensions enable autokey-gnome-extension@autokey.shell-extension
  12. Install the AutoKey icons:
    1. Make the system directory for icons if it doesn't already exist or let you know that it exists: 
      mkdir ~/.local/share/icons  || echo "Folder already exists!"
    2. Change to the clones/autokey/config directory: 
      cd ~/clones/autokey/config
    3. Copy the icons into the system directory for icons: 
      cp -vr *.png *.svg Humanity ubuntu-mono-* ~/.local/share/icons/
  13. Change to the clones/autokey directory: 
    cd ~/clones/autokey
  14. Install and activate a Python virtual environment to prevent modules needed by AutoKey from being installed to your system:
    1. Create a new virtual environment that has access to your global system packages: 
      python3 -m venv --system-site-packages .venv
    2. Activate the virtual environment (note that your prompt will change to let you know you're in a virtual environment): 
      source .venv/bin/activate
  15. Install AutoKey's pip dependencies: 
    python3 -m pip install -r pip-requirements.txt
  16. Install Python modules for AutoKey in the virtual environment: 
    python3 -m pip install packaging pyasyncore evdev
  17. Run AutoKey from the virtual environment:
    1. If you're using Wayland in the Gnome desktop environment, enable Assistive Technologies in the Gnome settings.
    2. Change to the /lib directory: 
      cd ~/clones/autokey/lib
    3. Pick an interface to run:
      • Run the GTK interface in verbose mode and with its configuration window open (pick one):
        • If you cloned the current release: 
          python3 -m autokey.gtkui -cl
        • If you cloned the develop branch or a pull request: 
          python3 -m autokey.gtkui -cv
      • Run the Qt interface in verbose mode and with its configuration window open (pick one):
        • If you cloned the current release: 
          python3 -m autokey.qtui -cl
        • If you cloned the develop branch or a pull request: 
          python3 -m autokey.qtui -cv
  18. Try out AutoKey's basic features:
    • Check the terminal window for traceback errors.
    • Use all of AutoKey's menu entries.
    • Go into all of AutoKey's settings to make sure they're accessible and work and that the version is correctly listed.
    • Run all of AutoKey's default phrases and scripts from the "play" button in the AutoKey interface.
    • Run all of AutoKey's default phrases and scripts from a hotkey.
    • Run all of AutoKey's default phrases and scripts from an abbreviation.
    • Change each of the settings on a phrase and try each of them out.
    • Create and try out a new phrase.
    • Create and try out a new script.
  19. When you're finished trying out AutoKey, close it normally.
  20. End the virtual environment session, returning your terminal window's prompt to normal: 
    deactivate
  21. Run AutoKey again to try the other AutoKey interface (pick one):
    • GTK: 
      #  Check if AutoKey is already running and exit if it is:
if (pgrep -c autokey > /dev/null); then
  echo "AutoKey is already running."
  exit 1
fi
source ~/clones/autokey/.venv/bin/activate
cd ~/clones/autokey/lib
python3 -m autokey.gtkui -c --verbose
deactivate
    • Qt: 
      #  Check if AutoKey is already running and exit if it is:
if (pgrep -c autokey > /dev/null); then
  echo "AutoKey is already running."
  exit 1
fi
source ~/clones/autokey/.venv/bin/activate
cd ~/clones/autokey/lib
python3 -m autokey.qtui -c --verbose
deactivate
  22. If you made changes to these steps and took notes, copy your notes out of the virtual machine.
  23. If you created logs that you'd like to reference or share later, copy those logs out of the virtual machine.
  24. Destroy the virtual machine.

🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡🟡

Goodies

Some goodies I can't live without:

  • Session type: 
    echo $XDG_SESSION_TYPE
  • Keyboard speed:
    • Xorg: 
      xset r rate 172 85
    • Wayland: 
      gsettings set org.gnome.desktop.peripherals.keyboard delay 172; gsettings set org.gnome.desktop.peripherals.keyboard repeat-interval 11
  • Prevent clipboard staleness under Wayland (pick one):
    • Set the primary paste configuration: 
      gsettings set org.gnome.desktop.interface gtk-enable-primary-paste true
    • Force Firefox to use Wayland mode for this terminal window's session: 
      export MOZ_ENABLE_WAYLAND=1
  • Tidy up by removing all pycache folders and .pyc files recursively after a while of experimenting: 
    find . -name "__pycache__" -type d -exec rm -rf {} + -o -name "*.pyc" -delete 2>/dev/null
    • or: 
      find . -type d -name "__pycache__" -exec rm -rf {} + -o -name "*.pyc" -del
  • Tidy up between tox runs: 
    tox run -c setup.cfg -e clean
clear
xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report
    If it still hangs: 
    tox -r
tox run -c setup.cfg -e clean
clear
xvfb-run -a tox run -c setup.cfg -r -e clean,coverage,report
  • Prevent the pycache and .pyc files from being created to begin with by adding the python3 -B prefix to the execution command. For example: 
    python3 -B autokey-gtk -cv
  • If you have build issues and want to try the build again, tidy up first from within the main root autokey directory: 
    (cd ~/clones/autokey && fakeroot debian/rules clean)
find ~/clones -type d -name "__pycache__" -exec rm -rf {} +
rm ~/clones/autokey-*
rm ~/clones/autokey_*
rm -rf ~/clones/autokey/.pybuild/
    • Or do all of that without multiple rm lines: 
      fakeroot debian/rules clean && rm -rf ../autokey[-_]* ../.pybuild/
  • Check which files you've changed or deleted (but not files you've added!) in this session: 
    git diff --name-only
  • Kill AutoKey if it's stuck and make sure it's gone: 
    pkill autokey; sleep 0.5; [[ $(pgrep -c autokey) -eq 0 ]] && echo "✅ Success: The AutoKey process stopped." || echo "❌ Error: AutoKey is still running."
  • Pip hack: Modern Ubuntu releases (23.04+) will give an "Externally Managed Environment" error when pip commands are run outside of a venv. If that happens and, for some reason, you want to run any of the above tests outside of a venv, you can add --break-system-packages to the end of the pip command. Since you're in a disposable VM for these tests, it’s safe to break the system rules to get the dependencies installed.

Back to top

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment