ci.yml

name: CI
on:
  pull_request:
  push:
    branches:
      - main
  workflow_call:
    inputs:
      attest-package:
        description: "Create GitHub provenance attestation for the package."
        default: "false"
        type: string
    outputs:
      artifact-basename:
        description: "Base name of the uploaded artifacts; use for artifact retrieval."
        value: ${{ jobs.package.outputs.artifact-basename }}

env:
  min_python_version: "3.9"
  max_python_version: "3.12"
  FORCE_COLOR: "1"

defaults:
  run:
    shell: bash

# Cancel active CI runs for a PR before starting another run
concurrency:
  group: ${{ github.workflow}}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  pre-commit:
    name: Pre-commit checks
    uses: beeware/.github/.github/workflows/pre-commit-run.yml@main
    with:
      # Although we only want to install the dev dependencies, we have to install the
      # core, which means we need travertino as well.
      pre-commit-source: "./travertino ./core[dev]"

  towncrier:
    name: Check towncrier
    uses: beeware/.github/.github/workflows/towncrier-run.yml@main
    with:
      # Although we only want to install the dev dependencies, we have to install the
      # core, which means we need travertino as well.
      tox-source: "./travertino ./core[dev]"

  package:
    name: Package Toga
    permissions:
      id-token: write
      contents: read
      attestations: write
    strategy:
      matrix:
        subdir:
        - "android"
        - "cocoa"
        - "core"
        - "demo"
        - "dummy"
        - "gtk"
        - "iOS"
        - "toga"
        - "travertino"
        - "textual"
        - "web"
        - "winforms"
    uses: beeware/.github/.github/workflows/python-package-create.yml@main
    with:
      build-subdirectory: ${{ matrix.subdir }}
      attest: ${{ inputs.attest-package }}

  core-and-travertino:
    name: Test ${{ matrix.package }} (${{ matrix.platform }}, ${{ matrix.python-version }})
    runs-on: ${{ matrix.platform }}
    needs: [ pre-commit, towncrier, package ]
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: false
      matrix:
        platform: [ "macos-latest", "ubuntu-latest", "windows-latest" ]
        python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
        package: ["core", "travertino"]
        exclude:
        - package: travertino
          platform: macos-latest
        - package: travertino
          platform: windows-latest
        include:
        - experimental: false
        - package: "core"
          tox-suffix: ""
        - package: "travertino"
          tox-suffix: "-trav"

    steps:
    - name: Checkout
      uses: actions/checkout@v4.2.2
      with:
        fetch-depth: 0

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5.4.0
      with:
        python-version: ${{ matrix.python-version }}
        allow-prereleases: true

    - name: Install Tox
      uses: beeware/.github/.github/actions/install-requirement@main
      with:
        requirements: tox
        extra: dev
        project-root: ${{ matrix.package }}

    - name: Get Packages
      uses: actions/download-artifact@v4.1.8
      with:
        pattern: ${{ format('{0}-*', needs.package.outputs.artifact-basename) }}
        merge-multiple: true
        path: dist

    - name: Test
      run: |
        # The $(ls ...) shell expansion is done in the Github environment; the value of
        # TOGA_INSTALL_COMMAND will be a literal string without any shell expansions to
        # perform. We don't *explicitly* install the Travertino wheel; we provide the
        # dist dir as a source of wheels, and rely on pip to resolve the explicit
        # version match to the Travertino wheel in that folder.
        export TOGA_INSTALL_COMMAND="python -m pip install --find-links ../dist ../$(ls dist/toga_core-*.whl)[dev] ../$(ls dist/toga_dummy-*.whl)"
        tox -e py-cov${{ matrix.tox-suffix }}
        tox -qe coverage$(tr -dc "0-9" <<< "${{ matrix.python-version }}")${{ matrix.tox-suffix }}
        mv ${{ matrix.package }}/.coverage ${{ matrix.package }}/.coverage.${{ matrix.platform }}.${{ matrix.python-version }}

    - name: Store Coverage Data
      uses: actions/upload-artifact@v4.6.0
      with:
        name: ${{ matrix.package }}-coverage-data-${{ matrix.platform }}-${{ matrix.python-version }}
        path: "${{ matrix.package }}/.coverage.*"
        if-no-files-found: error
        include-hidden-files: true

  micropython:
    name: MicroPython compatibility
    runs-on: ubuntu-latest
    needs: [ pre-commit, towncrier, package ]
    steps:
      - name: Build MicroPython
        id: micropython
        run: |
          # The following script also works on macOS, except that due to a bug,
          # threading must be enabled, i.e. THREAD must be omitted from the disabled
          # feature list.
          cd $RUNNER_TEMP
          git clone https://github.com/micropython/micropython -b v1.24.0 --depth 1

          # Create a variant with the same configuration as the PyScript build.
          cd micropython/ports/unix
          cp -a variants/standard variants/pyscript
          grep require ../webassembly/variants/pyscript/manifest.py \
              >> variants/pyscript/manifest.py
          for feature in BTREE FFI SOCKET SSL TERMIOS THREAD; do
              echo "MICROPY_PY_$feature = 0" >> variants/pyscript/mpconfigvariant.mk
          done

          export VARIANT=pyscript
          make submodules
          make -j $(nproc)
          echo "executable=$(pwd)/build-pyscript/micropython" >> $GITHUB_OUTPUT

      - name: Checkout
        uses: actions/checkout@v4.2.2

      - name: Set up Python
        uses: actions/setup-python@v5.4.0
        with:
          python-version: "3.13"

      - name: Get Core Package
        uses: actions/download-artifact@v4.1.8
        with:
          name: Packages-toga-core
          path: dist

      - name: Get Travertino Package
        uses: actions/download-artifact@v4.1.8
        with:
          name: Packages-toga-travertino
          path: dist

      - name: Test
        run: |
          # We don't *explicitly* install the Travertino wheel; we provide the dist dir
          # as a source of wheels, and rely on pip to resolve the explicit version match
          # to the travertino wheel in that folder.
          pip install --find-links ./dist dist/toga_core-*.whl

          site_packages=$(python -c '
          import sys
          print([path for path in sys.path if "site-packages" in path][0])
          ')

          cd core
          export MICROPYPATH="$site_packages:.frozen"

          ${{ steps.micropython.outputs.executable }} micropython_check.py

  core-and-travertino-coverage:
    name: "Coverage: ${{ matrix.package }}"
    needs: core-and-travertino
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ["core", "travertino"]
        include:
          - package: "core"
            tox-suffix: ""
          - package: "travertino"
            tox-suffix: "-trav"
    steps:
    - name: Checkout
      uses: actions/checkout@v4.2.2
      with:
        fetch-depth: 0

    - name: Set up Python ${{ env.min_python_version }}
      uses: actions/setup-python@v5.4.0
      with:
        # Use minimum version of python for coverage to avoid phantom branches
        # https://github.com/nedbat/coveragepy/issues/1572#issuecomment-1522546425
        python-version: ${{ env.min_python_version }}

    - name: Install Tox
      uses: beeware/.github/.github/actions/install-requirement@main
      with:
        requirements: tox
        extra: dev
        project-root: ${{ matrix.package }}

    - name: Retrieve Coverage Data
      uses: actions/download-artifact@v4.1.8
      with:
        pattern: ${{ matrix.package }}-coverage-data-*
        path: ${{ matrix.package }}
        merge-multiple: true

    - name: Generate Coverage Report
      # Even with "fail" on, Travertino will accept <100%.
      run: tox -e coverage${{ matrix.tox-suffix }}-html-fail-platform

    - name: Upload HTML Coverage Report
      uses: actions/upload-artifact@v4.6.0
      if: failure()
      with:
        name: html-coverage-report
        path: ${{ matrix.package }}/htmlcov

  testbed:
    name: Testbed
    needs: [ package, core-and-travertino ]
    runs-on: ${{ matrix.runs-on }}
    strategy:
      fail-fast: false
      matrix:
        backend:
        - "macOS-x86_64"
        - "macOS-arm64"
        - "windows"
        - "linux-x11-gtk3"
        - "linux-wayland-gtk3"
        - "linux-wayland-gtk4"
        - "android"
        - "iOS"
        - "textual-linux"
        - "textual-macOS"
        - "textual-windows"
        include:
        - pre-command: ""
          briefcase-run-prefix: ""
          briefcase-run-args: ""
          setup-python: true

        - backend: "macOS-x86_64"
          platform: "macOS"
          runs-on: "macos-13"
          app-user-data-path: "$HOME/Library/Application Support/org.beeware.toga.testbed"

        - backend: "macOS-arm64"
          platform: "macOS"
          runs-on: "macos-latest"
          app-user-data-path: "$HOME/Library/Application Support/org.beeware.toga.testbed"

        # We use a fixed Ubuntu version rather than `-latest` because at some point,
        # `-latest` will be updated, but it will be a soft changeover, which would cause
        # the system Python version to become inconsistent from run to run.
        - backend: "linux-x11-gtk3"
          platform: "linux"
          runs-on: "ubuntu-24.04"
          # The package list should be the same as in unix-prerequisites.rst, and the BeeWare
          # tutorial, plus blackbox to provide a window manager. We need a window
          # manager that is reasonably lightweight, honors full screen mode, and
          # treats the window position as the top-left corner of the *window*, not the
          # top-left corner of the window *content*. The default GNOME window managers of
          # most distros meet these requirements, but they're heavyweight; flwm doesn't
          # work either. Blackbox is the lightest WM we've found that works.
          pre-command: |
            sudo apt update -y
            sudo apt install -y --no-install-recommends \
              blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev \
              gir1.2-webkit2-4.1 gir1.2-xapp-1.0 gir1.2-geoclue-2.0 gir1.2-flatpak-1.0

            # Start Virtual X Server
            echo "Start X server..."
            Xvfb :99 -screen 0 2048x1536x24 &
            sleep 1

            # Start Window Mmanager
            echo "Start window manager..."
            DISPLAY=:99 blackbox &
            sleep 1
          briefcase-run-prefix: 'DISPLAY=:99'
          setup-python: false  # Use the system Python packages
          app-user-data-path: "$HOME/.local/share/testbed"

        - backend: "linux-wayland-gtk3"
          platform: "linux"
          runs-on: "ubuntu-24.04"
          # The package list should be the same as in unix-prerequisites.rst, and the BeeWare
          # tutorial, plus mutter to provide a window manager.
          pre-command: |
            sudo apt update -y
            sudo apt install -y --no-install-recommends \
              mutter pkg-config python3-dev libgirepository1.0-dev libcairo2-dev \
              gir1.2-webkit2-4.1 gir1.2-xapp-1.0 gir1.2-geoclue-2.0 gir1.2-flatpak-1.0

            # Start Virtual X Server
            echo "Start X server..."
            Xvfb :99 -screen 0 2048x1536x24 &
            sleep 1

            # Start Window Manager
            echo "Start window manager..."
            # mutter is being run inside a virtual X server because mutter's headless
            # mode does not provide a Gdk.Display
            DISPLAY=:99 MUTTER_DEBUG_DUMMY_MODE_SPECS=2048x1536 \
              mutter --nested --wayland --no-x11 --wayland-display toga &
            sleep 1
          briefcase-run-prefix: "WAYLAND_DISPLAY=toga"
          setup-python: false  # Use the system Python packages
          app-user-data-path: "$HOME/.local/share/testbed"

        - backend: "linux-wayland-gtk4"
          platform: "linux"
          runs-on: "ubuntu-24.04"
          env:
            XDG_RUNTIME_DIR: "/tmp"
          # The package list should be the same as in unix-prerequisites.rst, and the BeeWare
          # tutorial, plus mutter to provide a window manager.
          pre-command: |
            sudo apt update -y
            sudo apt install -y --no-install-recommends \
              mutter pkg-config python3-dev libgirepository1.0-dev libcairo2-dev \
              gir1.2-webkit-6.0 gir1.2-xapp-1.0 gir1.2-geoclue-2.0 gir1.2-flatpak-1.0 \
              gir1.2-gtk-4.0

            # Start Virtual X Server
            echo "Start X server..."
            Xvfb :99 -screen 0 2048x1536x24 &
            sleep 1

            # Start Window Manager
            echo "Start window manager..."
            # mutter is being run inside a virtual X server because mutter's headless
            # mode does not provide a Gdk.Display
            DISPLAY=:99 MUTTER_DEBUG_DUMMY_MODE_SPECS=2048x1536 \
              mutter --nested --wayland --no-x11 --wayland-display toga &
            sleep 1
          briefcase-run-prefix: "WAYLAND_DISPLAY=toga TOGA_GTK=4"
          setup-python: false  # Use the system Python packages
          app-user-data-path: "$HOME/.local/share/testbed"

        - backend: "textual-linux"
          platform: "linux"
          runs-on: "ubuntu-latest"
          setup-python: false  # Use the system Python packages
          briefcase-run-args: --config 'requires=["toga-core", "toga-textual"]' --config 'console_app=true'
          app-user-data-path: "$HOME/.local/share/testbed"
          # install the meta-package build-essential since Briefcase explicitly checks for it
          pre-command: sudo apt update -y && sudo apt install -y build-essential

        - backend: "textual-macOS"
          platform: "macOS"
          runs-on: "macos-latest"
          briefcase-run-args: --config 'requires=["toga-core", "toga-textual"]' --config 'console_app=true'
          app-user-data-path: "$HOME/Library/Application Support/org.beeware.toga.testbed"

        - backend: "textual-windows"
          platform: "windows"
          runs-on: "windows-latest"
          briefcase-run-args: --config 'requires=["toga-core", "toga-textual"]' --config 'console_app=true'
          app-user-data-path: '$HOME\AppData\Local\Tiberius Yak\Toga Testbed\Data'

        - backend: "windows"
          platform: "windows"
          runs-on: "windows-latest"
          app-user-data-path: '$HOME\AppData\Local\Tiberius Yak\Toga Testbed\Data'

        - backend: "iOS"
          platform: "iOS"
          runs-on: "macos-latest"
          briefcase-run-args: "--device 'iPhone SE (3rd generation)'"
          app-user-data-path: "$(xcrun simctl get_app_container booted org.beeware.toga.testbed data)/Documents"

        - backend: "android"
          platform: "android"
          runs-on: "ubuntu-latest"
          briefcase-run-prefix: JAVA_HOME=${JAVA_HOME_17_X64}
          briefcase-run-args: >-
            --device '{"avd":"beePhone","skin":"pixel_3a"}'
            --Xemulator=-no-window
            --Xemulator=-no-snapshot
            --Xemulator=-no-audio
            --Xemulator=-no-boot-anim
            --shutdown-on-exit
          pre-command: |
            # allow access to KVM to run the emulator
            echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
              | sudo tee /etc/udev/rules.d/99-kvm4all.rules
            sudo udevadm control --reload-rules
            sudo udevadm trigger --name-match=kvm
    steps:
    # GitHub runners seem to have intermittent connectivity issues.
    # See https://github.com/beeware/toga/issues/2632
    - name: Tune GitHub-hosted runner network
      uses: smorimoto/tune-github-hosted-runner-network@v1.0.0

    - name: Checkout
      uses: actions/checkout@v4.2.2
      with:
        fetch-depth: 0

    - name: Set up Python
      uses: actions/setup-python@v5.4.0
      if: matrix.setup-python
      with:
        python-version: "3.12"

    - name: Install Dependencies
      env:
        PIP_BREAK_SYSTEM_PACKAGES: "1"
      run: |
        ${{ matrix.pre-command }}
        # Use the development version of Briefcase
        python -m pip install -U pip
        python -m pip install git+https://github.com/beeware/briefcase.git

    - name: Get Packages
      uses: actions/download-artifact@v4.1.8
      with:
        pattern: ${{ format('{0}-*', needs.package.outputs.artifact-basename) }}
        merge-multiple: true
        path: dist

    - name: Test App
      working-directory: testbed
      timeout-minutes: 15
      run: |
        ${{ matrix.briefcase-run-prefix }} \
          briefcase run ${{ matrix.platform }} --log --test ${{ matrix.briefcase-run-args }} -- --ci

    - name: Upload Logs
      uses: actions/upload-artifact@v4.6.0
      if: failure()
      with:
        name: testbed-failure-logs-${{ matrix.backend }}
        path: testbed/logs/*

    - name: Copy App Generated User Data
      if: failure() && matrix.backend != 'android'
      run: |
        mkdir -p testbed/app_data
        cp -r "${{ matrix.app-user-data-path }}" testbed/app_data/testbed-app_data-${{ matrix.backend }}

    - name: Upload App Data
      uses: actions/upload-artifact@v4.6.0
      if: failure() && matrix.backend != 'android'
      with:
        name: testbed-failure-app-data-${{ matrix.backend }}
        path: testbed/app_data/*

    # This step is only needed if you're trying to diagnose test failures that
    # only occur in CI, and can't be reproduced locally. When it runs, it will
    # open an SSH server (URL reported in the logs) so you can ssh into the CI
    # machine.
    # - name: Setup tmate session
    #   uses: mxschmitt/action-tmate@v3
    #   if: failure()