Using Travis CI Matrix Builds to Test Multiple Python Versions

Quick answer: use a matrix to generate jobs

Add a matrix section to your .travis.yml file. Travis will expand each combination of the values you list (language versions, environment variables, etc.) into separate build jobs, letting you test multiple configurations without copying the job definition.

Worked example: Python unit and integration tests

language: python
python:
  - "3.8"
  - "3.9"
  - "3.10"
env:
  global:
    - TEST_SUITE=unit
matrix:
  include:
    - python: "3.8"
      env: TEST_SUITE=integration
    - python: "3.9"
      env: TEST_SUITE=integration
    - python: "3.10"
      env: TEST_SUITE=integration
script:
  - if [ "$TEST_SUITE" = "unit" ]; then pytest tests/unit; else pytest tests/integration; fi

Explanation:

• The top‑level python list creates three base jobs (one per version) that inherit the global TEST_SUITE=unit.
• The matrix.include block adds three additional jobs, one for each Python version, overriding TEST_SUITE to integration.
• Result: six parallel jobs – three unit‑test jobs and three integration‑test jobs.

Limits and common mistakes

• Job explosion: Each matrix entry multiplies the total job count. With the example above you get 6 jobs; adding more versions or variables can quickly exceed the concurrency limit of your Travis account (free tier allows 5 concurrent jobs).
• Incorrect indentation: The matrix block must be at the same level as language and env. Mis‑indenting it under env or script causes Travis to ignore the matrix or produce parsing errors.
• Mixing include and exclude: Using both in the same matrix can lead to unexpected combinations because exclude is applied after the full Cartesian product. If you need to remove specific combos, prefer exclude only, or restructure the matrix to avoid the need for both.
• Variable scope: Variables defined under the top‑level env: are global to all jobs unless they are placed inside a matrix item. In the example, TEST_SUITE=unit is global; the include items override it for integration tests.

How to verify the matrix works

1. Push the .travis.yml to a branch and watch the Travis dashboard; you should see six separate jobs labeled with the corresponding Python version and TEST_SUITE value.
2. In each job’s log, look for lines like Using Python 3.9 and TEST_SUITE=integration to confirm the variables were applied.
3. Optionally run travis lint locally (requires the Travis CLI) to catch YAML syntax errors before pushing.

Remember that matrix changes only affect new builds; any builds already queued or running will keep the matrix they were started with.