paperless-ngx/.github/workflows/ci-frontend.yml

name: Frontend Tests
on:
  push:
    branches-ignore:
      - 'translations**'
  pull_request:
    branches-ignore:
      - 'translations**'
  workflow_dispatch:
concurrency:
  group: frontend-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
permissions: {}
jobs:
  changes:
    name: Detect Frontend Changes
    runs-on: ubuntu-slim
    permissions:
      contents: read
    outputs:
      frontend_changed: ${{ steps.force.outputs.run_all == 'true' || steps.filter.outputs.frontend == 'true' }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Decide run mode
        id: force
        env:
          EVENT_NAME: ${{ github.event_name }}
          REF_NAME: ${{ github.ref_name }}
        run: |
          if [[ "${EVENT_NAME}" == "workflow_dispatch" ]]; then
            echo "run_all=true" >> "$GITHUB_OUTPUT"
          elif [[ "${EVENT_NAME}" == "push" && ( "${REF_NAME}" == "main" || "${REF_NAME}" == "dev" ) ]]; then
            echo "run_all=true" >> "$GITHUB_OUTPUT"
          else
            echo "run_all=false" >> "$GITHUB_OUTPUT"
          fi
      - name: Set diff range
        id: range
        if: steps.force.outputs.run_all != 'true'
        env:
          BEFORE_SHA: ${{ github.event.before }}
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          EVENT_CREATED: ${{ github.event.created }}
          EVENT_NAME: ${{ github.event_name }}
          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          SHA: ${{ github.sha }}
        run: |
          if [[ "${EVENT_NAME}" == "pull_request" ]]; then
            echo "base=${PR_BASE_SHA}" >> "$GITHUB_OUTPUT"
          elif [[ "${EVENT_CREATED}" == "true" ]]; then
            echo "base=${DEFAULT_BRANCH}" >> "$GITHUB_OUTPUT"
          else
            echo "base=${BEFORE_SHA}" >> "$GITHUB_OUTPUT"
          fi
          echo "ref=${SHA}" >> "$GITHUB_OUTPUT"
      - name: Detect changes
        id: filter
        if: steps.force.outputs.run_all != 'true'
        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
        with:
          base: ${{ steps.range.outputs.base }}
          ref: ${{ steps.range.outputs.ref }}
          filters: |
            frontend:
              - 'src-ui/**'
              - '.github/workflows/ci-frontend.yml'
  install-dependencies:
    needs: changes
    if: needs.changes.outputs.frontend_changed == 'true'
    name: Install Dependencies
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Install pnpm
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
        with:
          package_json_file: src-ui/package.json
      - name: Use Node.js 24
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
        id: cache-frontend-deps
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.pnpm-store
            ~/.cache
          key: ${{ runner.os }}-frontend-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
      - name: Install dependencies
        run: cd src-ui && pnpm install
  lint:
    name: Lint
    needs: [changes, install-dependencies]
    if: needs.changes.outputs.frontend_changed == 'true'
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Install pnpm
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
        with:
          package_json_file: src-ui/package.json
      - name: Use Node.js 24
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.pnpm-store
            ~/.cache
          key: ${{ runner.os }}-frontend-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
      - name: Install dependencies
        run: cd src-ui && pnpm install --frozen-lockfile
      - name: Run lint
        run: cd src-ui && pnpm run lint
  unit-tests:
    name: "Unit Tests (${{ matrix.shard-index }}/${{ matrix.shard-count }})"
    needs: [changes, install-dependencies]
    if: needs.changes.outputs.frontend_changed == 'true'
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        node-version: [24.x]
        shard-index: [1, 2, 3, 4]
        shard-count: [4]
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Install pnpm
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
        with:
          package_json_file: src-ui/package.json
      - name: Use Node.js 24
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.pnpm-store
            ~/.cache
          key: ${{ runner.os }}-frontend-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
      - name: Install dependencies
        run: cd src-ui && pnpm install --frozen-lockfile
      - name: Run Jest unit tests
        run: cd src-ui && pnpm run test --max-workers=2 --shard=${{ matrix.shard-index }}/${{ matrix.shard-count }}
      - name: Upload test results to Codecov
        if: always()
        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
        with:
          flags: frontend-node-${{ matrix.node-version }}
          directory: src-ui/
          report_type: test_results
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
        with:
          flags: frontend-node-${{ matrix.node-version }}
          directory: src-ui/coverage/
  e2e-tests:
    name: E2E Tests
    needs: [changes, install-dependencies]
    if: needs.changes.outputs.frontend_changed == 'true'
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    container: mcr.microsoft.com/playwright:v1.62.1-resolute
    env:
      PLAYWRIGHT_BROWSERS_PATH: /ms-playwright
      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Install pnpm
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
        with:
          package_json_file: src-ui/package.json
      - name: Use Node.js 24
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Set up Python
        id: setup-python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: '3.12'
      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          version: '0.13.x'
          enable-cache: false
          python-version: ${{ steps.setup-python.outputs.python-version }}
      - name: Cache frontend dependencies
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.pnpm-store
            ~/.cache
          key: ${{ runner.os }}-frontend-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
      - name: Install dependencies
        run: cd src-ui && pnpm install --frozen-lockfile
      - name: Install backend system dependencies
        timeout-minutes: 12
        uses: $/.github/actions/apt-install
        with:
          packages: libmagic1
      - name: Install backend dependencies
        env:
          PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}
        # The frozen repository lockfile and its build hooks are trusted.
        run: uv sync --python "${PYTHON_VERSION}" --no-dev --frozen # NOSONAR
      - name: Run Playwright E2E tests
        run: cd src-ui && pnpm exec playwright test
  frontend-build:
    name: Frontend Build
    needs: [changes, unit-tests, e2e-tests]
    if: needs.changes.outputs.frontend_changed == 'true'
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 2
          persist-credentials: false
      - name: Install pnpm
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
        with:
          package_json_file: src-ui/package.json
      - name: Use Node.js 24
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.pnpm-store
            ~/.cache
          key: ${{ runner.os }}-frontend-${{ hashFiles('src-ui/pnpm-lock.yaml') }}
      - name: Install dependencies
        run: cd src-ui && pnpm install --frozen-lockfile
      - name: Build
        run: cd src-ui && pnpm run build --configuration=production
  gate:
    name: Frontend CI Gate
    needs: [changes, install-dependencies, lint, unit-tests, e2e-tests, frontend-build]
    if: always()
    runs-on: ubuntu-slim
    steps:
      - name: Check gate
        env:
          BUILD_RESULT: ${{ needs['frontend-build'].result }}
          E2E_RESULT: ${{ needs['e2e-tests'].result }}
          FRONTEND_CHANGED: ${{ needs.changes.outputs.frontend_changed }}
          INSTALL_RESULT: ${{ needs['install-dependencies'].result }}
          LINT_RESULT: ${{ needs.lint.result }}
          UNIT_RESULT: ${{ needs['unit-tests'].result }}
        run: |
          if [[ "${FRONTEND_CHANGED}" != "true" ]]; then
            echo "No frontend-relevant changes detected."
            exit 0
          fi

          if [[ "${INSTALL_RESULT}" != "success" ]]; then
            echo "::error::Frontend install job result: ${INSTALL_RESULT}"
            exit 1
          fi

          if [[ "${LINT_RESULT}" != "success" ]]; then
            echo "::error::Frontend lint job result: ${LINT_RESULT}"
            exit 1
          fi

          if [[ "${UNIT_RESULT}" != "success" ]]; then
            echo "::error::Frontend unit-tests job result: ${UNIT_RESULT}"
            exit 1
          fi

          if [[ "${E2E_RESULT}" != "success" ]]; then
            echo "::error::Frontend e2e-tests job result: ${E2E_RESULT}"
            exit 1
          fi

          if [[ "${BUILD_RESULT}" != "success" ]]; then
            echo "::error::Frontend build job result: ${BUILD_RESULT}"
            exit 1
          fi

          echo "Frontend checks passed."