Apply pytest improvements to storybook workflow

- Create test-storybook-runner.yml as a simple reusable runner
  (analogous to test-py-pytest.yml)
- Add parallel_workers input with cgroup-aware auto-detection
- Add smart caching for target branch results with pending marker
  pattern to avoid duplicate test runs across concurrent PRs
- Refactor test-storybook.yml to use the new runner for source
  branch testing while maintaining inline target branch testing
  with caching
- Add consistent outputs for regression analysis compatibility
- Update usage.mmd to reflect new architecture

Author: claude

.github/workflows/test-storybook-runner.yml

@@ -0,0 +1,389 @@
+name: Reusable Storybook Runner
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "Git ref to checkout and test. Leave empty for default checkout."
+        required: false
+        type: string
+        default: ""
+      node-version:
+        description: "Node.js version to use for Storybook tests."
+        required: false
+        type: string
+        default: "18.x"
+      runs_on:
+        description: "Runner label for the test job."
+        required: false
+        type: string
+        default: '["self-hosted", "multithreaded"]'
+      artifact_name:
+        description: "Name for the test results artifact."
+        required: true
+        type: string
+      parallel_workers:
+        description: "Number of parallel workers (shards) for Storybook tests. Leave empty for runner default (6 for multithreaded, 1 for singlethreaded). Use 'auto' for cgroup-aware CPU count, or a number."
+        required: false
+        type: string
+        default: ""
+      storybook_port:
+        description: "Port for Storybook server."
+        required: false
+        type: string
+        default: "6006"
+      storybook_build_command:
+        description: "Command to build Storybook. Leave empty to use dev server instead."
+        required: false
+        type: string
+        default: ""
+      storybook_start_command:
+        description: "Command to start Storybook server. Uses 'npm run storybook' by default."
+        required: false
+        type: string
+        default: "npm run storybook"
+      storybook_test_command:
+        description: "Command to run Storybook tests. Uses 'npm run storybook-test' by default."
+        required: false
+        type: string
+        default: "npm run storybook-test"
+    outputs:
+      total:
+        description: "Total number of tests"
+        value: ${{ jobs.test.outputs.total }}
+      passed:
+        description: "Number of passing tests"
+        value: ${{ jobs.test.outputs.passed }}
+      percentage:
+        description: "Pass percentage"
+        value: ${{ jobs.test.outputs.percentage }}
+      collection_errors:
+        description: "Whether collection errors occurred"
+        value: ${{ jobs.test.outputs.collection_errors }}
+      no_tests_found:
+        description: "Whether no tests were found"
+        value: ${{ jobs.test.outputs.no_tests_found }}
+      has_errors:
+        description: "Whether any errors occurred"
+        value: ${{ jobs.test.outputs.has_errors }}
+      error_type:
+        description: "Type of error if any"
+        value: ${{ jobs.test.outputs.error_type }}
+      failing_count:
+        description: "Number of failing tests"
+        value: ${{ jobs.test.outputs.failing_count }}
+      error_count:
+        description: "Number of errored tests"
+        value: ${{ jobs.test.outputs.error_count }}
+      skipped_count:
+        description: "Number of skipped tests"
+        value: ${{ jobs.test.outputs.skipped_count }}
+      xfailed_count:
+        description: "Number of xfailed tests"
+        value: ${{ jobs.test.outputs.xfailed_count }}
+
+jobs:
+  test:
+    runs-on: ${{ fromJSON(inputs.runs_on) }}
+    outputs:
+      total: ${{ steps.extract-results.outputs.total }}
+      passed: ${{ steps.extract-results.outputs.passed }}
+      percentage: ${{ steps.extract-results.outputs.percentage }}
+      collection_errors: ${{ steps.check-stories.outputs.has_collection_errors }}
+      no_tests_found: ${{ steps.check-stories.outputs.no_tests_found }}
+      has_errors: ${{ steps.check-stories.outputs.has_errors }}
+      error_type: ${{ steps.check-stories.outputs.error_type }}
+      failing_count: ${{ steps.extract-results.outputs.failing_count }}
+      error_count: ${{ steps.extract-results.outputs.error_count }}
+      skipped_count: ${{ steps.extract-results.outputs.skipped_count }}
+      xfailed_count: ${{ steps.extract-results.outputs.xfailed_count }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.2.2
+        with:
+          submodules: "recursive"
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Use Node.js ${{ inputs.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Check for story collection errors
+        id: check-stories
+        run: |
+          echo "Checking for Storybook stories..."
+          HAS_COLLECTION_ERRORS="false"
+          NO_TESTS_FOUND="false"
+          ERROR_TYPE="none"
+
+          # Check if storybook config exists
+          if ! ls .storybook/main.* 2>/dev/null; then
+            echo "::error::No Storybook configuration found"
+            HAS_COLLECTION_ERRORS="true"
+            ERROR_TYPE="NoStorybookConfig"
+          else
+            # Try to find stories by checking for story files
+            STORY_COUNT=$(find . -name "*.stories.*" -o -name "*.story.*" 2>/dev/null | grep -v node_modules | wc -l || echo "0")
+            if [[ "$STORY_COUNT" == "0" ]]; then
+              echo "::warning::No story files were found"
+              NO_TESTS_FOUND="true"
+              ERROR_TYPE="NoStoriesFound"
+            else
+              echo "Found $STORY_COUNT story files"
+            fi
+          fi
+
+          echo "has_collection_errors=$HAS_COLLECTION_ERRORS" >> "$GITHUB_OUTPUT"
+          echo "no_tests_found=$NO_TESTS_FOUND" >> "$GITHUB_OUTPUT"
+          echo "error_type=$ERROR_TYPE" >> "$GITHUB_OUTPUT"
+          if [[ "$HAS_COLLECTION_ERRORS" == "true" || "$NO_TESTS_FOUND" == "true" ]]; then
+            echo "has_errors=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_errors=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build Storybook
+        if: ${{ inputs.storybook_build_command != '' && steps.check-stories.outputs.has_collection_errors != 'true' }}
+        run: ${{ inputs.storybook_build_command }}
+
+      - name: Start Storybook server
+        if: steps.check-stories.outputs.has_collection_errors != 'true'
+        run: |
+          ${{ inputs.storybook_start_command }} -- --port ${{ inputs.storybook_port }} &
+          echo "STORYBOOK_PID=$!" >> $GITHUB_ENV
+
+      - name: Wait for Storybook
+        if: steps.check-stories.outputs.has_collection_errors != 'true'
+        run: |
+          echo "Waiting for Storybook to start on port ${{ inputs.storybook_port }}..."
+          timeout=120
+          counter=0
+          until curl --output /dev/null --silent --head --fail http://localhost:${{ inputs.storybook_port }}; do
+            if [ $counter -ge $timeout ]; then
+              echo "::error::Timed out waiting for Storybook to start"
+              exit 1
+            fi
+            echo "Waiting for Storybook... ($counter seconds so far)"
+            sleep 5
+            counter=$((counter + 5))
+          done
+          echo "Storybook is up and running on port ${{ inputs.storybook_port }}!"
+
+      - name: Run Storybook tests
+        id: run-tests
+        continue-on-error: true
+        if: steps.check-stories.outputs.has_collection_errors != 'true'
+        run: |
+          set -euo pipefail
+
+          cgroup_auto_workers() {
+            local n=""
+
+            # cgroup v2: /sys/fs/cgroup/cpu.max => "<quota> <period>" or "max <period>"
+            if [ -f /sys/fs/cgroup/cpu.max ]; then
+              local quota period
+              quota="$(awk '{print $1}' /sys/fs/cgroup/cpu.max)"
+              period="$(awk '{print $2}' /sys/fs/cgroup/cpu.max)"
+              if [ -n "$quota" ] && [ -n "$period" ] && [ "$quota" != "max" ] && [ "$period" != "0" ]; then
+                n="$(awk -v q="$quota" -v p="$period" 'BEGIN{print int((q+p-1)/p)}')"
+              fi
+            fi
+
+            # cgroup v1: cpu.cfs_quota_us / cpu.cfs_period_us
+            if [ -z "$n" ] && [ -f /sys/fs/cgroup/cpu/cpu.cfs_quota_us ] && [ -f /sys/fs/cgroup/cpu/cpu.cfs_period_us ]; then
+              local quota period
+              quota="$(cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us)"
+              period="$(cat /sys/fs/cgroup/cpu/cpu.cfs_period_us)"
+              if [ "$quota" -gt 0 ] && [ "$period" -gt 0 ]; then
+                n="$(awk -v q="$quota" -v p="$period" 'BEGIN{print int((q+p-1)/p)}')"
+              fi
+            fi
+
+            # cpuset fallback (v2: /sys/fs/cgroup/cpuset.cpus ; v1: /sys/fs/cgroup/cpuset/cpuset.cpus)
+            if [ -z "$n" ]; then
+              local f=""
+              if [ -f /sys/fs/cgroup/cpuset.cpus ]; then
+                f="/sys/fs/cgroup/cpuset.cpus"
+              elif [ -f /sys/fs/cgroup/cpuset/cpuset.cpus ]; then
+                f="/sys/fs/cgroup/cpuset/cpuset.cpus"
+              fi
+
+              if [ -n "$f" ]; then
+                local spec
+                spec="$(cat "$f" | tr -d '[:space:]')"
+                if [ -n "$spec" ]; then
+                  local count=0
+                  IFS=',' read -r -a parts <<< "$spec"
+                  for p in "${parts[@]}"; do
+                    if [[ "$p" == *-* ]]; then
+                      local a="${p%%-*}"
+                      local b="${p##*-}"
+                      if [[ "$a" =~ ^[0-9]+$ && "$b" =~ ^[0-9]+$ && "$b" -ge "$a" ]]; then
+                        count=$((count + b - a + 1))
+                      fi
+                    elif [[ "$p" =~ ^[0-9]+$ ]]; then
+                      count=$((count + 1))
+                    fi
+                  done
+                  if [ "$count" -gt 0 ]; then
+                    n="$count"
+                  fi
+                fi
+              fi
+            fi
+
+            if [ -z "$n" ] || [ "$n" -lt 1 ] 2>/dev/null; then
+              n="1"
+            fi
+
+            echo "$n"
+          }
+
+          WORKERS="${{ inputs.parallel_workers }}"
+          if [ -z "$WORKERS" ]; then
+            if echo '${{ inputs.runs_on }}' | grep -q "multithreaded"; then
+              WORKERS="6"
+            else
+              WORKERS="1"
+            fi
+          elif [ "$WORKERS" = "auto" ]; then
+            WORKERS="$(cgroup_auto_workers)"
+          fi
+
+          echo "Running Storybook tests with $WORKERS workers..."
+
+          # Build the shard flag if workers > 1
+          SHARD_FLAGS=""
+          if [ "$WORKERS" != "1" ]; then
+            # Storybook test-runner supports --shard for parallelization
+            # We run all shards in sequence here, or you can use matrix strategy
+            SHARD_FLAGS="--maxWorkers=$WORKERS"
+          fi
+
+          set +e
+          ${{ inputs.storybook_test_command }} -- --url http://localhost:${{ inputs.storybook_port }} $SHARD_FLAGS --json --outputFile=results.json 2>&1 | tee test_output.txt
+          TEST_EXIT=$?
+          set -e
+
+          echo "test_exit_code=$TEST_EXIT" >> "$GITHUB_OUTPUT"
+
+          if [ $TEST_EXIT -eq 137 ]; then
+            echo "::warning::Tests were killed (exit 137) - likely OOM. Partial results may be available."
+          fi
+
+          if [ -f results.json ]; then
+            echo "Test execution completed (exit code: $TEST_EXIT)"
+          else
+            echo "No results.json - creating empty results file"
+            echo '{"testResults": [], "numTotalTests": 0, "numPassedTests": 0, "numFailedTests": 0}' > results.json
+          fi
+
+      - name: Extract test results
+        id: extract-results
+        run: |
+          # Use the storybook normalizer script if available, otherwise inline
+          if [ -f "$GITHUB_WORKSPACE/.github/scripts/storybook_results_to_standard_json.py" ]; then
+            python3 "$GITHUB_WORKSPACE/.github/scripts/storybook_results_to_standard_json.py" \
+              results.json \
+              test_data.json \
+              --github-output "$GITHUB_OUTPUT"
+          else
+            # Inline extraction for repositories without the script
+            python3 -c "
+          import json
+          import os
+
+          total = passed = 0
+          percentage = 0.0
+          passing_tests = []
+          failing_tests = []
+          error_tests = []
+          skipped_tests = []
+          xfailed_tests = []
+          all_tests = []
+
+          try:
+              with open('results.json') as f:
+                  results = json.load(f)
+
+              # Handle Jest-style output from storybook test-runner
+              if 'testResults' in results:
+                  for suite in results.get('testResults', []):
+                      for assertion in suite.get('assertionResults', []):
+                          name = assertion.get('fullName') or assertion.get('title', '')
+                          if not name:
+                              continue
+                          all_tests.append(name)
+                          status = assertion.get('status', '').lower()
+                          if status == 'passed':
+                              passing_tests.append(name)
+                          elif status == 'failed':
+                              failing_tests.append(name)
+                          elif status == 'skipped' or status == 'pending':
+                              skipped_tests.append(name)
+
+              total = len(all_tests)
+              passed = len(passing_tests)
+              percentage = (passed / total * 100) if total > 0 else 0
+          except FileNotFoundError:
+              print('Results file not found')
+          except Exception as e:
+              print(f'Error: {e}')
+
+          # Save artifact data
+          with open('test_data.json', 'w') as f:
+              json.dump({
+                  'passing_tests': passing_tests,
+                  'failing_tests': failing_tests,
+                  'error_tests': error_tests,
+                  'skipped_tests': skipped_tests,
+                  'xfailed_tests': xfailed_tests,
+                  'all_tests': all_tests,
+                  'warnings': []
+              }, f, indent=2)
+
+          print(f'Results: {passed}/{total} ({percentage:.1f}%)')
+
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write(f'total={total}\n')
+              f.write(f'passed={passed}\n')
+              f.write(f'percentage={percentage:.2f}\n')
+              f.write(f'failing_count={len(failing_tests)}\n')
+              f.write(f'error_count={len(error_tests)}\n')
+              f.write(f'skipped_count={len(skipped_tests)}\n')
+              f.write(f'xfailed_count={len(xfailed_tests)}\n')
+              f.write(f'no_tests_found={\"true\" if total == 0 else \"false\"}\n')
+              f.write(f'collection_errors=false\n')
+              f.write(f'has_failures={\"true\" if failing_tests else \"false\"}\n')
+          "
+          fi
+
+      - name: Stop Storybook server
+        if: always()
+        run: |
+          if [ -n "${STORYBOOK_PID:-}" ]; then
+            kill $STORYBOOK_PID 2>/dev/null || true
+          fi
+          # Also kill any stray node processes running storybook
+          pkill -f "storybook" 2>/dev/null || true
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact_name }}
+          path: |
+            test_data.json
+            test_output.txt
+            results.json
+          retention-days: 3
+          if-no-files-found: ignore