tox.yml

name: Python tests
on:
  push:
    branches:
      - develop
      - 'release-v**'
  pull_request:
    branches:
      - develop
      - 'release-v**'
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true
permissions:
  contents: read
  actions: read
env:
  # Skips setuptools_scm's `git archive` file listing; see Makefile.
  SETUPTOOLS_SCM_IGNORE_VCS_ROOTS: ${{ github.workspace }}
jobs:
  pre_job:
    name: Path match check
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      should_skip: ${{ steps.skip_check.outputs.should_skip }}
    steps:
      - id: skip_check
        uses: fkirc/skip-duplicate-actions@master
        with:
          github_token: ${{ github.token }}
          paths: '["**.py", ".github/workflows/tox.yml", "pyproject.toml", "uv.lock", "python_packages/**"]'
  unit_test_stage1:
    name: Python unit tests (Python 3.10)
    needs: pre_job
    if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          # Don't cache, only saves 1-2s per run.
          enable-cache: false
      - name: Install Python 3.10
        run: uv python install 3.10
      - name: Install dependencies
        run: uv sync --group test --python 3.10
      - name: Check migrations
        run: uv run kolibri manage makemigrations --check
        env:
          KOLIBRI_HOME: ${{ runner.temp }}/.kolibri
      - name: Run tests
        run: |
          uv run python -O -m pytest kolibri --color=no
          uv run python -O -m pytest --color=no -p no:django test
  unit_test_stage2:
    name: Python unit tests for uv-supported Python versions
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.8', '3.9', '3.11', '3.12', '3.13', '3.14']
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}
      - name: Install dependencies
        run: uv sync --group test --python ${{ matrix.python-version }}
      - name: Check migrations
        run: uv run kolibri manage makemigrations --check
        env:
          KOLIBRI_HOME: ${{ runner.temp }}/.kolibri
      - name: Run tests
        run: |
          uv run python -O -m pytest kolibri --color=no
          uv run python -O -m pytest --color=no -p no:django test
  unit_test_no_uv:
    name: Python unit tests for Python versions without uv support
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.6, 3.7]
    container:
      image: python:${{ matrix.python-version }}-buster
    env:
      PYTHONPATH: /home/runner/work/kolibri/kolibri
      KOLIBRI_HOME: /tmp/.kolibri
      DJANGO_SETTINGS_MODULE: kolibri.deployment.default.settings.test
      KOLIBRI_RUN_MODE: test
      SKIP_PY_CHECK: "1"
    steps:
      - name: Fix apt sources for archived Buster repos
        run: |
          echo "deb http://archive.debian.org/debian-archive/debian/ buster main" > /etc/apt/sources.list
          echo "deb http://archive.debian.org/debian-archive/debian-security/ buster/updates main" >> /etc/apt/sources.list
          echo 'Acquire::Check-Valid-Until "false";' > /etc/apt/apt.conf.d/99archive
          apt-get -y -qq update
          apt-get install -y git git-lfs
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      # The buster container runs as root but the checkout is owned by the
      # runner user, so git refuses to operate without this.
      - name: Fix git safe directory
        run: git config --global --add safe.directory /__w/kolibri/kolibri
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install dependencies
        run: |
          uv pip install --system --group base --group test
          uv pip install --system -r requirements/cext.txt
          make set-no-uv-python-version-for-tests
      - name: Check migrations
        run: python -m kolibri manage makemigrations --check
      - name: Run tests
        run: |
          # test_version.py needs setuptools-scm (not available on 3.6/3.7)
          # test_cli.py::test_list_plugins* needs installed entry points (not available via PYTHONPATH)
          python -O -m pytest kolibri --color=no --ignore=kolibri/utils/tests/test_version.py -k "not test_list_plugins"
          python -O -m pytest --color=no -p no:django test
  postgres:
    name: Python postgres unit tests
    needs: pre_job
    if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
    runs-on: ubuntu-latest
    services:
      # Label used to access the service container
      postgres:
        # Docker Hub image
        image: postgres:16
        # Provide the password for postgres
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test
        # Set health checks to wait until postgres has started
        options: >-
          --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          # Maps tcp port 5432 on service container to the host
          - 5432:5432
        # This database is discarded when the job ends, so crash durability buys
        # nothing, while every COMMIT costs an fsync. 3.2x on the content tests.
        command: >-
          -c fsync=off -c synchronous_commit=off -c full_page_writes=off
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python 3.9
        run: uv python install 3.9
      - name: Install dependencies
        run: uv sync --group test --extra postgres --python 3.9
      - name: Run tests
        run: |
          uv run python -O -m pytest kolibri --color=no
          uv run python -O -m pytest --color=no -p no:django test
        env:
          KOLIBRI_DATABASE_ENGINE: postgres
          KOLIBRI_DATABASE_USER: postgres
          KOLIBRI_DATABASE_NAME: test
          KOLIBRI_DATABASE_HOST: localhost
          KOLIBRI_DATABASE_PASSWORD: postgres
          KOLIBRI_DATABASE_PORT: "5432"
  postgres_ssl:
    name: Python postgres SSL smoke tests
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.14']
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test
        options: >-
          --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          - 5432:5432
        command: >-
          -c ssl=on -c ssl_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem -c ssl_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}
      - name: Install dependencies
        run: uv sync --group test --extra postgres --python ${{ matrix.python-version }}
      - name: Test with SSL enabled (require mode)
        run: uv run python -O -m pytest kolibri/core/public/test/test_api.py -k SyncQueueViewSetDeletedUsersTestCase --color=no
        env:
          KOLIBRI_DATABASE_ENGINE: postgres
          KOLIBRI_DATABASE_USER: postgres
          KOLIBRI_DATABASE_NAME: test
          KOLIBRI_DATABASE_HOST: localhost
          KOLIBRI_DATABASE_PASSWORD: postgres
          KOLIBRI_DATABASE_PORT: "5432"
          KOLIBRI_DATABASE_SSL_MODE: require
  macos:
    name: Python unit tests on Mac OS
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: macos-14
    strategy:
      matrix:
        python-version: ['3.10']
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}
      - name: Install dependencies
        run: uv sync --group test --python ${{ matrix.python-version }}
      - name: Run tests
        run: |
          uv run python -O -m pytest kolibri --color=no
          uv run python -O -m pytest --color=no -p no:django test
  windows:
    name: Python unit tests on Windows Server
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: windows-latest
    strategy:
      matrix:
        python-version: [3.8]
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      # github.workspace is backslashed here but git reports forward slashes,
      # and setuptools_scm compares the two as strings, so take git's own form.
      - name: Set the ignored VCS root from git
        shell: bash
        run: echo "SETUPTOOLS_SCM_IGNORE_VCS_ROOTS=$(git rev-parse --show-toplevel)" >> "$GITHUB_ENV"
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}
      - name: Install dependencies
        run: uv sync --group test --python ${{ matrix.python-version }}
      - name: Run tests
        run: |
          uv run python -O -m pytest kolibri --color=no
          uv run python -O -m pytest --color=no -p no:django test
  sync_extras_plugin_tests:
    name: kolibri-sync-extras-plugin tests
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python 3.10
        run: uv python install 3.10
      - name: Install dependencies
        # --all-packages is required: a plain `uv sync` scopes to this
        # subproject alone and drops root kolibri's own runtime deps
        # (Django, Click, etc.) from the shared venv.
        working-directory: python_packages/kolibri-sync-extras-plugin
        run: uv sync --group test --python 3.10 --all-packages
      - name: Enable kolibri_sync_extras_plugin
        working-directory: python_packages/kolibri-sync-extras-plugin
        env:
          KOLIBRI_HOME: .kolibri
        run: uv run kolibri plugin enable kolibri_sync_extras_plugin
      - name: Run tests
        working-directory: python_packages/kolibri-sync-extras-plugin
        env:
          KOLIBRI_HOME: .kolibri
        run: uv run python -O -m pytest --reuse-db
  opensearch_plugin_tests:
    name: kolibri-opensearch-plugin tests
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python 3.10
        run: uv python install 3.10
      - name: Install dependencies
        # --all-packages is required: a plain `uv sync` scopes to this
        # subproject alone and drops root kolibri's own runtime deps
        # (Django, Click, etc.) from the shared venv.
        working-directory: python_packages/kolibri-opensearch-plugin
        run: uv sync --group test --python 3.10 --all-packages
      - name: Enable kolibri_opensearch_plugin
        working-directory: python_packages/kolibri-opensearch-plugin
        env:
          KOLIBRI_HOME: .kolibri
        run: uv run kolibri plugin enable kolibri_opensearch_plugin
      - name: Run tests
        working-directory: python_packages/kolibri-opensearch-plugin
        env:
          KOLIBRI_HOME: .kolibri
        run: uv run python -O -m pytest --reuse-db
  # Tests for platforms/ members with their own suites, each pinned to Python
  # 3.10. debian-server needs the distro-info system package; android's
  # websockets test dep requires >= 3.10.
  platform_tests:
    name: Platform tests (${{ matrix.name }})
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: debian-server
            working-directory: platforms/debian-server
            python-version: "3.10"
            system-packages: distro-info
          - name: desktop-app
            working-directory: platforms/desktop-app
            python-version: "3.10"
          - name: android
            working-directory: platforms/android
            python-version: "3.10"
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}
      - name: Install system dependencies
        if: ${{ matrix.system-packages }}
        run: |
          sudo apt-get update
          sudo apt-get install -y ${{ matrix.system-packages }}
      - name: Install dependencies
        # --all-packages keeps root kolibri's runtime deps in the shared venv;
        # see the sync_extras_plugin_tests note above.
        working-directory: ${{ matrix.working-directory }}
        run: uv sync --group test --python ${{ matrix.python-version }} --all-packages
      - name: Run tests
        working-directory: ${{ matrix.working-directory }}
        run: uv run python -O -m pytest
  # Android host tests: the WorkManager task layer against real Kolibri core
  # (supervisor ownership, reconciliation). Needs Kolibri's Django test settings
  # and the kolibri/dist pythonpath, so runs from repo root with root pytest.ini,
  # not the member's config. Python 3.10 matches Chaquopy's embedded runtime.
  android_platform_tests:
    name: Android host tests
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      - name: Install Python 3.10
        run: uv python install 3.10
      - name: Install dependencies
        # --all-packages keeps root kolibri's runtime + test deps in the shared
        # venv alongside the kolibri-installer-android member; the tests import
        # kolibri.core.tasks and run real jobs through morango storage.
        run: uv sync --group test --python 3.10 --all-packages
      - name: Run tests
        run: uv run python -O -m pytest platforms/android/app/src/main/python/tests -c pytest.ini --color=no
  # Android JVM (Robolectric) unit tests. Need a JVM/Android toolchain (JDK 21,
  # Android SDK, Chaquopy buildPython 3.10), so kept separate from platform_tests.
  # Runs `gradle test` with no tar staged, proving it's decoupled from the dist.
  android_jvm_tests:
    name: Android JVM unit tests
    needs: [pre_job, stage1_required_checks]
    if: ${{ needs.pre_job.outputs.should_skip != 'true' && needs.stage1_required_checks.result == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
      - name: Set up JDK 21
        uses: actions/setup-java@v5.6.0
        with:
          distribution: 'temurin'
          java-version: '21'
          cache: 'gradle'
      - name: Set up uv
        uses: astral-sh/setup-uv@v9.0.0
        with:
          enable-cache: false
      # Chaquopy's buildPython (the workspace .venv) must match its embedded 3.10.
      - name: Provision Chaquopy buildPython (3.10)
        run: uv sync --package kolibri-installer-android --python 3.10
      - name: Run JVM unit tests
        working-directory: platforms/android
        run: ./gradlew test
  # Single stable check for branch protection. Skipped matrix jobs don't
  # produce per-version check runs, so matrix-suffixed required checks hang
  # as "Expected" on PRs that skip the tests; require these jobs instead.
  # Stage 1: fast, blocking feedback.
  stage1_required_checks:
    name: Python tests (stage 1)
    needs:
      - pre_job
      - unit_test_stage1
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Fail if any needed job failed or was cancelled
        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
        run: exit 1
  # Stage 2: rest of the Python version matrix plus per-member-package tests.
  # `postgres` gates here, not stage 1: it runs ~3x longer than the sqlite suite,
  # so gating stage 1 on it held every stage 2 job back by its own runtime. It
  # still starts off `pre_job`, so it now runs alongside stage 2 rather than
  # before it.
  stage2_required_checks:
    name: Python tests
    needs:
      - stage1_required_checks
      - postgres
      - unit_test_stage2
      - unit_test_no_uv
      - postgres_ssl
      - macos
      - windows
      - sync_extras_plugin_tests
      - opensearch_plugin_tests
      - platform_tests
      - android_platform_tests
      - android_jvm_tests
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Fail if any needed job failed or was cancelled
        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
        run: exit 1