integration.yml

name: integration

# Real-network multi-node integration tests (#313).
#
# This workflow runs `bun run test:integration` — the exact same
# command that works locally on a developer's laptop with Docker
# Desktop.  All the Docker-compose + scenario logic lives in
# `tests/integration/`; this file is intentionally thin so there's
# no CI-only drift.
#
# Triggers:
#   - Pushes to `develop` + PRs (into `develop`, or into `main` for the
#     release) — the suite proved fast enough in practice (~25 s scenarios
#     + ~10 s container startup + cached build) that the action-minute
#     budget isn't a concern.  It surfaces cluster / transport /
#     persistence regressions on the integration branch and before the
#     release promotion.
#   - Manual dispatch (workflow_dispatch) — re-run on demand from
#     the GitHub Actions UI for any branch.
#   - Nightly at 03:00 UTC on `develop` (the default branch) — catches
#     transport-level flakes that wouldn't show up in fast PR runs.

on:
  # Heavy real-network multi-node suite.  Runs on `develop` pushes and on
  # PRs (into `develop`, or into `main` for the release), nightly on
  # `develop` (the default branch, via the schedule below), and on dispatch.
  push:
    branches: [develop]
    paths:
      - 'src/**'
      - 'tests/integration/**'
      - 'package.json'
      - '.bun-version'
      - 'bun.lock'
      - 'tsconfig.json'
      - '.github/workflows/integration.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'src/**'
      - 'tests/integration/**'
      - 'package.json'
      - '.bun-version'
      - 'bun.lock'
      - 'tsconfig.json'
      - '.github/workflows/integration.yml'
  workflow_dispatch:
  schedule:
    # Nightly run catches transport-level flakes that wouldn't
    # show up in fast unit-test PR runs.  Fires regardless of the
    # `paths:` filter above (cron triggers ignore them).
    - cron: '0 3 * * *'

# Least privilege, stated rather than inherited: the repository default is
# read-only today, but a settings flip would otherwise hand a write token to
# a job that installs and runs the whole dependency tree.  #621
permissions:
  contents: read

jobs:
  integration:
    runs-on: ubuntu-latest
    timeout-minutes: 30

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

      - name: Setup Bun
        # Only needed to expose `bun run test:integration` as the
        # command — the actual scenarios run INSIDE the Docker
        # containers, not on the runner.  But the runner needs Bun
        # to evaluate the npm-script shorthand.
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
        with:
          bun-version-file: .bun-version

      # Docker is preinstalled on `ubuntu-latest`.  Print the version
      # so a future Docker-on-Actions outage is visible in the logs.
      - name: Show Docker version
        run: docker version

      - name: Run integration scenarios
        run: bun run test:integration
        # Surfacing the failure path: when a scenario fails, the
        # controller exits 1 → docker-compose exits 1 → this step
        # exits 1 → workflow turns red.  The `--exit-code-from
        # controller` flag in the npm script is the relay.

      - name: Capture container logs on failure
        if: failure()
        run: |
          # Dump every container's stdout/stderr so a flaky scenario
          # is debuggable from the workflow logs alone — no need to
          # re-run locally and pray for repro.  JSON-formatted by
          # JsonLogger, so the result is grep-friendly.
          docker compose -f tests/integration/docker-compose.integration.yml logs --no-color || true

      - name: Tear down
        if: always()
        run: bun run test:integration:teardown