Development#

Local development setup#

menuinst is a multiplatform tool with heavy reliance on OS-specific behaviour, APIs and tools. Each platform requires its own setup.

Since some tests might leave traces behind, we recommend running the tests from a VM (if you can). For your own protection, some tests only run when the CI env var has been set to a non-empty value. If you do want to run these on your local machine, you can set the CI env var to 1 before running the tests; it better be on a VM though!

Linux#

We recommend using Docker to run the tests on Linux. However, some tasks require a graphical environment.

Docker setup#

  1. We can leverage conda/conda’s conda-forge-based CI image for this. Make sure to mount the menuinst source to a known location in the container. In the example below, we are using ~/my/repos/menuinst, mapped to /opt/menuinst-src.

$ docker run -it --rm --platform=linux/aarch64 \
    -v ~/my/repos/menuinst:/opt/menuinst-src \
    ghcr.io/conda/conda-ci:main-linux-python3.10-conda-forge bash

  1. Create a new conda environment and install the dependencies:

$ conda create -n menuinst-dev \
    conda-canary/label/conda-conda-pr-11882::conda \
    pip \
    pytest \
    pytest-cov \
    pydantic \
    hypothesis \
    hypothesis-jsonschema

  1. Activate the environment and install menuinst:

$ conda activate menuinst-dev
$ python -m pip install -vv /opt/menuinst-src

  1. Run the tests:

$ cd /opt/menuinst-src
$ pytest

VM setup#

macOS#

Some of the tests involve modifying the system’s menu. While we have added some teardown logic to undo the modifications once done, it might still leave some artifacts behind. We recommend running the tests from a VM (if you can).

VM setup with UTM#

This is recommended for Apple Silicon.

  1. Download UTM and create a new VM for macOS using the default settings. The UI only requires a couple clicks, but the download and automated install will take a few hours, so be patient.

Debug in CI#

In extreme cases, you can edit the Github Actions workflow to add a step for mxschmitt/action-tmate and then connect to the VM via SSH. Please be mindful of the resources and only add it for the platforms and Python versions you need. For example:

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  timeout-minutes: 60
  if: ${{ failure() && startsWith(matrix.os, 'macos') && matrix.python-version == '3.9' }}

Windows#

Some tests will add changes to your system configuration (Windows registry, new files added, etc). We try to clean up after ourselves, but it’s not always possible. We recommend running the tests from a VM (if you can).