Feature/yksinkertaistetaan raportointi logiikkaa (#22)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #22
2026-06-18 12:55:02 +03:00
parent 65d385f9b9
commit 737b2fc3f2
11 changed files with 357 additions and 180 deletions
@@ -1,37 +1,29 @@
 #!/usr/bin/env bash
 set -euo pipefail

-WORKSPACE_VOLUME="${1:-}"
-REPORT_DIR="${2:-}"
+REPORT_DIR="${1:-}"
+COVERAGE_DIR="${REPORT_DIR}/coverage"

-[ -n "$WORKSPACE_VOLUME" ] || { echo "ERROR: workspace volume name required" >&2; exit 1; }
 [ -n "$REPORT_DIR" ] || { echo "ERROR: report directory required" >&2; exit 1; }

-HAS_COVERAGE=false
-COVERAGE_SRC=""
-if docker run --rm -v "$WORKSPACE_VOLUME":/data alpine sh -c '[ -d /data/coverage ] && ls -A /data/coverage | grep -q .' 2>/dev/null; then
-  COVERAGE_SRC="/data/coverage"
+if [ -d coverage ]; then
+  mkdir -p "$COVERAGE_DIR"
+  cp -a coverage/. "$COVERAGE_DIR/"
 fi

-if [ -n "$COVERAGE_SRC" ]; then
-  mkdir -p "$REPORT_DIR/coverage"
-  docker run --rm -v "$WORKSPACE_VOLUME":/data alpine tar c -C "$COVERAGE_SRC" . | tar x -C "$REPORT_DIR/coverage"
-  HAS_COVERAGE=true
+if [ -d "$COVERAGE_DIR" ] && [ ! -f "$COVERAGE_DIR/index.html" ]; then
+  SHA8="${GITHUB_SHA:0:8}"
+  {
+    echo '<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">'
+    echo "<title>Coverage report ${SHA8}</title>"
+    echo '<style>body{font-family:sans-serif;margin:2em}h1{color:#1e293b}ul{list-style:none;padding:0}li{margin:.5em 0}a{color:#2563eb}</style>'
+    echo "</head><body><h1>Coverage report <code>${SHA8}</code></h1><ul>"
+    while IFS= read -r -d '' f; do
+      base=$(basename "$f")
+      name="${base%.*}"
+      name="${name//-/ }"
+      echo "<li><a href=\"${base}\">${name^}</a></li>"
+    done < <(find "$COVERAGE_DIR" -maxdepth 1 -type f \( -name '*.html' -o -name '*.txt' \) ! -name index.html -print0 2>/dev/null || true)
+    echo '</ul></body></html>'
+  } > "$COVERAGE_DIR/index.html"
 fi
-
-cat > "$REPORT_DIR/index.html" << EOF
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
-<title>Bats report ${GITHUB_SHA:0:8}</title>
-<style>body{font-family:sans-serif;margin:2em;max-width:960px}
-h1{color:#1e293b}a{color:#2563eb;text-decoration:none}a:hover{text-decoration:underline}
-</style></head><body>
-<h1>Bats report <code>${GITHUB_SHA:0:8}</code></h1>
-<ul>
-<li><a href="test-report.html">Test results</a></li>
-EOF
-
-if [ "$HAS_COVERAGE" = true ]; then
-  echo '<li><a href="coverage/index.html">Coverage report</a></li>' >> "$REPORT_DIR/index.html"
-fi
-
-echo '</ul></body></html>' >> "$REPORT_DIR/index.html"
@@ -6,8 +6,9 @@ on:
        required: true
        type: string
      bats-image:
-        required: true
+        required: false
        type: string
+        default: gitea.app.keskikuja.site/niko/ci-bats:latest
    secrets:
      GITEA_TOKEN:
        required: true
@@ -23,6 +24,8 @@ env:
 jobs:
  bats:
    runs-on: ubuntu-latest
+    container:
+      image: ${{ inputs.bats-image }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/checkout@v4
@@ -31,34 +34,18 @@ jobs:
          path: .ci

      - name: Run bats tests
-        id: bats-tests
-        shell: bash
        run: |
-          docker volume create bats-workspace
-          tar c . | docker run --rm -i -v bats-workspace:/data alpine tar x -C /data
-          mkdir -p "reports/${GITHUB_SHA:0:8}/bats"
-          set +e
-          docker run --rm \
-            -v bats-workspace:/data \
-            --entrypoint bash ${{ inputs.bats-image }} \
-            -c 'cd /data && bashcov -- bats tests/' \
-            > "reports/${GITHUB_SHA:0:8}/bats/results.txt" 2>&1
-          BATS_EXIT=$?
-          bash .ci/.gitea/scripts/bats-coverage.sh bats-workspace "reports/${GITHUB_SHA:0:8}/bats"
-          docker volume rm bats-workspace > /dev/null 2>&1
-          bash .ci/.gitea/scripts/bats-report.sh "reports/${GITHUB_SHA:0:8}/bats"
-          echo "BATS_EXIT=${BATS_EXIT}" >> "${GITHUB_ENV}"
-          exit ${BATS_EXIT}
+          mkdir -p reports/bats
+          bashcov -- bats tests/ > reports/bats/results.txt 2>&1

-      - name: Publish bats reports
+      - name: Post-process coverage
        if: always()
-        run: bash .ci/scripts/publish-git-pages.sh bats
+        run: bash .ci/.gitea/scripts/bats-coverage.sh reports/bats

-      - name: Report status
+      - name: Post-process test report
        if: always()
-        run: |
-          if [ "${BATS_EXIT}" = "0" ]; then
-            bash .ci/scripts/report-status.sh success "Link to Bats reports" unit-tests bats
-          else
-            bash .ci/scripts/report-status.sh failure "Link to Bats reports" unit-tests bats
-          fi
+        run: bash .ci/.gitea/scripts/bats-report.sh reports/bats
+
+      - name: Report
+        if: always()
+        run: bash .ci/scripts/ci-report.sh "Bats test report" unit-tests bats
@@ -25,14 +25,14 @@ on:

 jobs:
  load-config:
-    uses: niko/gitea-ci-library/.gitea/workflows/config-provider.yml@v1
+    uses: niko/gitea-ci-library/.gitea/workflows/config-provider.yml@main
    secrets: inherit
    with:
      config_path: ${{ inputs.config_path }}

  build-push:
    needs: [load-config]
-    uses: niko/gitea-ci-library/.gitea/workflows/ci-container-build-push.yml@v1
+    uses: niko/gitea-ci-library/.gitea/workflows/ci-container-build-push.yml@main
    secrets: inherit
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}
@@ -6,8 +6,9 @@ on:
        required: true
        type: string
      cucumber-node-image:
-        required: true
+        required: false
        type: string
+        default: gitea.app.keskikuja.site/niko/ci-cucumber:latest
    secrets:
      GITEA_TOKEN:
        required: true
@@ -33,36 +34,14 @@ jobs:
          path: .ci

      - name: Run cucumber tests
-        id: cucumber-tests
        shell: bash
        run: |
-          mkdir -p "reports/${GITHUB_SHA:0:8}/cucumber"
-          set +e
+          mkdir -p reports/cucumber
          npx cucumber-js \
-            --format json:"reports/${GITHUB_SHA:0:8}/cucumber/report.json" \
-            --format html:"reports/${GITHUB_SHA:0:8}/cucumber/index.html" 2>&1
-          CUCUMBER_EXIT=$?
-          echo "CUCUMBER_EXIT=${CUCUMBER_EXIT}" >> "${GITHUB_ENV}"
-          exit ${CUCUMBER_EXIT}
+            --format json:reports/cucumber/report.json \
+            --format html:reports/cucumber/report.html 2>&1

-      - name: Publish cucumber reports
-        if: always()
-        run: bash .ci/scripts/publish-git-pages.sh cucumber
-
-      - name: Report status
+      - name: Report
        if: always()
        shell: bash
-        run: |
-          if [ "${CUCUMBER_EXIT}" = "0" ]; then
-            if [ -f "reports/${GITHUB_SHA:0:8}/cucumber/index.html" ]; then
-              bash .ci/scripts/report-status.sh success "Link to Cucumber reports" acc-tests cucumber
-            else
-              bash .ci/scripts/report-status.sh success "Link to Cucumber reports" acc-tests
-            fi
-          else
-            if [ -f "reports/${GITHUB_SHA:0:8}/cucumber/index.html" ]; then
-              bash .ci/scripts/report-status.sh failure "Link to Cucumber reports" acc-tests cucumber
-            else
-              bash .ci/scripts/report-status.sh failure "Link to Cucumber reports" acc-tests
-            fi
-          fi
+        run: bash .ci/scripts/ci-report.sh "Cucumber test report" acc-tests cucumber
@@ -20,7 +20,6 @@ jobs:
    secrets: inherit
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}
-      bats-image: gitea.app.keskikuja.site/niko/ci-bats:latest

  cucumber:
    name: Cucumber tests
@@ -29,7 +28,6 @@ jobs:
    secrets: inherit
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}
-      cucumber-node-image: gitea.app.keskikuja.site/niko/ci-cucumber:latest

  report-summary:
    name: Report Summary
