tests.yml

name: Tests

# Called by the top-level CI and nightly workflows
on:
  workflow_call:
    inputs:
      build_type:
        description: Debug or release test build.
        required: false
        type: string
        default: release
      unit_repeat:
        description: Number of times to repeat unit tests.
        required: false
        type: number
        default: 100
      integration_repeat:
        description: Number of times to repeat integration tests.
        required: false
        type: number
        default: 1
      run_stress_tests:
        description: Run stress tests that require LiveKit server setup.
        required: false
        type: boolean
        default: false
      stress_repeat:
        description: Number of times to repeat stress tests.
        required: false
        type: number
        default: 1
      unit_timeout_minutes:
        description: Unit test step timeout in minutes.
        required: false
        type: number
        default: 10
      integration_timeout_minutes:
        description: Integration test step timeout in minutes.
        required: false
        type: number
        default: 10
      stress_timeout_minutes:
        description: Stress test step timeout in minutes.
        required: false
        type: number
        default: 120
      artifact_retention_days:
        description: Test artifact retention in days.
        required: false
        type: number
        default: 7
      run_coverage:
        description: Run the Linux coverage job.
        required: false
        type: boolean
        default: true
  workflow_dispatch:
    inputs:
      build_type:
        description: Debug or release test build.
        required: false
        type: choice
        options:
          - release
          - debug
        default: release
      unit_repeat:
        description: Number of times to repeat unit tests.
        required: false
        type: number
        default: 100
      integration_repeat:
        description: Number of times to repeat integration tests.
        required: false
        type: number
        default: 1
      run_stress_tests:
        description: Run stress tests that require LiveKit server setup.
        required: false
        type: boolean
        default: false
      stress_repeat:
        description: Number of times to repeat stress tests.
        required: false
        type: number
        default: 1
      unit_timeout_minutes:
        description: Unit test step timeout in minutes.
        required: false
        type: number
        default: 10
      integration_timeout_minutes:
        description: Integration test step timeout in minutes.
        required: false
        type: number
        default: 10
      stress_timeout_minutes:
        description: Stress test step timeout in minutes.
        required: false
        type: number
        default: 120
      artifact_retention_days:
        description: Test artifact retention in days.
        required: false
        type: number
        default: 7
      run_coverage:
        description: Run the Linux coverage job.
        required: false
        type: boolean
        default: true

permissions:
  contents: read
  actions: read
  packages: read

