tox azure-pipeline-template

This a template that will help simplify the
Azure Pipelines configuration when using
tox to drive your CI.

usage

First configure a github service connection

It is suggested to use a generic name, such as github so forks can also configure the same.

You can find this in Project Settings => Service connections in the Azure Devops dashboard for your project. Project
settings is located in the bottom left corner of the UI as of 2019-04-30. Below I’m using the endpoint name github.

To load the template, add this to the beginning of the azure-pipelines.yml

resources:
  repositories:
    - repository: tox
      type: github
      endpoint: github
      name: tox-dev/azure-pipelines-template
      ref: refs/tags/0.2

this will make the templates in this repository available in the tox namespace. Note the ref allows you to pin the
template version you want, you can use refs/master if you want latest unstable version.

job templates

run-tox-env.yml

Assumptions

tox will run under Python 3.8. tox environments generate Junit file under .tox\junit.{toxenv}.xml. Environments
tracking coverage data generate will have another tox environment to normalize/merge coverage files. These should be
invoked after test suit runs, and one final time to merge all the sub-coverage files when all specified tox environments
finished (independent their outcome).

Logic

This job template will run tox for a given set of tox target on given platforms (new in 0.2). Features and
functionality:

• each specified toxenv target maps to a single Azure Pipelines job, but split over multiple architectures via the image
  matrix (each matrix will set the image_name variable to macOs, linux or windows depending on the image used)
• make tox available in the job: provision a python (3.8) and install a specified tox into that
• provision a python needed for the target tox environment
• provision the target tox environment (create environment, install dependencies)
• invoke the tox target
• if a junit file is found under .tox\junit.{toxenv}.xml upload it as test report
• if coverage is requested, run a tox target that should generate the .tox\coverage.xml or .tox\.coverage and upload
  those as a build artifact (also enqueue a job after all these job succeed to merge the generated coverage reports)
• if coverage was requested queue a job that post all toxenv runs will merge all the coverages via a tox target

example

The following example will run py36 and py37 on Windows, Linux and MacOs. It will also invoke fix_lint and docs
target with python3.8 on Linux. It will also run the the coverage tox environment for py37 and py36, and then
save as build artifacts files .tox/.coverage and .tox/coverage.xml:

jobs:
  - template: run-tox-env.yml@tox
    parameters:
      tox_version: ""
      jobs:
        fix_lint: null
        docs: null
        py37:
          image: [linux, windows, macOs]
        py36:
          image: [linux, windows, macOs]
      coverage:
        with_toxenv: "coverage"
        for_envs: [py39, py38]

parameters

At root level you can control with:

• tox_version the tox version specifier to install, this defaults to latest in PyPi (tox) - setting it to empty,
• dependsOn jobs these set of jobs should depend on
• before steps to be run before invoking every tox environment (useful to provision additional dependencies), use
  condition variables for architecture specific content

• jobs a map where the key is the tox environment key, while the value is configuration related to that environment:

  • the key determines the tox target to run

  • the value contains:

    • image to list an array of targeted architecture, the array elements are mapped as:

      • linux - ubuntu-latest
      • windows - windows-latest
      • osx - macOS-latest
      • otherwise the value if set, fallback to ubuntu-latest.

    • py - determines the python to provision for running the environment, if not set will be derived from the key:

      • py27 or starts with py27- - Python 2.7
      • py36 or starts with py36- - Python 3.6
      • py37 or starts with py37- - Python 3.7
      • py38 or starts with py38- - Python 3.8
      • py39 or starts with py39- - Python 3.9
      • py310 or starts with py310- - Python 3.10
      • pypy or starts with pypy- - PyPy 2
      • pypy3 or starts with pypy3- - PyPy 3
      • jython - Jython is available from under Linux and MacOs.
    • architecture: Python architecture (either x64 or x86) with default x64 (only affects windows)
    • before steps to be run before invoking this tox environment (useful to provision additional dependencies)

• coverage - if set runs a tox environment (with_toxenv - must run with python3.8) to normalize coverage data
  (must generate .tox/.coverage and .tox/coverage.xml) after all environments within for_envs. It also enqueues a
  final job to use with_toxenv to merge the coverage files under the name report_coverage.

publish-pypi.yml

Assumptions

The project is PEP-517 and PEP-518 compatible. A PyPi remote and external feed is configured via Azure Pipelines project
dashboard.

Logic

This job template will publish the Python package in the current folder (both sdist and wheel) via the PEP-517/8 build
mechanism and twine.

example

- ${{ if startsWith(variables['Build.SourceBranch'], 'refs/tags/') }}:
    - template: publish-pypi.yml@tox
      parameters:
        external_feed: "toxdev"
        pypi_remote: "pypi-toxdev"
        dependsOn: [report_coverage, fix_lint, docs]

parameters

• external_feed - the external feed to upload
• pypi_remote - the pypi remote to upload to
• dependsOn - jobs this jobs depends on