@@ -29,7 +29,6 @@ jobs:
    secrets: inherit
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}
-      bats-image: gitea.app.keskikuja.site/niko/ci-bats:latest

  cucumber:
    name: Cucumber tests
@@ -39,7 +38,6 @@ jobs:
    secrets: inherit
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}
-      cucumber-node-image: gitea.app.keskikuja.site/niko/ci-cucumber:latest

  build-push:
    name: Build & Push Docker
@@ -1,3 +1,3 @@
-FROM bats/bats:latest
+FROM bats/bats:1.11.0
 RUN apk add --no-cache lsof python3 jq curl ruby && \
    gem install bashcov -v 3.3.0
@@ -123,8 +123,8 @@ Hae token Giteasta:

 ```bash
 GITEA_URL="https://<gitea-server-url>"
-GITEA_ACTIONS_TOKEN="<registration-token>"
 GITEA_ACTIONS_NAMESPACE="gitea-actions"
+GITEA_ACTIONS_TOKEN="<registration-token>"
 ```

 ### 3. Tee secret vain init install yhteydessä
@@ -158,6 +158,7 @@ helm upgrade --install act-runner gitea/actions \
  --set giteaRootURL="$GITEA_URL" \
  --set existingSecret=act-runner-token \
  --set existingSecretKey=token \
