Draft - Integration tests in CI

.github/workflows/builds.yml

@@ -65,23 +65,27 @@ jobs:
         include:
           - os: ubuntu-latest
             name: linux-x64
-            build_cmd: ./build.sh release-all
+            build_cmd: ./build.sh release-examples
             build_dir: build-release
           - os: ubuntu-24.04-arm
             name: linux-arm64
-            build_cmd: ./build.sh release-all
+            build_cmd: ./build.sh release-examples
             build_dir: build-release
-          - os: macos-latest
+          # macos-latest currently maps to a lower-spec 3-core/7GB arm64 image;
+          # macos-26 gives us 4 cores/14GB on the standard free runner tier.
+          - os: macos-26
             name: macos-arm64
-            build_cmd: ./build.sh release-all
+            build_cmd: ./build.sh release-examples
             build_dir: build-release
-          - os: macos-latest
+          # Use the explicit Intel image for x64 with the same 4-core/14GB profile
+          # instead of cross-building on the lower-spec macos-latest arm64 runner.
+          - os: macos-26-intel
             name: macos-x64
-            build_cmd: ./build.sh release-all --macos-arch x86_64
+            build_cmd: ./build.sh release-examples --macos-arch x86_64
             build_dir: build-release
           - os: windows-latest
             name: windows-x64
-            build_cmd: .\build.cmd release-all
+            build_cmd: .\build.cmd release-examples
             build_dir: build-release
 
     name: Build (${{ matrix.name }})
@@ -149,22 +153,10 @@ jobs:
         run: rustup target add x86_64-apple-darwin
 
       # ---------- Cache Cargo ----------
-      - name: Cache Cargo registry
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
         with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-          key: ${{ runner.os }}-${{ matrix.name }}-cargo-reg-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: ${{ runner.os }}-${{ matrix.name }}-cargo-reg-
-
-      - name: Cache Cargo target
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: client-sdk-rust/target
-          key: ${{ runner.os }}-${{ matrix.name }}-cargo-target-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ matrix.name }}-cargo-target-
+          workspaces: client-sdk-rust -> target
 
       # ---------- Build environment setup ----------
       - name: Set Linux build environment
@@ -288,29 +280,6 @@ jobs:
           }
           if ($failed) { exit 1 } else { exit 0 }
 
