test-python-bindings.yml

name: Test Python Bindings

# The matrix runs when code changes: the same surface the upstream pull-request branch ships (src, tests, examples, scripts, pyproject.toml, setup.py).
# Documentation, READMEs and agent files do not start it; see "Documentation Development" for what to run by hand, and the release workflow runs everything.
on:
  # Run on push to bindings/python/ directory, on main only: the upstream-main
  # mirror branch that sync-upstream.sh maintains (locally; the script does not
  # push it) is upstream's tree without our fixes, and running our checks on it
  # if it is pushed only produces red runs nobody acts on.
  push:
    branches:
      - main
    paths:
      - 'bindings/python/src/**'
      - 'bindings/python/tests/**'
      - 'bindings/python/deprecation/**'
      - 'bindings/python/examples/**'
      - 'bindings/python/scripts/**'
      - 'bindings/python/pyproject.toml'
      - 'bindings/python/setup.py'
      - '.github/workflows/test-python-bindings.yml'

  # Run on pull request affecting bindings/python/
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths:
      - 'bindings/python/src/**'
      - 'bindings/python/tests/**'
      - 'bindings/python/deprecation/**'
      - 'bindings/python/examples/**'
      - 'bindings/python/scripts/**'
      - 'bindings/python/pyproject.toml'
      - 'bindings/python/setup.py'
      - '.github/workflows/test-python-bindings.yml'

  # Allow being called by other workflows (e.g., release workflow)
  workflow_call:
    inputs:
      build-version:
        description: "Override package version (PEP 440) for build.sh"
        required: false
        type: string
      engine-from-source:
        description: "Build the engine jars from this commit's source (the package module) instead of downloading the jars of the arcadedata/arcadedb image that pom.xml names. Off for a caller that does not set it, so the release workflow keeps its jars."
        required: false
        type: boolean
        default: false

  # Allow manual trigger
  workflow_dispatch:
    inputs:
      engine-from-source:
        description: "Build the engine jars from this commit's source (the package module). Turn off to download the jars of the arcadedata/arcadedb image that pom.xml names (upstream's moving snapshot between releases) instead."
        required: false
        type: boolean
        default: true

# A newer push to a pull request supersedes the run of the commit before it: without this each push starts another
# full matrix next to the one still running. Scoped to pull_request only, so a push to main keeps its run as the
# record for that commit (same rule as test-python-examples.yml).
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

# A draft pull request skips every job below (the matrix is the expensive part); marking it ready for review
# starts the run (`ready_for_review` in the trigger types). Pushes to main, manual dispatch and the release
# workflow's call are never drafts, so they always run.
permissions:
  contents: read

