pytest-debug.yaml

# Copyright 2025 The Cirq Developers
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# GitHub workflow for manually running pytest with debug flags.
#
# This workflow can only be executed manually, e.g., using the "Run workflow"
# button on https://github.com/quantumlib/Cirq/actions/workflows/debug.yaml
# Clicking the "Run workflow" button there will present a form interface with
# various options for the characteristics of the run.
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

name: Run pytest with debug options

on:
  workflow_dispatch:
    inputs:
      py-version:
        description: "Python version:"
        type: choice
        default: "3.12"
        options:
          - "3.13"
          - "3.12"
          - "3.11"
          - "3.10"

      os:
        description: "Runner OS:"
        type: choice
        default: ubuntu-22.04
        options:
          - ubuntu-22.04
          - ubuntu-20.04
          - macos-15
          - macos-14
          - macos-13
          - windows-2025
          - windows-2022
          - windows-2019

      arch:
        description: "Hardware architecture:"
        type: choice
        default: x64
        options:
          - x64
          - arm64

      single-test:
        description: "Run specific single test:"
        type: string
        default: ""

      repetitions:
        description: "Number of repetitions:"
        type: number
        default: 1

      random-seed:
        description: "Explicit random seed:"
        type: number

      multiple-workers:
        description: "Use multiple pytest workers"
        type: boolean
        default: true

      verbose:
        description: "Turn on verbose tracing"
        type: boolean
        default: false

      exit-first:
        description: "Stop at first error"
        type: boolean
        default: true

      include-rigetti:
        description: "Include rigetti module"
        type: boolean
        default: false

run-name: |
  Pytest ${{inputs.single-test || '(all tests)' }} on ${{inputs.os}}
  ${{inputs.arch}} with Python ${{inputs.py-version}}

# Declare default permissions as read only.
permissions: read-all

jobs:
  pytest:
    name: Run pytest
    runs-on: ${{github.event.inputs.os}}
    steps:
      - name: Do miscellaneous preliminary configuration steps
        run: |
          mkdir -p ~/.cache/pip

      - name: Check out a copy of the Cirq git repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

      - name: Set up Python
        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5
        with:
          python-version: ${{github.event.inputs.py-version}}
          architecture: ${{github.event.inputs.arch}}
          cache: pip
          cache-dependency-path: |
            dev_tools/requirements/*.txt
            dev_tools/requirements/deps/*.txt

      - name: Install Python requirements
        run: |
          set -e
          requirements="dev_tools/requirements/dev.env.txt"
          pip install --upgrade pip setuptools wheel
          pip install --upgrade --upgrade-strategy eager -r "$requirements"

      - name: Start Quil dependencies if needed
        if: inputs.include-rigetti == true || inputs.include-rigetti == 'true'
        run: docker compose -f cirq-rigetti/docker-compose.test.yaml up -d

      - name: Run pytest
        run: |
          # Configure flags for pytest.
          flags="--durations=20 --strict-config --ignore=cirq-core/cirq/contrib"
          workers="-n auto"
          if [[ -n "${{github.event.inputs.random-seed}}" ]]; then
            flags=" --randomly-seed=${{github.event.inputs.random-seed}}"
          fi
          if [[ "${{github.event.inputs.multiple-workers}}" == "false" ]]; then
            workers="-n0"
          fi
          if [[ "${{github.event.inputs.verbose}}" == "true" ]]; then
            flags+="-vv --full-trace --setup-show"
            # Save Python info to the run log, in case it's useful.
            which python
            pip list
          fi
          if [[ "${{github.event.inputs.include-rigetti}}" == true ]]; then
            flags+=" --rigetti-integration"
          fi
          if [[ "${{github.event.inputs.exit-first}}" == "true" ]]; then
            flags+=" --exitfirst"
            set -e
          fi
          # Now finally run pytest, as many times as requested.
          for i in $(seq 1 ${{github.event.inputs.repetitions}}); do
            echo ""
            echo -n "︎▞▚▞ Iteration $i ▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚"
            echo    "▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞"
            echo ""
            check/pytest $workers $flags ${{github.event.inputs.single-test}}
          done

      - name: Stop Quil dependencies if needed
        if: inputs.include-rigetti == true || inputs.include-rigetti == 'true'
        run: docker compose -f cirq-rigetti/docker-compose.test.yaml down