-      # ---------- Run unit tests ----------
-      - name: Run unit tests (Unix)
-        if: runner.os != 'Windows'
-        shell: bash
-        run: |
-          ${{ matrix.build_dir }}/bin/livekit_unit_tests \
-            --gtest_output=xml:${{ matrix.build_dir }}/unit-test-results.xml
-
-      - name: Run unit tests (Windows)
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          & "${{ matrix.build_dir }}/bin/livekit_unit_tests.exe" `
-            --gtest_output=xml:${{ matrix.build_dir }}/unit-test-results.xml
-
-      - name: Upload test results
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: test-results-${{ matrix.name }}
-          path: ${{ matrix.build_dir }}/unit-test-results.xml
-          retention-days: 7
-
       # ---------- Upload artifacts ----------
       - name: Upload build artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

.github/workflows/tests.yml

@@ -0,0 +1,205 @@
+name: Tests
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - src/**
+      - include/**
+      - client-sdk-rust/**
+      - CMakeLists.txt
+      - CMakePresets.json
+      - build.sh
+      - build.cmd
+      - vcpkg.json
+      - .token_helpers/**
+      - .github/workflows/tests.yml
+  pull_request:
+    branches: ["main"]
+    paths:
+      - src/**
+      - include/**
+      - client-sdk-rust/**
+      - CMakeLists.txt
+      - CMakePresets.json
+      - build.sh
+      - build.cmd
+      - vcpkg.json
+      - .token_helpers/**
+      - .github/workflows/tests.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+  packages: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: linux-x64
+          - os: ubuntu-24.04-arm
+            name: linux-arm64
+          # macos-latest currently maps to a lower-spec 3-core/7GB arm64 image;
+          # macos-26 gives us 4 cores/14GB on the standard free runner tier.
+          - os: macos-26
+            name: macos-arm64
+
+    name: Test (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+          fetch-depth: 1
+
+      - name: Pull LFS files
+        run: git lfs pull
+
+      # ---------- 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 \
+            libwayland-dev libdecor-0-dev \
+            libspdlog-dev \
+            jq
+
+      - name: Install deps (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          set -eux
+          brew update
+          brew install cmake ninja protobuf abseil spdlog jq
+
+      # ---------- Rust toolchain ----------
+      - name: Install Rust (stable)
+        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+        with:
+          toolchain: stable
+
+      # ---------- Cache Cargo ----------
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: 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_VERSION=$(llvm-config --version | cut -d. -f1)
+          echo "LIBCLANG_PATH=/usr/lib/llvm-${LLVM_VERSION}/lib" >> $GITHUB_ENV
+
+      # ---------- Build (release-tests: tests on, examples off) ----------
+      - name: Build tests
+        shell: bash
+        run: |
+          chmod +x build.sh
+          ./build.sh release-tests
+
+      # ---------- Run unit tests ----------
+      - name: Run unit tests
+        timeout-minutes: 1
+        shell: bash
+        run: |
+          build-release/bin/livekit_unit_tests \
+            --gtest_output=xml:build-release/unit-test-results.xml
+
+      # ---------- Install + start livekit-server for integration tests ----------
+      - name: Install livekit-server and lk CLI
+        shell: bash
+        run: |
+          set -euxo pipefail
+          if [[ "$RUNNER_OS" == "Linux" ]]; then
+            # Linux: official install scripts. lk's installer parses the GitHub
+            # API JSON with jq (already installed above).
+            curl -sSL https://get.livekit.io | bash
+            curl -sSL https://get.livekit.io/cli | bash
+          else
+            # macOS: Homebrew formulas. Server install script aborts on Darwin.
+            brew install livekit livekit-cli
+          fi
+          livekit-server --version
+          lk --version
+
+      - name: Start livekit-server
+        shell: bash
+        env:
+          LIVEKIT_CONFIG: "enable_data_tracks: true"
+        run: |
+          set -euxo pipefail
+          # Background the server with nohup so it survives this step's shell
+          # exit and remains running for the integration-test step.
+          nohup livekit-server --dev > livekit-server.log 2>&1 &
+          echo $! > livekit-server.pid
+          # Port 7880 is a WebSocket endpoint, so a TCP-connect probe is the
+          # most reliable readiness signal.
+          for i in $(seq 1 30); do
+            if nc -z 127.0.0.1 7880 >/dev/null 2>&1; then
+              echo "livekit-server is ready"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "::error::livekit-server failed to start within 30s"
+          tail -n 200 livekit-server.log || true
+          exit 1
+
+      - name: Run integration tests
+        timeout-minutes: 5
+        shell: bash
+        run: |
+          set -euo pipefail
+          source .token_helpers/set_data_track_test_tokens.bash
+          build-release/bin/livekit_integration_tests \
+            --gtest_output=xml:build-release/integration-test-results.xml
+
+      - name: Stop livekit-server
+        if: always()
+        shell: bash
+        run: |
+          if [ -f livekit-server.pid ]; then
+            kill "$(cat livekit-server.pid)" 2>/dev/null || true
+            rm -f livekit-server.pid
+          fi
+
+      - name: Dump livekit-server log on failure
+        if: failure()
+        shell: bash
+        run: tail -n 500 livekit-server.log || true
+
+      # ---------- Upload results ----------
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: test-results-${{ matrix.name }}
+          path: |
+            build-release/unit-test-results.xml
+            build-release/integration-test-results.xml
+            livekit-server.log
+          if-no-files-found: ignore
+          retention-days: 7

.token_helpers/README.md

@@ -5,4 +5,7 @@ Examples of generating tokens
 Generate tokens and then set them as env vars for the current terminal session
 
 ## set_data_track_test_tokens.bash
-Generate tokens for data track integration tests and set them as env vars for the current terminal session.
+Generate the two participant tokens required by the C++ SDK's integration
+and stress test suites (data tracks, RPC, media multistream, etc.) and
+export them as `LK_TOKEN_TEST_A`, `LK_TOKEN_TEST_B`, and `LIVEKIT_URL` for
+the current terminal session.

.token_helpers/set_data_track_test_tokens.bash

@@ -14,10 +14,11 @@
 # limitations under the License.
 
 # Generate two LiveKit access tokens via `lk` and set the environment variables
-# required by src/tests/integration/test_data_track.cpp.
+# required by the C++ SDK's integration and stress tests (data tracks, RPC,
+# media multistream, etc.).
 #
-#   source examples/tokens/set_data_track_test_tokens.bash
-#   eval "$(bash examples/tokens/set_data_track_test_tokens.bash)"
+#   source .token_helpers/set_data_track_test_tokens.bash
+#   eval "$(bash .token_helpers/set_data_track_test_tokens.bash)"
 #
 # Exports:
 #   LK_TOKEN_TEST_A
@@ -47,8 +48,6 @@ fi
 LIVEKIT_ROOM="cpp_data_track_test"
 LIVEKIT_IDENTITY_A="cpp-test-a"
 LIVEKIT_IDENTITY_B="cpp-test-b"
-LIVEKIT_CALLER_IDENTITY="caller"
-LIVEKIT_RECEIVER_IDENTITY="receiver"
 
 if [[ $# -ne 0 ]]; then
   _fail "this script is hard-coded and does not accept arguments" 2
@@ -106,27 +105,22 @@ _create_token() {
 
 LK_TOKEN_TEST_A="$(_create_token "$LIVEKIT_IDENTITY_A")"
 LK_TOKEN_TEST_B="$(_create_token "$LIVEKIT_IDENTITY_B")"
-LIVEKIT_CALLER_TOKEN="$(_create_token "$LIVEKIT_CALLER_IDENTITY")"
-LIVEKIT_RECEIVER_TOKEN="$(_create_token "$LIVEKIT_RECEIVER_IDENTITY")"
+
 _apply() {
   export LK_TOKEN_TEST_A
   export LK_TOKEN_TEST_B
-  export LIVEKIT_CALLER_TOKEN
-  export LIVEKIT_RECEIVER_TOKEN
   export LIVEKIT_URL
 }
 
 _emit_eval() {
   printf 'export LK_TOKEN_TEST_A=%q\n' "$LK_TOKEN_TEST_A"
   printf 'export LK_TOKEN_TEST_B=%q\n' "$LK_TOKEN_TEST_B"
-  printf 'export LIVEKIT_CALLER_TOKEN=%q\n' "$LIVEKIT_CALLER_TOKEN"
-  printf 'export LIVEKIT_RECEIVER_TOKEN=%q\n' "$LIVEKIT_RECEIVER_TOKEN"
   printf 'export LIVEKIT_URL=%q\n' "$LIVEKIT_URL"
 }
 
 if [[ "$_sourced" -eq 1 ]]; then
   _apply
-  echo "LK_TOKEN_TEST_A, LK_TOKEN_TEST_B, LIVEKIT_CALLER_TOKEN, LIVEKIT_RECEIVER_TOKEN, and LIVEKIT_URL set for this shell." >&2
+  echo "LK_TOKEN_TEST_A, LK_TOKEN_TEST_B, and LIVEKIT_URL set for this shell." >&2
 else
   _emit_eval
   echo "set_data_track_test_tokens.bash: for this shell run: source $0   or: eval \"\$(bash $0 ...)\"" >&2

AGENTS.md

@@ -107,6 +107,9 @@ Updates to ./build.sh and ./build.cmd should be accompanied by updates to this f
 ./build.sh clean-all          # Full clean (C++ + Rust targets)
 ```
 
+The build scripts pass an explicit job count to `cmake --build --parallel`. Set
+`CMAKE_BUILD_PARALLEL_LEVEL` to override the default detected logical CPU count.
+
 **Requirements:** CMake 3.20+, C++17, Rust toolchain (cargo), protoc. On macOS: `brew install cmake ninja protobuf abseil spdlog`. On Linux: see the CI workflow for apt packages.
 
 ### SDK Packaging