jobs:
  bandit:
    name: Bandit security scan (bindings/python)
    runs-on: ubuntu-24.04
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    timeout-minutes: 15
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      - name: Setup UV package manager
        shell: bash
        run: |
          # Retry transient network failures (a connection reset failed a whole examples job on #8897); the
          # script is downloaded first so a retried transfer is never piped half-written into sh.
          installer="$(mktemp)"
          curl -LsSf --retry 5 --retry-all-errors --retry-delay 5 -o "$installer" https://astral.sh/uv/0.12.0/install.sh
          sh "$installer"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          export PATH="$HOME/.local/bin:$PATH"
          uv --version

      - name: Run Bandit on src and tests (must be clean)
        working-directory: bindings/python
        run: uvx "bandit==1.9.4" -c pyproject.toml -r src tests --severity-level low --confidence-level low

      - name: Run Bandit on examples (must be clean at medium+/high-confidence)
        working-directory: bindings/python
        run: uvx "bandit==1.9.4" -c pyproject.toml -r examples --severity-level medium --confidence-level high

  # Meterian cannot scan this folder: `uv lock` refuses on a project carrying
  # `[tool.uv] managed = false`, so it produces no lockfile to read (see #5616).
  # This audits the dependency floors declared in pyproject.toml instead.
  dependency-floors:
    name: Dependency floor audit (bindings/python)
    runs-on: ubuntu-24.04
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    timeout-minutes: 15
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      # Every uv install in these workflows is pinned to this version, so a uv release never changes a run
      # by itself; this job's own output also depends on how uv resolves, so a silent resolver change would
      # silently change what gets audited. Raise the pin in all of them together.
      - name: Setup UV package manager
        shell: bash
        run: |
          # Retry transient network failures (a connection reset failed a whole examples job on #8897); the
          # script is downloaded first so a retried transfer is never piped half-written into sh.
          installer="$(mktemp)"
          curl -LsSf --retry 5 --retry-all-errors --retry-delay 5 -o "$installer" https://astral.sh/uv/0.12.0/install.sh
          sh "$installer"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          export PATH="$HOME/.local/bin:$PATH"
          uv --version

      # resolution = "lowest-direct" pins every declared dependency to the oldest
      # release its own constraint admits, which is the version this manifest
      # actually promises to work with. The default resolution would pick the
      # newest instead, and a floor left open to a vulnerable release would
      # never show up.
      #
      # The dev extra is excluded on purpose: black, isort, mypy and pytest-cov
      # declare no lower bound, so lowest-direct drops them onto their earliest
      # PyPI releases (mypy 0.1, which pulls Python 2-era sdists that fail to
      # build). It is contributor tooling and is never installed from the wheel.
      #
      # Every interpreter the package claims to support is resolved, because the
      # closure is interpreter-dependent even though the declared floors are not:
      # an older interpreter pulls backports (typing-extensions, for one) that a
      # newer one does not, and 3.14 drops one more. A `requires-python` of
      # `==<version>.*` selects the resolution target without installing
      # anything, so this stays one job rather than a matrix.
      # The list is read from the classifiers rather than repeated here, so adding
      # an interpreter to the package cannot leave it unaudited.
      #
      # uv's pip-compatible compile is not used: this pyproject is `managed = false`, so
      # `uv lock` refuses it. Instead the declared dependencies and the same extras
      # are written into a PEP 723 script header, which `uv lock --script` and
      # `uv export --script` resolve and print as pinned requirements. The export
      # is universal, so it also lists the packages other platforms pull in
      # (colorama, cffi, ...), which the old per-host compile left out.
      #
      # --disable-pip reads the pinned file directly rather than asking pip to
      # resolve it. Without it, a floor whose version has no wheel for the
      # running interpreter fails as an sdist build error instead of reporting
      # the advisory that caused the regression.
      - name: Audit declared dependency floors on every supported interpreter
        working-directory: bindings/python
        run: |
          # The trailing dot in the prefix is load-bearing: the classifiers also
          # carry a bare "Programming Language :: Python :: 3", which without it
          # yields a requires-python of ==3.* and fails.
          versions=$(python -c 'import tomllib;p="Programming Language :: Python :: 3.";print(" ".join(c.rsplit(" ",1)[1] for c in tomllib.load(open("pyproject.toml","rb"))["project"]["classifiers"] if c.startswith(p)))')
          # No classifiers would audit nothing and still pass, which is the kind
          # of silent gap this job exists to close.
          [ -n "$versions" ] || { echo "no Python version classifiers found in pyproject.toml"; exit 1; }
          echo "auditing declared floors for: $versions"
          for v in $versions; do
            echo "::group::Resolve floors for Python $v"
            script="$RUNNER_TEMP/floors-$v.py"
            python - "$v" > "$script" <<'PY'
          import json, sys, tomllib
          project = tomllib.load(open("pyproject.toml", "rb"))["project"]
          deps = list(project["dependencies"])
          for extra in ("test", "vector", "examples", "arrow", "pandas"):
              deps += project["optional-dependencies"][extra]
          print("# /// script")
          print(f'# requires-python = "=={sys.argv[1]}.*"')
          print("# dependencies = [")
          for dep in deps:
              print(f"#   {json.dumps(dep)},")
          print("# ]")
          print("# [tool.uv]")
          print('# resolution = "lowest-direct"')
          print("# ///")
          PY
            uv lock --script "$script"
            uv export --script "$script" --no-hashes --no-annotate --no-header -o "$RUNNER_TEMP/floors-$v.txt"
            cat "$RUNNER_TEMP/floors-$v.txt"
            echo "::endgroup::"
            uvx "pip-audit==2.10.1" --no-deps --disable-pip -r "$RUNNER_TEMP/floors-$v.txt"
          done

  # First job: Download ArcadeDB JARs (platform-agnostic)
  download-jars:
    name: Download ArcadeDB JARs
    runs-on: ubuntu-24.04
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    timeout-minutes: 90
    outputs:
      engine-from-source: ${{ steps.mode.outputs.engine-from-source }}
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      # WHICH ENGINE THE TESTS RUN ON. A push, a pull request and a manual dispatch test the engine built from this
      # commit's source: the jars of upstream's moving snapshot image can carry fixes this repository's source does
      # not have yet (five strict-xfail tripwires fired on 2026-10-04 for that reason, #143), so a green run would say
      # nothing about the code in the checkout. A dispatch can turn it off (engine-from-source: false) to test the
      # snapshot image. A workflow_call that does not set the input (the release workflow) keeps the image's jars.
      # `inputs.*` is empty on push and pull_request, a boolean on the other two.
      - name: Choose where the engine jars come from
        id: mode
        shell: bash
        env:
          ENGINE_FROM_SOURCE_INPUT: ${{ inputs.engine-from-source }}
        run: |
          echo "engine-from-source=${ENGINE_FROM_SOURCE_INPUT:-true}" >> "$GITHUB_OUTPUT"

      # The jars depend only on the engine source tree, so they are cached under a hash of it: a bindings-only change
      # restores them in seconds, and the Maven build runs only when an engine module, a pom or the
      # Maven wrapper changes (an upstream sync, for example). Raise the `v1` to rebuild after a change to the build
      # steps below.
      - name: Restore the engine jars of this source tree
        id: engine-cache
        if: steps.mode.outputs.engine-from-source == 'true'
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: bindings/python/src/arcadedb_embedded/jars
          key: engine-jars-v1-${{ hashFiles('pom.xml', 'mvnw', '.mvn/**', '**/pom.xml', '**/src/main/**', '!bindings/**', '!benchmarks/**', '!e2e*/**', '!load-tests/**', '!docs/**') }}

      - name: Set up JDK 21 (engine from source)
        if: steps.mode.outputs.engine-from-source == 'true' && steps.engine-cache.outputs.cache-hit != 'true'
        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
        with:
          distribution: temurin
          java-version: "21"
          cache: maven

      - name: Build the engine jars from source
        if: steps.mode.outputs.engine-from-source == 'true' && steps.engine-cache.outputs.cache-hit != 'true'
        shell: bash
        run: |
          ./mvnw -B -q -DskipTests -pl package -am package
          # The FULL distribution. The base, headless, and minimal variants are
          # written beside it as arcadedb-<version>-<variant>.dir, and "-" sorts
          # before ".", so `ls | head -1` picked base, which has no plugins (no
          # Gremlin, Bolt, wire protocols, GraphQL, metrics, or tracing).
          LIB=$(ls -d package/target/arcadedb-*.dir/arcadedb-*/lib | grep -vE -- '-(base|headless|minimal)\.dir/' || true)
          if [ "$(printf '%s\n' "$LIB" | grep -c .)" != 1 ] || [ ! -d "$LIB" ]; then
            echo "::error::expected one full-distribution lib under package/target, got: $LIB"; exit 1
          fi
          if ! ls "$LIB"/arcadedb-gremlin-*.jar > /dev/null 2>&1; then
            echo "::error::$LIB has no Gremlin plugin jar, so it is not the full distribution"; exit 1
          fi
          mkdir -p bindings/python/src/arcadedb_embedded/jars
          cp "$LIB"/*.jar bindings/python/src/arcadedb_embedded/jars/
          ENGINE=$(ls bindings/python/src/arcadedb_embedded/jars/arcadedb-engine-*.jar | head -1)
          echo "Built from $(git rev-parse HEAD): $(ls -1 bindings/python/src/arcadedb_embedded/jars/*.jar | wc -l) JARs"
          unzip -p "$ENGINE" META-INF/MANIFEST.MF | tr -d '\r' | grep -i -E "build|version" || true

      - name: Download JARs from ArcadeDB Docker image
        if: steps.mode.outputs.engine-from-source != 'true'
        shell: bash
        run: |
          cd bindings/python

          # Detect ArcadeDB version from pom.xml (Docker format: X.Y.Z-SNAPSHOT)
          ARCADEDB_TAG=$(python3 scripts/extract_version.py --format=docker)
          echo "📌 ArcadeDB version: $ARCADEDB_TAG"

          # Download JARs from official Docker image
          echo "📦 Downloading JARs from arcadedata/arcadedb:$ARCADEDB_TAG..."

          # Create output directory
          mkdir -p src/arcadedb_embedded/jars

          # Create a temporary container and copy JARs from it
          CONTAINER_ID=$(docker create arcadedata/arcadedb:$ARCADEDB_TAG)
          docker cp $CONTAINER_ID:/home/arcadedb/lib/. src/arcadedb_embedded/jars/
          docker rm $CONTAINER_ID

          # Verify JARs were downloaded
          ls -lh src/arcadedb_embedded/jars/
          JAR_COUNT=$(ls -1 src/arcadedb_embedded/jars/*.jar 2>/dev/null | wc -l)
          echo "✅ Downloaded $JAR_COUNT JAR files"

      # Unfiltered on purpose: build-native.sh applies scripts/jar_exclusions.txt
      # to whatever lands in the jars directory, so the list lives in one place.
      - name: Upload JARs as artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: arcadedb-jars
          path: bindings/python/src/arcadedb_embedded/jars/*.jar
          retention-days: 1

  # Second job: Build and test on each platform
  test:
    name: Test arcadedb-embedded (${{ matrix.platform }}, Python ${{ matrix.python-version }})
    runs-on: ${{ matrix.runs-on }}
    timeout-minutes: 45
    needs: download-jars
    # An experimental leg (Python 3.15) is reported but never fails the job, so Test Summary stays green.
    continue-on-error: ${{ matrix.experimental == true }}
    env:
      BUILD_VERSION: ${{ inputs.build-version }}
    strategy:
      # Don't cancel other matrix jobs if one fails
      fail-fast: false
      matrix:
        python-version:
          - '3.11'
          - '3.12'
          - '3.13'
          - '3.14'
        # Temporarily limit to four platforms (skip macOS x86_64, Windows ARM64)
        # platform: ['linux/amd64', 'linux/arm64', 'darwin/amd64', 'darwin/arm64', 'windows/amd64', 'windows/arm64']
        platform: ['linux/amd64', 'linux/arm64', 'darwin/arm64', 'windows/amd64']
        include:
          - platform: linux/amd64
            runs-on: ubuntu-24.04
          - platform: linux/arm64
            runs-on: ubuntu-24.04-arm
          - platform: darwin/arm64
            runs-on: macos-15
          - platform: windows/amd64
            runs-on: windows-2025
          # - platform: darwin/amd64
          #   runs-on: macos-15-intel
          # - platform: windows/arm64
          #   runs-on: windows-11-arm
          # macOS x86_64 and Windows ARM64 temporarily disabled
          # Python 3.15 is informational: one linux/amd64 leg that may fail without failing the
          # job or the summary (continue-on-error below). It uploads no wheel, so the release
          # workflow never collects or publishes a 3.15 wheel. Drop `experimental` when 3.15 is supported.
          - python-version: '3.15'
            platform: linux/amd64
            runs-on: ubuntu-24.04
            experimental: true

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Setup UV package manager
        shell: bash
        run: |
          # Retry transient network failures (a connection reset failed a whole examples job on #8897); the
          # script is downloaded first so a retried transfer is never piped half-written into sh.
          installer="$(mktemp)"
          curl -LsSf --retry 5 --retry-all-errors --retry-delay 5 -o "$installer" https://astral.sh/uv/0.12.0/install.sh
          sh "$installer"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          export PATH="$HOME/.local/bin:$PATH"
          uv --version

      - name: Download ArcadeDB JARs artifact
        # Native builds (macOS/Windows) always take the jars from this artifact. The
        # Linux Docker build pulls the image's jars itself, except with
        # engine-from-source, where the artifact holds the jars built from this commit.
        if: (matrix.platform != 'linux/amd64' && matrix.platform != 'linux/arm64') || needs.download-jars.outputs.engine-from-source == 'true'
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: arcadedb-jars
          path: bindings/python/src/arcadedb_embedded/jars

      - name: Set up Java (for native builds on macOS/Windows)
        if: matrix.platform != 'linux/amd64' && matrix.platform != 'linux/arm64'
        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
        with:
          distribution: 'corretto'
          java-version: '25'

      - name: Set up Docker Buildx (Linux only)
        if: matrix.platform == 'linux/amd64' || matrix.platform == 'linux/arm64'
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      - name: Set UTF-8 encoding (Windows only)
        if: matrix.platform == 'windows/amd64' || matrix.platform == 'windows/arm64'
        shell: bash
        run: |
          echo "PYTHONIOENCODING=utf-8" >> $GITHUB_ENV
          echo "PYTHONUTF8=1" >> $GITHUB_ENV

      # Windows currently enabled, no symlink needed
      # - name: Create python3 symlink (Windows only)
      #   if: matrix.platform == 'windows/amd64' || matrix.platform == 'windows/arm64'
      #   shell: bash
      #   run: |
      #     PYTHON_DIR=$(dirname "$(which python)")
      #     ln -s "$PYTHON_DIR/python.exe" "$PYTHON_DIR/python3.exe" || true
      #     python3 --version

      - name: Build and test arcadedb-embedded (${{ matrix.platform }})
        shell: bash
        env:
          ENGINE_FROM_SOURCE: ${{ needs.download-jars.outputs.engine-from-source }}
        run: |
          cd bindings/python
          echo "🔨 Building arcadedb-embedded for ${{ matrix.platform }} with Python ${{ matrix.python-version }}..."
          # scripts/build-native.sh (macOS and Windows) runs `python -m build` with the first python on PATH that
          # has the build module. `uv run --with` puts a throwaway environment holding the build tools first on
          # PATH for this one command, so nothing is installed into the runner's interpreter. Linux builds in Docker.
          BUILD_RUN=(uv run --no-project --python "${{ matrix.python-version }}" --with build --with wheel --with setuptools bash)
          # ENGINE FROM SOURCE: hand the jars built from this commit to build.sh on
          # every platform. Without JAR_LIB_DIR the Linux (Docker) build pulls the
          # snapshot image's jars itself, so the option silently did nothing there
          # while the native builds used the artifact (2026-10-04, run 37193748490).
          if [ "${ENGINE_FROM_SOURCE}" = "true" ]; then
            "${BUILD_RUN[@]}" ./scripts/build.sh ${{ matrix.platform }} ${{ matrix.python-version }} src/arcadedb_embedded/jars
          else
            "${BUILD_RUN[@]}" ./scripts/build.sh ${{ matrix.platform }} ${{ matrix.python-version }}
          fi

      - name: Extract wheel for additional testing
        shell: bash
        run: |
          cd bindings/python
          mkdir -p test-install
          cp dist/*.whl test-install/

      - name: Set up Python for host testing
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      # Note: Java is NOT required for arcadedb-embedded (JRE is bundled)
      # This package works without any external Java installation!

      # REMOVE WHEN: jpype1 publishes cp315 wheels (JPype > 1.7.1)
      # JPype has no cp315 wheel yet, so the Python 3.15 leg compiles it from a pinned commit of JPype master
      # (it supports 3.15: jpype-project/jpype#1493, #1498, #1501). That build needs a JDK (jni.h, javac) and
      # Apache Ant, only to build JPype itself. The tests still run on the wheel's bundled JRE.
      - name: Set up JDK and Ant to build JPype (Python 3.15)
        if: matrix.python-version == '3.15'
        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
        with:
          distribution: temurin
          java-version: '17'

      - name: Check Ant for the JPype build (Python 3.15)
        if: matrix.python-version == '3.15'
        shell: bash
        run: |
          command -v ant > /dev/null || { sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends ant; }
          ant -version
          test -f "$JAVA_HOME/include/jni.h"

      - name: Install wheel and test dependencies
        shell: bash
        run: |
          cd bindings/python
          # This list is hand-maintained and mirrors the `test` extra. It had
          # already drifted: pyarrow and pandas were missing, so to_arrow() and
          # to_dataframe() tests skipped themselves in this job while it
          # reported green. The guard step below now fails the build if any
          # test skips for a missing import, so the next drift is loud.
          #
          # Nothing is installed into the runner's interpreter: the list goes to a
          # requirements file that the pytest step hands to `uv run --with-requirements`,
          # which runs the tests in a throwaway environment next to the wheel.
          cat > "$RUNNER_TEMP/test-requirements.txt" <<'REQ'
          pytest
          pytest-cov
          requests
          numpy
          psycopg[binary]
          redis
          neo4j
          pyarrow
          pandas
          polars
          adbc-driver-postgresql>=1.12
          duckdb>=1.4.2
          # REMOVE WHEN: ladybug publishes cp315 wheels (> 0.21.2); also drop the matching collect_ignore in tests/conftest.py
          ladybug>=0.21.2 ; python_version < "3.15"
          networkx>=3.4
          # REMOVE WHEN: jpype1 publishes cp315 wheels (JPype > 1.7.1)
          jpype1 @ git+https://github.com/jpype-project/jpype@ed2cc2095c4b45dd3bfcb4fe1af28369c131e166 ; python_version >= "3.15"
          REQ
          # Build that environment now, so a dependency that cannot be resolved or installed
          # fails here and not in the middle of the test step.
          uv run --no-project --python "${{ matrix.python-version }}" --with ./test-install/*.whl --with-requirements "$RUNNER_TEMP/test-requirements.txt" python -c "import sys; print(sys.version)"

      - name: Run pytest on host
        id: pytest
        # A HUNG TEST ENDS THE STEP, NOT THE DAY. On 2026-09-25 the windows/3.13
        # job sat in test_lsm_vector_quantization_int8_comprehensive for 86 minutes
        # (re-run: passed in 7), and with no limit it would have held the run for
        # GitHub's 6-hour default. The step takes 108-319 s on every platform.
        timeout-minutes: 30
        shell: bash
        run: |
          cd bindings/python
          echo "🧪 Testing arcadedb-embedded (with bundled JRE)..."

          # Run pytest with JUnit XML output for structured results
          # WINDOWS RUNS WITH --capture=sys (humemai/arcadedb-embedded-python#10). pytest's default fd capture swaps
          # fds 1 and 2 with dup2 around every test; on Windows that closes the OS handle
          # the JVM cached for System.out/err at start-up, a later pipe or socket can be
          # handed the same handle value, and the next Java log line then blocks forever
          # in WriteFile once that pipe is full. The Java dump caught it on 2026-09-29:
          # main thread in FileOutputStream.writeBytes under LSMVectorIndex.build's
          # progress log. sys capture never touches the fds, so the JVM keeps writing to
          # the runner's own pipes (its log lines appear in this job's log). No test uses
          # capfd.
          CAPTURE=""
          if [ "$RUNNER_OS" = "Windows" ]; then CAPTURE="--capture=sys"; fi
          set +e  # Don't exit on test failures
          uv run --no-project --python "${{ matrix.python-version }}" --with ./test-install/*.whl --with-requirements "$RUNNER_TEMP/test-requirements.txt" \
            pytest tests/ -v --tb=short --color=yes --junitxml=test-results.xml $CAPTURE
          PYTEST_EXIT_CODE=$?
          set -e

          # Parse JUnit XML for test counts (cross-platform XML parsing)
          if [ -f "test-results.xml" ]; then
            # Extract counts from testsuite element
            TOTAL=$(grep -oE 'tests="[0-9]+"' test-results.xml | grep -oE '[0-9]+' | head -1)
            FAILED=$(grep -oE 'failures="[0-9]+"' test-results.xml | grep -oE '[0-9]+' | head -1)
            SKIPPED=$(grep -oE 'skipped="[0-9]+"' test-results.xml | grep -oE '[0-9]+' | head -1)
            ERRORS=$(grep -oE 'errors="[0-9]+"' test-results.xml | grep -oE '[0-9]+' | head -1)
            # JUnit counts an expected failure (a strict xfail: an open upstream bug the suite tracks)
            # as skipped, so a run with 14 of them read "14 skipped". Count them apart from real skips.
            # grep exits 1 when nothing matches, and this shell runs with pipefail and -e: a suite with no expected failures
            # (every upstream bug fixed, no strict xfail left) used to abort the step here, silently, after all tests passed.
            XFAILED=$({ grep -oE '<skipped[^>]*type="pytest.xfail"' test-results.xml || true; } | wc -l | tr -d ' ')

            # Default to 0 if not found
            TOTAL=${TOTAL:-0}
            FAILED=${FAILED:-0}
            SKIPPED=${SKIPPED:-0}
            ERRORS=${ERRORS:-0}
            XFAILED=${XFAILED:-0}

            # Calculate passed tests (JUnit's skipped total includes the expected failures)
            PASSED=$((TOTAL - FAILED - SKIPPED - ERRORS))
            SKIPPED=$((SKIPPED - XFAILED))

            echo "passed=$PASSED" >> $GITHUB_OUTPUT
            echo "skipped=$SKIPPED" >> $GITHUB_OUTPUT
            echo "xfailed=$XFAILED" >> $GITHUB_OUTPUT
            echo "failed=$FAILED" >> $GITHUB_OUTPUT

            echo "✅ Test results: $PASSED passed, $XFAILED expected failures (xfail), $SKIPPED skipped, $FAILED failed"

            # A test that skips because a dependency is missing is not a
            # passing test, and it does not look like a failure either: the
            # suite goes green having exercised nothing.
            #
            # This has now happened three times. pyarrow was dropped by an
            # install command and the to_arrow() tests skipped; pandas was
            # never in the `test` extra at all, so to_dataframe() had no
            # executed coverage in any CI run this package has ever had; and
            # the hand-written dependency list in this very job was missing
            # both. Each time the signal was a green build.
            #
            # So make it loud. importorskip failures name the module, and a
            # missing dependency is a CI bug rather than an expected condition.
            IMPORT_SKIPS=$(grep -oE 'could not import .[a-zA-Z0-9_.]+.' test-results.xml | sort -u || true)
            if [ -n "$IMPORT_SKIPS" ]; then
              echo "❌ Tests skipped because dependencies are missing:"
              echo "$IMPORT_SKIPS" | sed 's/^/     /'
              echo ""
              echo "   These tests did not run. Add the module to the 'test' extra in"
              echo "   bindings/python/pyproject.toml AND to the test requirements in the install step above,"
              echo "   or delete the test if the integration is no longer supported."
              exit 1
            fi

            # Any other skip must be one somebody accepted (scripts/check_test_skips.py
            # names each, with the platform it applies to and why). A skip because the
            # runtime "lacks" a feature the wheel always ships is how a wrong empty answer
            # once passed as a skip; the import grep above is the special case.
            python scripts/check_test_skips.py test-results.xml --platform "${{ matrix.platform }}" || exit 1

            # Force failure if there are failures or errors
            if [ "$FAILED" -gt 0 ] || [ "$ERRORS" -gt 0 ]; then
              echo "❌ Tests failed (failures=$FAILED, errors=$ERRORS)"
              exit 1
            fi
          else
            echo "⚠️ test-results.xml not found"
            exit 1
          fi

          # Exit with pytest's exit code
          exit $PYTEST_EXIT_CODE

      - name: Generate test summary
        if: always()
        shell: python
        run: |
          import os
          import zipfile
          import glob
          from pathlib import Path

          summary_file = os.environ.get('GITHUB_STEP_SUMMARY', '/dev/null')

          with open(summary_file, 'a', encoding='utf-8') as f:
              f.write("## 🧪 Test Results: arcadedb-embedded (${{ matrix.platform }})\n")
              f.write("\n")

              # Check test status
              if "${{ steps.pytest.outcome }}" == "success":
                  f.write("✅ **Status**: PASSED\n")
              else:
                  f.write("❌ **Status**: FAILED\n")

              f.write("\n")
              f.write("| Metric | Count |\n")
              f.write("|--------|-------|\n")

              # Show test results
              f.write("| ✅ Passed | ${{ steps.pytest.outputs.passed || 'N/A' }} |\n")
              f.write("| ⏭️ Skipped | ${{ steps.pytest.outputs.skipped || 'N/A' }} |\n")
              f.write("| 🔖 Expected failures (xfail) | ${{ steps.pytest.outputs.xfailed || 'N/A' }} |\n")
              f.write("| ❌ Failed | ${{ steps.pytest.outputs.failed || 'N/A' }} |\n")
              f.write("\n")

              f.write("### 📦 Package Info:\n")
              f.write("\n")

              # Get wheel size and analyze contents
              wheel_files = glob.glob("bindings/python/dist/*.whl")
              if wheel_files:
                  wheel_file = wheel_files[0]

                  # Get wheel size
                  wheel_size_bytes = os.path.getsize(wheel_file)
                  wheel_size_mb = wheel_size_bytes / 1024 / 1024

                  # Analyze wheel contents
                  jre_size_mb = "N/A"
                  jar_size_mb = "N/A"
                  installed_size_mb = "N/A"

                  try:
                      # Extract and analyze (cross-platform)
                      import tempfile
                      import shutil

                      with tempfile.TemporaryDirectory() as temp_dir:
                          with zipfile.ZipFile(wheel_file, 'r') as whl:
                              whl.extractall(temp_dir)

                          # Calculate JRE size
                          jre_dir = None
                          for root, dirs, files in os.walk(temp_dir):
                              if 'jre' in dirs:
                                  jre_dir = os.path.join(root, 'jre')
                                  break

                          if jre_dir and os.path.isdir(jre_dir):
                              jre_size_kb = 0
                              for root, dirs, files in os.walk(jre_dir):
                                  for file in files:
                                      jre_size_kb += os.path.getsize(os.path.join(root, file))
                              jre_size_mb = jre_size_kb / 1024 / 1024

                          # Calculate JAR size
                          jar_files = []
                          for root, dirs, files in os.walk(temp_dir):
                              for file in files:
                                  if file.endswith('.jar'):
                                      jar_files.append(os.path.join(root, file))

                          if jar_files:
                              jar_size_kb = sum(os.path.getsize(f) for f in jar_files) / 1024
                              jar_size_mb = jar_size_kb / 1024

                          # Calculate total size
                          total_size_kb = 0
                          for root, dirs, files in os.walk(temp_dir):
                              for file in files:
                                  total_size_kb += os.path.getsize(os.path.join(root, file))
                          installed_size_mb = total_size_kb / 1024 / 1024
                  except Exception as e:
                      print(f"Warning: Could not analyze wheel contents: {e}")

                  f.write(f"- **Wheel Size**: {wheel_size_mb:.1f}M (compressed)\n")
                  if isinstance(jre_size_mb, str):
                      f.write(f"- **JRE Size**: {jre_size_mb} (uncompressed)\n")
                  else:
                      f.write(f"- **JRE Size**: {jre_size_mb:.1f}M (uncompressed)\n")
                  if isinstance(jar_size_mb, str):
                      f.write(f"- **JARs Size**: {jar_size_mb} (uncompressed)\n")
                  else:
                      f.write(f"- **JARs Size**: {jar_size_mb:.1f}M (uncompressed)\n")
                  if isinstance(installed_size_mb, str):
                      f.write(f"- **Installed Size**: {installed_size_mb} (total uncompressed)\n")
                  else:
                      f.write(f"- **Installed Size**: ~{installed_size_mb:.0f}M (total uncompressed)\n")

              f.write("- **Platform**: ${{ matrix.platform }}\n")
              f.write("- **Features**: All ArcadeDB features (some JARs excluded, see jar_exclusions.txt)\n")

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: test-results-${{ matrix.platform == 'linux/amd64' && 'linux-amd64' || matrix.platform == 'linux/arm64' && 'linux-arm64' || matrix.platform == 'darwin/amd64' && 'darwin-amd64' || matrix.platform == 'darwin/arm64' && 'darwin-arm64' || matrix.platform == 'windows/amd64' && 'windows-amd64' || 'windows-arm64' }}-py${{ matrix.python-version }}
          path: |
            bindings/python/pytest-output.txt
            bindings/python/.coverage
          retention-days: 7

      # Not for an experimental leg: the release workflow collects wheel-*-py* and counts them.
      - name: Upload wheel artifact
        if: matrix.experimental != true
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheel-${{ matrix.platform == 'linux/amd64' && 'linux-amd64' || matrix.platform == 'linux/arm64' && 'linux-arm64' || matrix.platform == 'darwin/amd64' && 'darwin-amd64' || matrix.platform == 'darwin/arm64' && 'darwin-arm64' || matrix.platform == 'windows/amd64' && 'windows-amd64' || 'windows-arm64' }}-py${{ matrix.python-version }}
          path: bindings/python/dist/*.whl
          retention-days: 7

      - name: Upload wheel artifact for release
        if: matrix.python-version == '3.12'
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheel-${{ matrix.platform == 'linux/amd64' && 'linux-amd64' || matrix.platform == 'linux/arm64' && 'linux-arm64' || matrix.platform == 'darwin/amd64' && 'darwin-amd64' || matrix.platform == 'darwin/arm64' && 'darwin-arm64' || matrix.platform == 'windows/amd64' && 'windows-amd64' || 'windows-arm64' }}-test
          path: bindings/python/dist/*.whl
          retention-days: 7

  # Summary job that checks all platforms
  test-summary:
    name: Test Summary
    needs: test
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    # Skipped with the matrix on a draft pull request; a skipped check is not a failed one.
    if: always() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false)
    steps:
      - name: Check test results
        run: |
          echo "## 🎯 Overall Test Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [ "${{ needs.test.result }}" = "success" ]; then
            echo "✅ **All platforms passed testing!**" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "The arcadedb-embedded package has been successfully built and tested." >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "**Package**: arcadedb-embedded" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "ℹ️ **Note**: Some platform/Python combinations are excluded from testing:" >> $GITHUB_STEP_SUMMARY
            echo "- Windows ARM64 (no GitHub-hosted runners available)" >> $GITHUB_STEP_SUMMARY
            echo "- macOS x86_64 (temporarily disabled)" >> $GITHUB_STEP_SUMMARY
            echo "- Python 3.15 runs as an informational linux/amd64 leg: its result is shown on the run but does not decide this summary" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "❌ **Some platforms failed testing**" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "Please check the individual test jobs for details." >> $GITHUB_STEP_SUMMARY
            exit 1
          fi