env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: full
  # Disable Cargo incremental artifacts. The Rust FFI is built once per
  # submodule SHA and cached whole (see the cargo target cache below), so
  # incremental dirs add nothing but bloat the cached target/ directory and
  # slow the cache upload/download.
  CARGO_INCREMENTAL: "0"
  # vcpkg binary caching for Windows (mirrors builds.yml). The x-gha backend
  # was removed from vcpkg, so use vcpkg's files provider and persist that
  # directory with actions/cache.
  VCPKG_GIT_COMMIT: fb87e2bb3fe69e16c224989acb5a61349166c782
  VCPKG_BINARY_CACHE_DIR: ${{ github.workspace }}/.vcpkg-binary-cache
  VCPKG_BINARY_SOURCES: "clear;files,${{ github.workspace }}/.vcpkg-binary-cache,readwrite"
  VCPKG_DEFAULT_TRIPLET: x64-windows-static-md
  VCPKG_DEFAULT_HOST_TRIPLET: x64-windows-static-md
  VCPKG_TARGET_TRIPLET: x64-windows-static-md

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-22.04
            name: ubuntu-22.04-x64
            e2e-testing: true
          - os: ubuntu-22.04-arm
            name: ubuntu-22.04-arm64
            e2e-testing: true
          - os: ubuntu-24.04
            name: ubuntu-24.04-x64
            e2e-testing: true
          - os: ubuntu-24.04-arm
            name: ubuntu-24.04-arm64
            e2e-testing: true
          - os: macos-26-xlarge
            name: macos-arm64
            e2e-testing: true
          - os: macos-26-large
            name: macos-x64
            macos_arch: x86_64
            e2e-testing: true
          # Pinned to Windows 2022 for current VS 17 implementation
          - os: windows-2022
            name: windows-x64
            e2e-testing: true

    name: Test (${{ matrix.name }})
    runs-on: ${{ matrix.os }}
    env:
      BUILD_DIR: ${{ inputs.build_type == 'debug' && 'build-debug' || 'build-release' }}

    steps:
      - name: Checkout (with submodules)
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          submodules: recursive
          fetch-depth: 1

      - name: Pull LFS files
        run: git lfs pull

      # Cargo's freshness check is mtime-based. A fresh `actions/checkout`
      # stamps every submodule source file with the checkout time, which is
      # newer than the cached target/ artifacts — so cargo rebuilds the whole
      # client-sdk-rust workspace (~6 min) even on an exact cargo-target cache
      # hit. Pin all submodule source files to a fixed, deterministic
      # timestamp (older than any cached artifact) so cargo treats them as
      # unchanged across runs and reuses the cached FFI build. Runs before the
      # cargo target cache is restored, so target/ does not yet exist and is
      # never touched. shell: bash so this also runs under Git Bash on Windows.
      - name: Stabilize Rust source mtimes for cargo freshness
        shell: bash
        run: |
          find client-sdk-rust -type f -not -path '*/.git/*' -exec touch -t 202001010000 {} +

      # ---------- vcpkg for Windows (mirrors builds.yml) ----------
      - name: Restore vcpkg binary cache
        if: runner.os == 'Windows'
        id: cache-vcpkg-binary
        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ${{ env.VCPKG_BINARY_CACHE_DIR }}
          key: ${{ runner.os }}-${{ matrix.name }}-vcpkg-binary-${{ env.VCPKG_TARGET_TRIPLET }}-${{ env.VCPKG_GIT_COMMIT }}-${{ hashFiles('vcpkg.json') }}
          restore-keys: |
            ${{ runner.os }}-${{ matrix.name }}-vcpkg-binary-${{ env.VCPKG_TARGET_TRIPLET }}-${{ env.VCPKG_GIT_COMMIT }}-

      - name: Setup vcpkg (Windows only)
        if: runner.os == 'Windows'
        uses: lukka/run-vcpkg@5e0cab206a5ea620130caf672fce3e4a6b5666a1 # v11.5
        with:
          vcpkgGitCommitId: ${{ env.VCPKG_GIT_COMMIT }}

      # ---------- OS-specific deps ----------
      - name: Install deps (Ubuntu)
        if: runner.os == 'Linux'
        run: |
          set -eux
          sudo apt-get update
          sudo apt-get install -y \
            build-essential cmake ninja-build pkg-config \
            llvm-dev libclang-dev clang \
            libva-dev libdrm-dev libgbm-dev libx11-dev libgl1-mesa-dev \
            libxext-dev libxcomposite-dev libxdamage-dev libxfixes-dev \
            libxrandr-dev libxi-dev libxkbcommon-dev \
            libasound2-dev libpulse-dev \
            libssl-dev \
            libprotobuf-dev protobuf-compiler \
            libabsl-dev \
            libcurl4-openssl-dev \
            libwayland-dev libdecor-0-dev \
            gdb jq

      # The libwebrtc artifact ships a hermetic libc++ built from LLVM trunk.
      # Distro clang (14 on Ubuntu 22.04, 18 on 24.04) cannot compile its
      # headers; the submodule script installs LLVM 21 and exports CC/CXX.
      - name: Install clang for libwebrtc
        if: runner.os == 'Linux'
        shell: bash
        run: client-sdk-rust/.github/scripts/install-clang.sh

      - name: Install deps (macOS)
        if: runner.os == 'macOS'
        run: |
          set -eux
          brew update
          brew install cmake ninja protobuf abseil

      # ---------- Rust toolchain ----------
      - name: Install Rust (stable)
        uses: dtolnay/rust-toolchain@e2a55d2ffb04f378e9626c28d38b36d230d1e12f
        with:
          toolchain: stable

      - name: Install Rust cross-compilation target
        if: matrix.name == 'macos-x64'
        run: rustup target add x86_64-apple-darwin

      # ---------- Cache Cargo ----------
      # See builds.yml for the rationale: the Rust FFI output only changes with
      # the client-sdk-rust submodule commit, so key the target cache on the
      # submodule SHA. Only main pushes save this cache; tests are restore-only
      # to avoid same-key save races and PR-scoped cache churn.
      - name: Resolve Rust submodule SHA
        id: rust_sha
        shell: bash
        run: echo "sha=$(git -C client-sdk-rust rev-parse HEAD)" >> "$GITHUB_OUTPUT"

      - name: Cache cargo registry
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.cargo/registry/index/
            ~/.cargo/registry/cache/
            ~/.cargo/git/db/
          key: ${{ runner.os }}-${{ matrix.name }}-cargo-registry-${{ hashFiles('client-sdk-rust/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-${{ matrix.name }}-cargo-registry-

      # Compiled target/ artifacts are glibc-bound and must not restore across
      # Ubuntu major versions (e.g. 24.04 → 22.04 → GLIBC_2.39 not found).
      - name: Restore cargo target
        id: cache-cargo-target
        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: client-sdk-rust/target/
          key: ${{ matrix.os }}-${{ matrix.name }}-cargo-target-${{ steps.rust_sha.outputs.sha }}
          restore-keys: |
            ${{ matrix.os }}-${{ matrix.name }}-cargo-target-

      # restore-keys can hydrate target/ from a prior submodule SHA. cxxbridge
      # artifacts in webrtc-sys are not compatible across those bumps.
      - name: Drop stale cargo target on submodule SHA cache miss
        if: steps.cache-cargo-target.outputs.cache-hit != 'true'
        shell: bash
        run: rm -rf client-sdk-rust/target/

      # ---------- Build environment setup ----------
      - name: Set Linux build environment
        if: runner.os == 'Linux'
        run: |
          echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
          echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
          LLVM_ROOT="$(dirname "${CXX}")/.."
          test -f "${LLVM_ROOT}/lib/libclang.so"
          echo "LIBCLANG_PATH=${LLVM_ROOT}/lib" >> "$GITHUB_ENV"

      - name: Configure Unix crash diagnostics
        if: runner.os != 'Windows'
        shell: bash
        run: |
          echo "LIVEKIT_CRASH_DIAGNOSTICS=1" >> "$GITHUB_ENV"
          echo "LIVEKIT_CORE_DIR=${RUNNER_TEMP}" >> "$GITHUB_ENV"
          if [[ "$RUNNER_OS" == "Linux" ]]; then
            sudo sysctl -w "kernel.core_pattern=${RUNNER_TEMP}/livekit-core.%p"
          else
            sudo sysctl -w "kern.coredump=1"
            sudo sysctl -w "kern.corefile=${RUNNER_TEMP}/livekit-core.%P"
          fi

      # ---------- Build (tests on, examples off) ----------
      - name: Build tests (Unix)
        if: runner.os != 'Windows'
        shell: bash
        run: |
          set -euo pipefail
          chmod +x build.sh
          build_cmd=(./build.sh "${{ inputs.build_type }}-tests")
          if [[ -n "${{ matrix.macos_arch || '' }}" ]]; then
            build_cmd+=(--macos-arch "${{ matrix.macos_arch }}")
          fi
          "${build_cmd[@]}"

      - name: Build tests (Windows)
        if: runner.os == 'Windows'
        shell: pwsh
        run: .\build.cmd ${{ inputs.build_type }}-tests

      # ---------- Run unit tests ----------
      - name: Run unit tests (Unix)
        if: runner.os != 'Windows'
        timeout-minutes: ${{ inputs.unit_timeout_minutes }}
        shell: bash
        run: |
          bash scripts/run-with-backtrace.sh \
            ${{ env.BUILD_DIR }}/bin/livekit_unit_tests \
            --gtest_repeat=${{ inputs.unit_repeat }} \
            --gtest_brief=1 \
            --gtest_output=xml:${{ env.BUILD_DIR }}/unit-test-results.xml

      - name: Run unit tests (Windows)
        if: runner.os == 'Windows'
        timeout-minutes: ${{ inputs.unit_timeout_minutes }}
        shell: pwsh
        run: |
          ${{ env.BUILD_DIR }}\bin\livekit_unit_tests.exe `
            --gtest_repeat=${{ inputs.unit_repeat }} `
            --gtest_brief=1 `
            --gtest_output="xml:${{ env.BUILD_DIR }}\unit-test-results.xml"

      - name: Start livekit-server
        if: matrix.e2e-testing && (inputs.integration_repeat > 0 || inputs.run_stress_tests)
        id: livekit_server
        uses: livekit/dev-server-action@5d4d5337a875e2d1afd37bed03c601d159dab002 # v1.1.1
        with:
          github-token: ${{ github.token }}
          version: v1.13.3
          config: |
            enable_participant_data_blob: true

      # Needed by token helper script
      - name: Install livekit-cli
        if: matrix.e2e-testing && (inputs.integration_repeat > 0 || inputs.run_stress_tests)
        shell: bash
        env:
          # Windows installs lk via `gh api` / `gh release download`, which need this env var
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euxo pipefail
          if [[ "$RUNNER_OS" == "Linux" ]]; then
            curl -sSL https://get.livekit.io/cli | bash
          elif [[ "$RUNNER_OS" == "macOS" ]]; then
            brew install livekit-cli
          elif [[ "$RUNNER_OS" == "Windows" ]]; then
            install_dir="$RUNNER_TEMP/livekit-cli"
            mkdir -p "$install_dir"
            tag="$(gh api repos/livekit/livekit-cli/releases/latest --jq '.tag_name')"
            gh release download "$tag" \
              --repo livekit/livekit-cli \
              --pattern "*_windows_amd64.zip" \
              --output "$RUNNER_TEMP/lk.zip"
            unzip -o "$RUNNER_TEMP/lk.zip" -d "$install_dir"
            # GITHUB_PATH updates apply to subsequent steps only; export PATH here
            # so lk --version in this step succeeds.
            echo "$install_dir" >> "$GITHUB_PATH"
            export PATH="$install_dir:$PATH"
          else
            echo "::error::Unsupported runner OS for livekit-cli install: ${RUNNER_OS}"
            exit 1
          fi
          lk --version

      - name: Start token server
        if: matrix.e2e-testing && inputs.integration_repeat > 0
        id: token_server
        uses: livekit/token-server-action@a1e42c649a1998d5b224f5102f252c07762024f0 # v0.0.1
        with:
          livekit-url: ws://localhost:7880
          api-key: devkey
          api-secret: secret

      - name: Run integration tests
        if: matrix.e2e-testing && inputs.integration_repeat > 0
        timeout-minutes: ${{ inputs.integration_timeout_minutes }}
        shell: bash
        env:
          RUST_LOG: "metrics=debug"
          LIVEKIT_CREATE_TOKEN_URL: ${{ steps.token_server.outputs.token-url }}
        run: |
          set -euo pipefail
          source scripts/set-test-tokens.sh
          # TODO(BOT-477) Temporarily disable platform audio integration tests in CI until instability is resolved
          bash scripts/run-with-backtrace.sh \
            ${{ env.BUILD_DIR }}/bin/livekit_integration_tests \
            --gtest_filter='-PlatformAudioIntegrationTest.*' \
            --gtest_repeat=${{ inputs.integration_repeat }} \
            --gtest_recreate_environments_when_repeating=1 \
            --gtest_output=xml:${{ env.BUILD_DIR }}/integration-test-results.xml

      - name: Run stress tests
        if: matrix.e2e-testing && inputs.run_stress_tests
        timeout-minutes: ${{ inputs.stress_timeout_minutes }}
        shell: bash
        env:
          RUST_LOG: "metrics=debug"
        run: |
          set -euo pipefail
          source scripts/set-test-tokens.sh
          bash scripts/run-with-backtrace.sh \
            ${{ env.BUILD_DIR }}/bin/livekit_stress_tests \
            --gtest_repeat=${{ inputs.stress_repeat }} \
            --gtest_recreate_environments_when_repeating=1 \
            --gtest_output=xml:${{ env.BUILD_DIR }}/stress-test-results.xml

      - name: Dump livekit-server log on failure
        if: failure() && matrix.e2e-testing && (inputs.integration_repeat > 0 || inputs.run_stress_tests)
        shell: bash
        run: tail -n 500 "${{ steps.livekit_server.outputs.log-path }}" || true

      - name: Dump token server log on failure
        if: failure() && matrix.e2e-testing && steps.token_server.outputs.log-path != ''
        shell: bash
        run: tail -n 200 "${{ steps.token_server.outputs.log-path }}" || true

      # ---------- Upload results ----------
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: test-results-${{ matrix.name }}
          path: |
            ${{ env.BUILD_DIR }}/unit-test-results.xml
            ${{ env.BUILD_DIR }}/integration-test-results.xml
            ${{ env.BUILD_DIR }}/stress-test-results.xml
            ${{ steps.livekit_server.outputs.log-path }}
          if-no-files-found: ignore
          retention-days: ${{ inputs.artifact_retention_days }}

  # ============================================================================
  # Code Coverage (Linux only)
  # Runs a debug build through gcov and generates an inline action summary
  # alongside an HTML report. Unit and integration tests both execute against
  # that build so their .gcda data is included in the same report.
  # ============================================================================
  coverage:
    name: Code Coverage
    if: inputs.run_coverage
    runs-on: ubuntu-24.04
    # A debug build instrumented with --coverage is far heavier (RAM + disk)
    # than the release builds. Cap the wall-clock so a stuck/OOM build fails
    # fast and visibly instead of hanging toward the 6h default. The extra
    # time beyond the build covers the integration server and test run.
    timeout-minutes: 60

    steps:
      - name: Checkout (with submodules)
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          submodules: recursive
          fetch-depth: 1

      - name: Pull LFS files
        run: git lfs pull

      # Reclaim ~30GB on the runner. The debug+coverage object tree plus gcov
      # data is large; prior runs died mid-build from disk/memory pressure.
      - name: Free disk space
        uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # v2.0.0
        with:
          tool-cache: false
          android: true
          dotnet: true
          haskell: true
          large-packages: true
          docker-images: true
          swap-storage: false

      # ---------- OS deps ----------
      - name: Install deps
        run: |
          set -eux
          sudo apt-get update
          sudo apt-get install -y \
            build-essential cmake ninja-build pkg-config \
            llvm-dev libclang-dev clang \
            libva-dev libdrm-dev libgbm-dev libx11-dev libgl1-mesa-dev \
            libxext-dev libxcomposite-dev libxdamage-dev libxfixes-dev \
            libxrandr-dev libxi-dev libxkbcommon-dev \
            libasound2-dev libpulse-dev \
            libssl-dev \
            libprotobuf-dev protobuf-compiler \
            libabsl-dev \
            libcurl4-openssl-dev \
            libwayland-dev libdecor-0-dev
          pip install --break-system-packages gcovr

      # The coverage build compiles the Rust FFI too, so it needs the same
      # compiler floor as the normal Linux build/test matrices.
      - name: Install clang for libwebrtc
        shell: bash
        run: client-sdk-rust/.github/scripts/install-clang.sh

      # ---------- Rust toolchain ----------
      - name: Install Rust (stable)
        uses: dtolnay/rust-toolchain@e2a55d2ffb04f378e9626c28d38b36d230d1e12f
        with:
          toolchain: stable

      # ---------- Cache Cargo ----------
      # Only the cargo registry (downloaded crate sources, ~60 MB) is cached
      # here. The compiled target/ is intentionally not cached for coverage —
      # see the note below the registry cache step.
      - name: Cache cargo registry
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.cargo/registry/index/
            ~/.cargo/registry/cache/
            ~/.cargo/git/db/
          key: ${{ runner.os }}-coverage-cargo-registry-${{ hashFiles('client-sdk-rust/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-coverage-cargo-registry-

      # NOTE: we deliberately do NOT cache client-sdk-rust/target/ here. The
      # coverage job builds the FFI in debug mode, so its target/ was ~2.8 GB —
      # the single largest entry in the repo's 10 GB Actions cache budget. That
      # one cache crowded out the release build/test caches (and the Windows
      # vcpkg binaries), causing repo-wide LRU eviction and cold rebuilds
      # elsewhere. Coverage runs once per PR off the critical path, so eating a
      # cold FFI build here is cheaper than the eviction it caused. The cargo
      # registry cache above is tiny (~60 MB) and stays.

      # ---------- Build environment setup ----------
      - name: Set build environment
        run: |
          LLVM_ROOT="$(dirname "${CXX}")/.."
          test -f "${LLVM_ROOT}/lib/libclang.so"
          LLVM_COV="${LLVM_ROOT}/bin/llvm-cov"
          test -x "${LLVM_COV}"
          echo "LIBCLANG_PATH=${LLVM_ROOT}/lib" >> "$GITHUB_ENV"
          echo "GCOV_EXECUTABLE=${LLVM_COV} gcov" >> "$GITHUB_ENV"

      # ---------- Configure with upstream preset + coverage flag overrides ----------
      - name: Configure (linux-debug-tests preset + coverage flags)
        run: |
          cmake --preset linux-debug-tests \
            -DCMAKE_C_FLAGS="-Wno-deprecated-declarations --coverage" \
            -DCMAKE_CXX_FLAGS="-Wno-deprecated-declarations --coverage" \
            -DCMAKE_EXE_LINKER_FLAGS="--coverage" \
            -DCMAKE_SHARED_LINKER_FLAGS="--coverage"

      # Cap parallelism: a debug build with --coverage instrumentation has a
      # much larger per-TU memory footprint, and unbounded --parallel (one job
      # per core) is what OOM-killed prior runs (failure surfaced only as an
      # abandoned "Build" step). 2 keeps peak RAM in check on the standard
      # runner; bump if/when this moves to a larger runner.
      - name: Build
        run: cmake --build build-debug --parallel 2

      # ---------- Run unit and integration tests ----------
      # Both binaries write .gcda for the instrumented liblivekit, so running
      # them in sequence produces one combined coverage report.
      - name: Run unit tests
        timeout-minutes: 5
        run: |
          build-debug/bin/livekit_unit_tests \
            --gtest_output=xml:build-debug/unit-test-results.xml

      - name: Start livekit-server
        if: inputs.integration_repeat > 0
        id: livekit_server
        uses: livekit/dev-server-action@5d4d5337a875e2d1afd37bed03c601d159dab002 # v1.1.1
        with:
          github-token: ${{ github.token }}
          version: v1.13.3
          config: |
            enable_participant_data_blob: true

      - name: Install livekit-cli
        if: inputs.integration_repeat > 0
        run: |
          set -euxo pipefail
          curl -sSL https://get.livekit.io/cli | bash
          lk --version

      - name: Start token server
        if: inputs.integration_repeat > 0
        id: token_server
        uses: livekit/token-server-action@a1e42c649a1998d5b224f5102f252c07762024f0 # v0.0.1
        with:
          livekit-url: ws://localhost:7880
          api-key: devkey
          api-secret: secret

      - name: Run integration tests
        if: inputs.integration_repeat > 0
        timeout-minutes: ${{ inputs.integration_timeout_minutes }}
        env:
          RUST_LOG: "metrics=debug"
          LIVEKIT_CREATE_TOKEN_URL: ${{ steps.token_server.outputs.token-url }}
        run: |
          set -euo pipefail
          source scripts/set-test-tokens.sh
          # TODO(BOT-477) Temporarily disable platform audio integration tests in CI until instability is resolved
          bash scripts/run-with-backtrace.sh \
            build-debug/bin/livekit_integration_tests \
            --gtest_filter='-PlatformAudioIntegrationTest.*' \
            --gtest_output=xml:build-debug/integration-test-results.xml

      - name: Dump livekit-server log on failure
        if: failure() && steps.livekit_server.outputs.log-path != ''
        run: tail -n 500 "${{ steps.livekit_server.outputs.log-path }}" || true

      - name: Dump token server log on failure
        if: failure() && steps.token_server.outputs.log-path != ''
        run: tail -n 200 "${{ steps.token_server.outputs.log-path }}" || true

      # Make resource-exhaustion failures visible instead of silent. Runs only
      # if an earlier step failed (e.g. OOM during Build).
      - name: Diagnostics on failure
        if: failure()
        run: |
          echo "===== disk ====="; df -h || true
          echo "===== memory ====="; free -h || true
          echo "===== dmesg (OOM killer) ====="
          sudo dmesg 2>/dev/null | grep -iE 'killed process|out of memory|oom' | tail -20 || true

      # ---------- Generate coverage reports ----------
      - name: Generate coverage reports
        if: (success() || failure()) && hashFiles('build-debug/**/*.gcda') != ''
        run: |
          mkdir -p coverage-html
          gcovr build-debug \
            --root . \
            --gcov-executable "${GCOV_EXECUTABLE}" \
            --gcov-ignore-parse-errors=all \
            --filter 'include/' \
            --filter 'src/' \
            --exclude 'src/tests/' \
            --exclude '.*\.pb\.' \
            --exclude-unreachable-branches \
            --exclude-throw-branches \
            --cobertura coverage.xml \
            --html-details coverage-html/index.html \
            --txt coverage-summary.txt

      - name: Add coverage summary to job
        if: (success() || failure()) && hashFiles('coverage-summary.txt') != ''
        run: |
          {
            echo '## Code Coverage Summary'
            echo ''
            echo '```'
            cat coverage-summary.txt
            echo '```'
            echo ''
            echo '*Full HTML report available in the **coverage-report** artifact.*'
          } >> "$GITHUB_STEP_SUMMARY"

      # ---------- Upload reports ----------
      - name: Upload coverage HTML report
        if: always()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: coverage-report
          path: coverage-html/
          retention-days: 14