From 3e784463288deef42beb1f509eff1983c723a2ad Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Mon, 14 Sep 2026 15:15:08 -0700
Subject: [PATCH] devops: verify javadoc jar contents in CI

Javadoc errors don't fail the build, so a misconfiguration can silently
produce an empty javadoc jar (see #1979). Check the jar for a minimum
number of class pages and a few key pages on JDK 21.
---
 .github/workflows/test.yml |  3 +++
 scripts/verify_javadoc.sh  | 52 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100755 scripts/verify_javadoc.sh

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index b15c361d0..e454c79c0 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -119,6 +119,9 @@ jobs:
         run: scripts/download_driver.sh
       - name: Build & Install
         run: mvn -B install -D skipTests --no-transfer-progress
+      # Runs on JDK 21: with JDK 8 the javadoc plugin never uses the module path.
+      - name: Verify javadoc
+        run: scripts/verify_javadoc.sh
       - name: Install browsers
         run: mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps" -f playwright/pom.xml --no-transfer-progress
       - name: Run tests
diff --git a/scripts/verify_javadoc.sh b/scripts/verify_javadoc.sh
new file mode 100755
index 000000000..1ed02de8e
--- /dev/null
+++ b/scripts/verify_javadoc.sh
@@ -0,0 +1,52 @@
+#!/bin/bash
+
+# Checks that the javadoc jar produced by `mvn package` documents the public API.
+# Javadoc errors don't fail the build (failOnError is false), so a misconfiguration
+# can silently produce an empty jar.
+
+set -e
+set +x
+
+trap "cd $(pwd -P)" EXIT
+cd "$(dirname $0)/.."
+
+JARS=(playwright/target/playwright-*-javadoc.jar)
+if [[ ${#JARS[@]} -ne 1 || ! -f "${JARS[0]}" ]]; then
+  echo "ERROR: expected exactly one javadoc jar, found: ${JARS[*]}"
+  exit 1
+fi
+JAR=${JARS[0]}
+ENTRIES=$(jar tf "$JAR")
+
+FAILED=0
+
+# Class pages, excluding class-use/ and package-summary/tree/use pages.
+CLASS_PAGES=$(echo "$ENTRIES" | grep -E '^com/microsoft/playwright/.*\.html$' | grep -v -E '/class-use/|/package-[a-z]+\.html$' | wc -l)
+MIN_CLASS_PAGES=300
+echo "$JAR: $CLASS_PAGES class pages"
+if [[ $CLASS_PAGES -lt $MIN_CLASS_PAGES ]]; then
+  echo "ERROR: expected at least $MIN_CLASS_PAGES class pages"
+  FAILED=1
+fi
+
+for page in \
+    index.html \
+    com/microsoft/playwright/Page.html \
+    com/microsoft/playwright/Locator.html \
+    com/microsoft/playwright/options/Cookie.html \
+    com/microsoft/playwright/assertions/PlaywrightAssertions.html \
+    com/microsoft/playwright/junit/UsePlaywright.html; do
+  if ! echo "$ENTRIES" | grep -q -x -F "$page"; then
+    echo "ERROR: missing $page"
+    FAILED=1
+  fi
+done
+
+IMPL_PAGES=$(echo "$ENTRIES" | grep -E '^com/microsoft/playwright/impl/[^/]+\.html$' || true)
+if [[ -n "$IMPL_PAGES" ]]; then
+  echo "ERROR: com.microsoft.playwright.impl should be excluded, found:"
+  echo "$IMPL_PAGES"
+  FAILED=1
+fi
+
+exit $FAILED