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:
      pre-commit-source: "./core[dev]"

  towncrier:
    name: Check towncrier
    uses: beeware/.github/.github/workflows/towncrier-run.yml@main
    with:
      tox-source: "./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"
        - "textual"
        - "web"
        - "winforms"
    uses: beeware/.github/.github/workflows/python-package-create.yml@main
    with:
      build-subdirectory: ${{ matrix.subdir }}
      attest: ${{ inputs.attest-package }}

  core:
    name: Test core
    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" ]
        include:
        - experimental: false

    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.3.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: core

    - 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
        TOGA_INSTALL_COMMAND="python -m pip install ../$(ls dist/toga_core-*.whl)[dev] ../$(ls dist/toga_dummy-*.whl)" \
          tox -e py-cov
        tox -qe coverage$(tr -dc "0-9" <<< "${{ matrix.python-version }}")
        mv core/.coverage core/.coverage.${{ matrix.platform }}.${{ matrix.python-version }}

    - name: Store Coverage Data
      uses: actions/upload-artifact@v4.4.3
      with:
        name: core-coverage-data-${{ matrix.platform }}-${{ matrix.python-version }}
        path: "core/.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.3.0
        with:
          python-version: "3.13"

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

      - name: Test
        run: |
          pip install 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"

          echo "Stable Travertino"
          ${{ steps.micropython.outputs.executable }} micropython_check.py

          echo "Development Travertino"
          pip install git+https://github.com/beeware/travertino
          ${{ steps.micropython.outputs.executable }} micropython_check.py

  core-coverage:
    name: Coverage
    needs: core
    runs-on: ubuntu-latest
    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.3.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: core

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

    - name: Generate Coverage Report
      run: tox -e coverage-html-fail-platform

    - name: Upload HTML Coverage Report
      uses: actions/upload-artifact@v4.4.3
      if: failure()
      with:
        name: html-coverage-report
        path: core/htmlcov

  testbed:
    name: Testbed
    needs: core
    runs-on: ${{ matrix.runs-on }}
    strategy:
      fail-fast: false
      matrix:
        backend:
        - "macOS-x86_64"
        - "macOS-arm64"
        - "windows"
        - "linux-x11"
        - "linux-wayland"
        - "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"
          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"
          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 is not compatible with Gtk
            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: "textual-linux"
          platform: "linux"
          runs-on: "ubuntu-latest"
          setup-python: false  # Use the system Python packages
          briefcase-run-args: --config 'requires=["../core","../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=["../core","../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=["../core","../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.3.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: 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.4.3
      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.4.3
      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()