GitHub Action that returns a dynamic test matrix. Currently it supports projects using:
python
andtox
min_python
- Minimal version of python to be tested against, default is"3.8"
. The maximum value is currently"3.12"
other_names
- A list of other tox environments to include in the matrix. We plan to read them from envlist field intox.ini
.platforms
- Default tolinux
only but can belinux
,windows
,macos
or a combination of them (comma separated).linux
: matrix expansion strategy for Linux,full
orminmax
.windows
: matrix expansion strategy for Windows,full
orminmax
.macos
: matrix expansion strategy for MacOS,full
orminmax
.
Simple workflow using coactions/dynamic-matrix
# .github/workflows/tox.yml (your workflow file)
---
jobs:
pre: # <-- this runs before your real matrix job
name: pre
runs-on: ubuntu-22.04
outputs:
matrix: ${{ steps.generate_matrix.outputs.matrix }}
steps:
- name: Determine matrix
id: generate_matrix
uses: coactions/dynamic-matrix@v1
with:
other_names: |
lint
pkg
build:
name: ${{ matrix.name }}
runs-on: ${{ matrix.os || 'ubuntu-22.04' }}
needs: pre
strategy: # thais the magic part, entire matrix comes from pre job!
matrix: ${{ fromJson(needs.pre.outputs.matrix) }}
steps: # common steps used to test with tox
- uses: actions/checkout@main
with:
fetch-depth: 0
- name: Set up python ${{ matrix.python_version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python_version }}
- name: Install tox
run: |
python -m pip install -U pip
pip install tox
- run: tox run -e ${{ matrix.passed_name }}
Which projects using tox would benefit from this GitHub Action?
If your tox envlist is simple, like lint,packaging,py{36,37,38,39}
you are among the best candidates to make use of it as that is the primary usage case it covers. If you use environments combining multiple factors, you will need to specify them in other_names
argument.
Why this action does not just load envlist values?
We plan to add support for this in the future but it might not be
as simple as one would assume. For historical reasons envlist
do very often already include python versions instead of generic py
entry or
they are outdated. The repository code is not available at the
time this action runs.
Why only Linux testing is enabled by default?
Linux runners are the fastest ones and many Python projects do not need to support platforms like Windows or macOS. That is why the default platform contains only lines. Still, you can enable all of them by specifying platforms: linux,windows,macos
in the action arguments.
Why Windows and MacOS matrix expansion strategy is different than Linux one?
The defaults for macOS and Windows are minmax
while for Linux is full
. This limit resource usage low while still providing a good level of testing. If your pythons are py38,py39,py310,py311
unless you specify windows: full
you will see only two Windows based jobs in the generated matrix: py38 and py311.
What is the difference between name and passed_name in generated matrix?
name
is aimed to be the job name displayed in GHA, while passed_name
is the tox environment name. We did not name it tox_env
because we plan to add support for other testing frameworks, which might use different
terminology.
Why is other_names a multiline string instead of being comma separated?
We wanted to allow users to chain (group) multiple tox environments in a single command like tox run -e lint,packaging
, and this means that we
needed to allow users to use commas as part of a valid name, without
splitting on it.