+  --set statefulset.replicas=3 \
  --set statefulset.runner.tag=1.0.8 \
  --set statefulset.dind.tag=29.5.2-dind \
  --set-string 'statefulset.runner.config=log:
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DESCRIPTION="${1:-}"
+CONTEXT="${2:-}"
+SUITE="${3:-}"
+
+[ -n "$DESCRIPTION" ] || { echo "ERROR: description argument required" >&2; exit 1; }
+[ -n "$CONTEXT" ] || { echo "ERROR: context argument required" >&2; exit 1; }
+[ -n "$SUITE" ] || { echo "ERROR: suite argument required" >&2; exit 1; }
+
+REPORT_DIR="reports/${SUITE}"
+
+if [ ! -d "$REPORT_DIR" ]; then
+  echo "ERROR: $REPORT_DIR not found" >&2
+  bash .ci/scripts/report-status.sh failure "$DESCRIPTION" "$CONTEXT"
+  exit 1
+fi
+
+FILES=()
+while IFS= read -r -d '' f; do
+  FILES+=("$(basename "$f")")
+done < <(find "$REPORT_DIR" -maxdepth 1 -type f ! -name index.html -print0 2>/dev/null || true)
+
+SUBDIRS=()
+while IFS= read -r -d '' d; do
+  name="${d#$REPORT_DIR/}"
+  [ -f "$d/index.html" ] && SUBDIRS+=("$name")
+done < <(find "$REPORT_DIR" -maxdepth 1 -type d ! -name . -print0 2>/dev/null || true)
+
+TOTAL=$(( ${#FILES[@]} + ${#SUBDIRS[@]} ))
+
+if [ "$TOTAL" -eq 0 ]; then
+  echo "ERROR: no reportable items in $REPORT_DIR" >&2
+  bash .ci/scripts/report-status.sh failure "$DESCRIPTION" "$CONTEXT"
+  exit 1
+fi
+
+SHA8="${GITHUB_SHA:0:8}"
+
+humanize() {
+  local name="$1"
+  name="${name%.*}"
+  name="${name//-/ }"
+  name="${name//_/ }"
+  echo "${name^}"
+}
+
+generate_index() {
+  local html
+  html='<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">'
+  html+="<title>$DESCRIPTION</title>"
+  html+='<style>body{font-family:sans-serif;margin:2em;max-width:960px}h1{color:#1e293b}ul{list-style:none;padding:0}li{margin:.5em 0;padding:.5em;background:#f8fafc;border-radius:6px}a{color:#2563eb;text-decoration:none}a:hover{text-decoration:underline}</style>'
+  html+="</head><body><h1>$DESCRIPTION</h1><ul>"
+  for f in "${FILES[@]}"; do
+    html+="<li><a href=\"$f\">$(humanize "$f")</a></li>"
+  done
+  for d in "${SUBDIRS[@]}"; do
+    html+="<li><a href=\"$d/index.html\">${d^}</a></li>"
+  done
+  html+='</ul></body></html>'
+  printf '%s' "$html" > "$REPORT_DIR/index.html"
+}
+
+STAGED="reports/${SHA8}/${SUITE}"
+mkdir -p "$STAGED"
+
+if [ "$TOTAL" -eq 1 ]; then
+  cp -a "$REPORT_DIR/." "$STAGED/"
+  bash .ci/scripts/publish-git-pages.sh "$SUITE"
+
+  if [ ${#FILES[@]} -eq 1 ]; then
+    ENTRY="${FILES[0]}"
+  else
+    ENTRY="${SUBDIRS[0]}/index.html"
+  fi
+  URL="${GIT_PAGES_URL}/${GITHUB_REPOSITORY}/reports/${SHA8}/${SUITE}/${ENTRY}"
+  bash .ci/scripts/report-status.sh success "$DESCRIPTION" "$CONTEXT" "" "$URL"
+else
+  generate_index
+  cp -a "$REPORT_DIR/." "$STAGED/"
+  bash .ci/scripts/publish-git-pages.sh "$SUITE"
+  bash .ci/scripts/report-status.sh success "$DESCRIPTION" "$CONTEXT" "$SUITE"
+fi
+
+rm -rf "$STAGED"
@@ -33,7 +33,42 @@ else
 fi
 mkdir -p "$TARGET"
 cp -a "$REPORT_DIR/." "$TARGET/"
-cat > "$WORK/${OWNER}/${REPO}/reports/${SHA8}/.meta" <<EOF
+if [ ! -f "$TARGET/index.html" ]; then
+  items=()
+  while IFS= read -r -d '' f; do
+    items+=("$(basename "$f")")
+  done < <(find "$TARGET" -maxdepth 1 -type f ! -name index.html -print0 2>/dev/null || true)
+  while IFS= read -r -d '' d; do
+    name=$(basename "$d")
+    [ -f "$d/index.html" ] && items+=("$name")
+  done < <(find "$TARGET" -maxdepth 1 -type d ! -name . -print0 2>/dev/null || true)
+
+  if [ ${#items[@]} -gt 1 ]; then
+    {
+      echo '<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">'
+      echo "<title>Test report ${SHA8}</title>"
+      echo '<style>body{font-family:sans-serif;margin:2em;max-width:960px}'
+      echo 'h1{color:#1e293b}ul{list-style:none;padding:0}'
+      echo 'li{margin:.5em 0;padding:.5em;background:#f8fafc;border-radius:6px}'
+      echo 'a{color:#2563eb;text-decoration:none}a:hover{text-decoration:underline}'
+      echo '</style></head><body>'
+      echo "<h1>Test report <code>${SHA8}</code></h1><ul>"
+      for item in "${items[@]}"; do
+        label="${item%.*}"
+        label="${label//-/ }"
+        label="${label//_/ }"
+        if [ -f "$TARGET/$item" ]; then
+          echo "<li><a href=\"$item\">${label^}</a></li>"
+        else
+          echo "<li><a href=\"$item/index.html\">${label^}</a></li>"
+        fi
+      done
+      echo '</ul></body></html>'
+    } > "$TARGET/index.html"
+  fi
+fi
+
+cat > "$TARGET/.meta" <<EOF
 {"branch":"${GITHUB_REF_NAME:-}","sha":"${GITHUB_SHA}","published_at":"$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
 EOF
 find "$WORK/$OWNER" \( -type f -o -type l \) -print | sed "s|^${WORK}/||" | tar -cf "$TAR" -C "$WORK" -T -
@@ -79,16 +79,14 @@ Ei monoliittista `ci-tests.yml`. Jokainen testityyppi tai operaatio on oma `work

 ## 3. Exit-koodin käsittely

-Jokainen testi kaappaa komentonsa exit-koodin eksplisiittisesti:
+`set -e` on oletuksena käytössä Gitea Actions -stepeissä — ensimmäinen feilaava komento pysäyttää stepin
+ja exit-koodi välittyy natiivisti. Ylimääräistä `EXIT=$?` + `echo >> GITHUB_ENV` -käärettä ei tarvita.

 ```yaml
 - name: Run tests
  shell: bash
  run: |
    <testikomento> > results.txt 2>&1
-    EXIT=$?
-    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
-    exit ${EXIT}
 ```

 **Miksi ei pipeä (`| tee`):**
@@ -101,8 +99,29 @@ Jokainen testi kaappaa komentonsa exit-koodin eksplisiittisesti:
 <komento> > results.txt 2>&1
 ```

-Ilman `EXIT=$?` + `exit ${EXIT}` komento voi feilata mutta job menee läpi vihreänä — `container:`-modessa
-shellin käyttäytyminen vaihtelee.
+`set -e` ei pelasta pipe-tilanteessa — `|` syö exit-koodin kuten ennenkin. Redirectillä exit-koodi
+välittyy luonnollisesti.
+
+**Yksi asia per step:** Älä koskaan niputa useaa post-process-komentoa samaan `run:`-blockiin.
+`bash -e` pysäyttää koko stepin jos yksi komento epäonnistuu — seuraavat jäävät ajamatta.
+Käytä erillisiä steppejä `if: always()`:lla, jotta jokainen vaihe ajetaan itsenäisesti:
+
+```yaml
+# VÄÄRIN — jos coverage epäonnistuu, report jää generoimatta
+- name: Post-process reports
+  run: |
+    bash .ci/.gitea/scripts/bats-coverage.sh reports/bats
+    bash .ci/.gitea/scripts/bats-report.sh reports/bats
+
+# OIKEIN — erilliset stepit if: always()
+- name: Post-process coverage
+  if: always()
+  run: bash .ci/.gitea/scripts/bats-coverage.sh reports/bats
+
+- name: Post-process test report
+  if: always()
+  run: bash .ci/.gitea/scripts/bats-report.sh reports/bats
+```

 ## 4. Konttipolitiikka

@@ -114,44 +133,33 @@ shellin käyttäytyminen vaihtelee.
   `latest` on näille paras käytäntö, ei kompromissi
 3. **Ei koskaan `curl`-latauksia CI-ajon sisällä** — työkalujen asennus CI-stepeissä hidastaa,
   epäluotettavaa, ja vaikeuttaa toistettavuutta
+4. **Konttikuva hallitaan workflow'ssa, ei kutsujassa** — jos workflow vaatii tietyn
+   konttikuvan, se määritellään oletuksena (`default:`) workflow'n inputissa.
+   Kutsujan ei tarvitse tietää eikä välittää image-nimeä ellei halua ylikirjoittaa.

 CI-kontin build-workflow'n template: [skills/ci-container-build/SKILL.md](../ci-container-build/SKILL.md) — sisältää
 valmiin `ci-container-build-<kontti>.yml`-pohjan jossa `workflow_dispatch`-tuki manuaaliajoon.

 ### 4.1 CI-kontin ajaminen jobissa

-CI-kontin voi ajaa joko `container:`-direktiivillä (kaikki stepit kontissa)
-tai `docker run --rm`:llä stepin sisällä (checkout natiivisti). Molemmat tavat
-toimivat.
+Ainoa sallittu tapa on `container:`-direktiivi. `docker run` komennolla kontin
+käynnistäminen stepin sisällä on anti-pattern.
+
+**Miksi:** `docker run` erilliskonttina aiheuttaa:
+- Tiedostojen jako vaatii erillisen volyyminhallinnan (`docker volume create`)
+- Coverage-data jää volyymiin, ei filesystemille → post-process-skriptit eivät löydä sitä
+- Ylimääräisiä siirtoja (`tar`, `docker cp`), jotka voivat epäonnistua hiljaa
+- Vaikeampi debugata (data on kontissa, ei CWD:ssä)
+
+`container:`-direktiivillä kaikki ajetaan samassa kontissa — tiedostot ovat suoraan
+filesystemillä, post-process-skriptit näkevät ne ilman erillistä siirtoa.

 ```yaml
-# Tapa A: container:-direktiivi
 jobs:
  <työkalu>:
    runs-on: ubuntu-latest
    container:
      image: ${{ inputs.<image-name> }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/checkout@v4
-        with:
-          repository: <owner>/gitea-ci-library
-          path: .ci
-      - name: Run <työkalu>
-        shell: bash
-        run: |
-          mkdir -p "reports/${GITHUB_SHA:0:8}/<suite>"
-          <komento> > "reports/${GITHUB_SHA:0:8}/<suite>/results.txt" 2>&1
-          EXIT=$?
-          echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
-          exit ${EXIT}
-```
-
-```yaml
-# Tapa B: docker run --rm stepin sisällä (kuten example-bats-tests.yml)
-jobs:
-  <työkalu>:
-    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/checkout@v4
@@ -162,87 +170,179 @@ jobs:
      - name: Run <työkalu>
        shell: bash
        run: |
-          docker volume create ws-<suite>
-          tar c . | docker run --rm -i -v ws-<suite>:/data alpine tar x -C /data
-          mkdir -p "reports/${GITHUB_SHA:0:8}/<suite>"
-          set +e
-          docker run --rm \
-            -v ws-<suite>:/data \
-            --entrypoint bash ${{ inputs.<image-name> }} \
-            -c 'cd /data && <komento>' \
-            > "reports/${GITHUB_SHA:0:8}/<suite>/results.txt" 2>&1
-          EXIT=$?
-          docker volume rm ws-<suite> > /dev/null 2>&1
-          echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
-          exit ${EXIT}
+          mkdir -p "reports/<suite>"
+          <komento> > "reports/<suite>/results.txt" 2>&1

-      - name: Publish <suite> reports
-        if: always()
-        run: bash .ci/scripts/publish-git-pages.sh <suite>
-
-      - name: Report status
+      - name: Post-process reports
        if: always()
        run: |
-          if [ "${EXIT}" = "0" ]; then
-            bash .ci/scripts/report-status.sh success "<kuvaus>" <context> <suite>
-          else
-            bash .ci/scripts/report-status.sh failure "<kuvaus>" <context> <suite>
-          fi
+          <mahdollinen_raporttien_jälkikäsittely>
+
+      - name: Report
+        if: always()
+        run: bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite>
 ```

-**Malli:** `example-bats-tests.yml` (tapa B).
+Jos testi tuottaa raportteja suoraan ilman jälkikäsittelyä, Post-process-steppiä ei tarvita.
+Jos jälkikäsittely on tarpeen (coverage-siirto, HTML-generointi raa'asta outputista),
+se tehdään omassa stepissä `if: always()` — katso tarkemmin [Raporttitasot](#5-raporttitasot).
+
+**Mallit:**
+- `example-cucumber-tests.yml` — ei post-processia
+- `example-bats-tests.yml` — post-process coverage + report

 ## 5. Raporttitasot

-Testi tuottaa raportin `reports/${GITHUB_SHA:0:8}/<suite>/`-hakemistoon. `publish-git-pages.sh` julkaisee sen,
-`report-status.sh` linkittää commit-statusin siihen. Molemmat `if: always()`.
+Testi tuottaa raportin `reports/<suite>/`-hakemistoon. Yksi `ci-report.sh`-kutsu hoitaa sekä
+julkaisun että commit-statuksen — erillistä Publish + Report Status -kaksivaiheisuutta ei tarvita.

-### Taso 1: Pelkkä teksti
+### Taso 1: Ei jälkikäsittelyä

-Kun testi tuottaa vain stdout/stderr — tallennetaan `results.txt`:
+Kun testi tuottaa raportit suoraan (kuten `pytest --html` tai `cucumber-js --format html`):

 ```yaml
 - name: Run tests
  shell: bash
  run: |
-    mkdir -p "reports/${GITHUB_SHA:0:8}/<suite>"
-    <testikomento> > "reports/${GITHUB_SHA:0:8}/<suite>/results.txt" 2>&1
-    EXIT=$?
-    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
-    exit ${EXIT}
+    mkdir -p "reports/<suite>"
+    <testikomento>

- name: Publish reports
+- name: Report
  if: always()
-  shell: bash
-  run: bash .ci/scripts/publish-git-pages.sh <suite>
+  run: bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite>
+```

- name: Report status
-  if: always()
+### Taso 2: Jälkikäsittely tarvitaan
+
+Kun testi tuottaa raakadataa (stdout, coverage-tiedostot) joka pitää muuntaa tai siirtää
+`reports/<suite>/`-hakemistoon, käytetään Post-process-steppejä. **Jokainen operaatio
+omassa stepissään** — älä koskaan niputa useaa post-process-komentoa samaan `run:`-blockiin:
+
+```yaml
+- name: Run tests
  shell: bash
  run: |
-    if [ "${EXIT}" = "0" ]; then
-      bash .ci/scripts/report-status.sh success "<kuvaus>" <context> <suite>
-    else
-      bash .ci/scripts/report-status.sh failure "<kuvaus>" <context> <suite>
-    fi
+    mkdir -p "reports/<suite>"
+    <testikomento> > "reports/<suite>/results.txt" 2>&1
+
+- name: Post-process coverage
+  if: always()
+  run: <siirrä coverage-data reports/<suite>/coverage/-hakemistoon>
+
+- name: Post-process test report
+  if: always()
+  run: <HTML-generointi raa'asta outputista>
+
+- name: Report
+  if: always()
+  run: bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite>
 ```

-### Taso 2: HTML-raportti
+**Huomio subdir-sisällöstä:** Jos testi tuottaa dataa alihakemistoon (esim.
+coverage `./coverage/`-kansioon), se pitää erikseen SIIRTÄÄ
+`reports/<suite>/<subdir>/`-hakemistoon ennen `ci-report.sh`:n ajoa.
+Ilman siirtoa sisältö ei näy index-sivulla, vaikka työkalu tuottaisi sen oikein.
+Subdir vaatii lisäksi `index.html`:n, jotta `ci-report.sh` löytää sen.

-Kun testi tuottaa strukturoitua dataa (JUnit XML, coverage, tms.) — generoidaan HTML ja `index.html`:
+**Miksi:** Gitea Actions käyttää `bash -e`-oletusta. Jos yksi post-process-komento
+epäonnistuu (esim. `set -euo pipefail`-skripti), koko stepi pysähtyy eivätkä seuraavat
+komennot käynnisty — raportti jää julkaisematta. Erilliset stepit `if: always()` takaavat
+että jokainen post-process-vaihe ajetaan itsenäisesti.
+
+### Monta raportoitavaa tiedostoa
+
+Kun `reports/<suite>/`-hakemistossa on useita tiedostoja tai alihakemistoja,
+`ci-report.sh` generoi automaattisesti `reports/<suite>/index.html` jos hakemistossa
+on enemmän kuin yksi raportoitava item.

 ```
-reports/<sha8>/<suite>/
-├── index.html          ← generoitu: linkit alla oleviin
-├── results.txt         ← testin stdout
-├── junit.xml           ← testin JUnit XML -output
-└── junit.html          ← generoitu HTML (xsltproc, tms.)
+reports/<suite>/
+├── results.txt               ← testin stdout (skannataan FILES)
+├── test-report.html          ← generoitu HTML (skannataan FILES)
+└── <mikä tahansa>/           ← alihakemisto (skannataan SUBDIRS)
+    └── index.html            ← VAIN jos tämä on olemassa
 ```

-`index.html` linkittää kaikkiin raporttitiedostoihin. Selain avaa sen ja navigoi sieltä
-yksittäisiin raportteihin.
+**Subdir-sääntö:** Alihakemisto näkyy indexissä VAIN jos se sisältää `index.html`:n.
+Pelkkä tyhjä subdir ilman `index.html`:ää ei näy — tämä on yleisin syy miksi
+jokin raportin osa (kuten coverage) puuttuu indexistä.

-## 6. Nimeäminen
+## 6. Raportin julkaisukelpoisuus
+
+`ci-report.sh` päättää onko raportti julkaisukelpoinen skannaamalla
+`reports/<suite>/`-hakemistoa.
+
+### Mitä skannataan
+
+| Mitä | Sääntö |
+|---|---|
+| **Tiedostot (FILES)** | Kaikki `reports/<suite>/`-juuressa olevat tiedostot paitsi `index.html` |
+| **Alihakemistot (SUBDIRS)** | Vain ne, joissa on `index.html` |
+
+### Julkaisukelpoisuus
+
+| Tila | Seuraus |
+|---|---|
+| `FILES + SUBDIRS = 0` | **Failure** — `ci-report.sh` palauttaa virheen, raporttia ei julkaista |
+| `FILES + SUBDIRS = 1` | Suora linkki itemiin — ei generoi index-sivua |
+| `FILES + SUBDIRS > 1` | Generoi `reports/<suite>/index.html`-sivun, linkit kaikkiin itemeihin |
+
+### Esimerkki: coverage-näkymä
+
+```
+reports/<suite>/coverage/index.html   ← on olemassa
+```
+
+Coverage-dataa ei siirretä automaattisesti. Testin tai post-process-stepin pitää
+siirtää coverage `reports/<suite>/coverage/`-hakemistoon ja varmistaa että
+`index.html` on mukana. Sama periaate pätee mihin tahansa subdir-sisältöön.
+
+## 7. Debug-ohje: raportti ei näy
+
+### 1. Aja lokaalisti samalla komennolla kuin CI
+
+Näet mitä tiedostoja syntyy, mihin ne tulevat ja mikä on työkalun exit-koodi.
+
+```bash
+# Esimerkki
+mkdir -p reports/bats
+bashcov -- bats tests/ > reports/bats/results.txt 2>&1
+echo "exit: $?"
+ls -la reports/bats/
+```
+
+### 2. Lisää `echo "DEBUG: ..." >&2` ennen ja jälkeen kriittisen operaation
+
+Debuggaus stderriin (`>&2`) näkyy CI-logissa eikä häiritse skriptin normaalia outputia.
+
+```bash
+echo "DEBUG: coverage exists? $([ -d coverage ] && echo YES || echo NO)" >&2
+echo "DEBUG: target/index.html exists? $([ -f reports/suite/coverage/index.html ] && echo YES || echo NO)" >&2
+```
+
+### 3. Tarkista kutsuparametrit
+
+Yleisin virhe: skripti odottaa `$1` = X, mutta kutsuja antaa `$1` = Y ja `$2` = X.
+Skripti lukee väärän parametrin ja etsii dataa väärästä paikasta.
+
+### 4. Tarkista tiedostopolut
+
+1. Onko lähdetiedosto olemassa ennen kopiointia?
+2. Onko kohde olemassa kopioinnin jälkeen?
+3. Onko `index.html` subdirissä (vaaditaan `ci-report.sh`:lle)?
+
+Jos vastaus johonkin on "ei" — tiedät mikä pitää korjata.
+
+### 5. Poista debug-echot kun ongelma on korjattu
+
+Debug-rivit eivät kuulu tuotantoon.
+
+### 6. Älä kokeile — debuggaa
+
+Kokeilu = arvaus. Debuggaus = lisää echo, aja, lue logi, eristä ongelma.
+Vasta sitten korjaa. Tämä on nopeampi tie oikeaan ratkaisuun.
+
+## 8. Nimeäminen

 Tiedostonimet `.gitea/workflows/`-kansiossa noudattavat yhtenäistä rakennetta, jotta
 tiedostot löytyvät nopeasti ja niiden rooli on selvillä:
@@ -261,7 +361,7 @@ Single repossa `<komponentti>` jätetään pois — tiedostot ovat suoraan `ci-f
 Monorepossa prefiksi pitää komponentin tiedostot yhdessä: `ls <komponentti>.*` löytää kaikki
 kerralla.

-## 7. Artifact-kuri
+## 9. Artifact-kuri

 Gitea Actionsin `upload-artifact` jättää pysyvän tiedoston. Artifakteja ei käytetä
 workflow_call:ien väliseen datan siirtoon ellei se ole teknisesti välttämätöntä.
@@ -457,8 +557,9 @@ Gitean Settings → Branches → Add Rule:

 | Skripti | Käyttötarkoitus |
 |---|---|
-| `report-status.sh` | POSTaa commit-statuksen linkillä |
-| `publish-git-pages.sh` | Julkaisee raporttihakemiston git-pagesiin |
+| `ci-report.sh` | Yhdistetty raportointi: julkaisee git-pagesiin ja asettaa commit-statuksen. Korvaa erilliset `publish-git-pages.sh` + `report-status.sh` -kutsut. Käyttö: `bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite>` |
+| `report-status.sh` | POSTaa commit-statuksen linkillä (kutsutaan `ci-report.sh`:n sisältä) |
+| `publish-git-pages.sh` | Julkaisee raporttihakemiston git-pagesiin (kutsutaan `ci-report.sh`:n sisältä) |
 | `ci-validate.sh` | Validoi `.conf`-tiedoston (kutsutaan `config-provider.yml`:stä) |

 ---
@@ -499,7 +600,7 @@ Ei pipeä (`|`) komennon perässä — se syö exit-koodin. Käytä redirectiä

 ### Commit-status vain raporttilinkille (ADR 0007)

-`report-status.sh`-skriptiä käytetään VAIN kun on raportti linkitettäväksi.
+`ci-report.sh`-skriptiä käytetään VAIN kun on raportti linkitettäväksi.
 Tool-jobit (build, deploy) luottavat Gitean natiiviin job-statukseen.

 ### Providerin checkout ei kuulu consumerille