framework-tests.yml

# Hugo + Hextra docs-framework harness, run against agw-oss's built site.
#
# One Hugo build feeds two Playwright projects (defined in docs-theme-extras'
# playwright.config.ts):
#   --project=static   layout / theme-behavior specs (render the theme)
#   --project=content  scanners that depend on the consumer's real content
#                      (markdown-leaks walks the built HTML for rendering
#                      leaks; curl-quotes lints source markdown)
# The `content` scanners are the reason this workflow's path filter includes
# CONTENT paths (assets/agw-docs/**, content/**), not just layout paths: a
# content-only PR must still run the leak scan, since that is exactly the kind
# of PR that introduces content rendering breaks. Both projects share the same
# build, so running the (fast, mostly fixture-bound) layout specs on a content
# PR too costs almost nothing — not worth a second workflow to avoid.
#
# The harness lives in solo-io/docs-theme-extras and is checked out at the
# version pinned in go.mod (semver tag or pseudo-version). Layouts and tests
# stay in lockstep — bumping the module pin is one PR that updates both.
#
# Marked continue-on-error for the first ~week to let allowlists and
# fixture-aware specs settle. Promote to a required check once the suite
# stays green for a sustained run.

name: Framework tests

on:
  pull_request:
    paths:
      # Content — so the `content` scanners run on content-only PRs.
      - 'assets/agw-docs/**'
      - 'content/**'
      # Layout / build inputs.
      - 'layouts/**'
      - 'static/**'
      - 'assets/css/**'
      - 'assets/js/**'
      - 'go.mod'
      - 'go.sum'
      - 'hugo.yaml'
      - '.docs-test.toml'
      - '.github/workflows/framework-tests.yml'
  workflow_dispatch:

jobs:
  framework-test:
    name: Static + content checks
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
        with:
          go-version: 'stable'
          cache: false
      - uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3
        with:
          hugo-version: '0.160.1'
          extended: true

      - name: Resolve docs-theme-extras ref from go.mod
        id: theme-sha
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Pull the full version field as written in go.mod. Handles every
          # form: tag (v0.0.2), prerelease tag (v0.0.2-beta.1, v0.0.2-rc.1),
          # and Go pseudo-version (v0.0.2-0.20260522171640-df9722216725).
          version=$(awk -v pkg="github.com/solo-io/docs-theme-extras" '
            { for (i=1; i<=NF; i++) if ($i == pkg) { print $(i+1); exit } }
          ' go.mod)
          if [ -z "$version" ]; then
            echo "Could not extract docs-theme-extras version from go.mod" >&2
            exit 1
          fi
          # Pseudo-version shape: ends with .<14-digit timestamp>-<12-hex short SHA>
          # (e.g. v0.0.2-0.20260522171640-df9722216725).
          if echo "$version" | grep -qE -- '\.[0-9]{14}-[0-9a-f]{12}$'; then
            # Extract the 12-char short SHA and resolve to a full 40-char SHA,
            # since actions/checkout treats short SHAs as branch names and
            # fails to fetch them.
            short=$(echo "$version" | grep -oE '[0-9a-f]{12}$')
            ref=$(gh api "repos/solo-io/docs-theme-extras/commits/${short}" --jq .sha)
            if [ -z "$ref" ]; then
              echo "Could not resolve full SHA for short=${short}" >&2
              exit 1
            fi
          else
            # Semver tag (release or prerelease): actions/checkout accepts it directly.
            ref="$version"
          fi
          echo "ref=$ref" >> "$GITHUB_OUTPUT"

      - name: Check out docs-theme-extras at module pin
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          repository: solo-io/docs-theme-extras
          ref: ${{ steps.theme-sha.outputs.ref }}
          path: docs-theme-extras

      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: 'docs-theme-extras/package-lock.json'

      - name: Build site with Hugo
        run: |
          # PostCSS is invoked by Hugo's css.PostCSS for assets/css/styles.css
          # but isn't installed by default in this runner. Mirror the
          # install pattern from links.yml so Hugo can find it via npx.
          npm i -D postcss postcss-cli autoprefixer
          # Capture the build log so hugo-warnings.spec can scan it for ERROR /
          # WARN lines; surface it and fail if the build itself fails.
          hugo --gc --minify > .build.log 2>&1 || { cat .build.log; exit 1; }

      - name: Install harness dependencies
        working-directory: docs-theme-extras
        run: npm ci

      - name: Run static + content specs
        working-directory: docs-theme-extras
        env:
          DOCS_TEST_CONFIG: ${{ github.workspace }}/.docs-test.toml
        run: |
          # One invocation runs both projects against the single build above.
          npx playwright test --project=static --project=content --reporter=list,html 2>&1 | tee playwright-output.txt

      - name: Append summary to PR check
        if: always()
        working-directory: docs-theme-extras
        run: |
          {
            echo "## Framework tests (informational)"
            echo ""
            echo '```'
            tail -25 playwright-output.txt 2>/dev/null || echo "No test output captured."
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
        with:
          name: framework-test-report
          path: docs-theme-extras/playwright-report
          retention-days: 7