Add closed shadow DOM capture via CDP

[aryanku-dev]

Summary

• Add exposeClosedShadowRoots() method using CDP to discover and expose closed shadow roots before DOM serialization
• Non-fatal: catches exceptions for non-Chromium browsers and CDP errors

Ported from percy/percy-playwright#609

Test plan

• Verify snapshot works on Chromium (closed shadow roots captured)
• Verify snapshot works on Firefox/WebKit (CDP silently skipped)
• Verify no regression on pages without shadow DOM

🤖 Generated with Claude Code

[aryanku-dev]

🤖 stack:pr-review — Automated review (BrowserStack AI harness)

Summary: Adds (1) closed shadow DOM capture via CDP (DOM.getDocument pierce:true → resolve hosts/roots into a __percyClosedShadowRoots WeakMap read by PercyDOM.serialize) and (2) a readiness gate (PercyDOM.waitForReady) run before serialize with diagnostics. Also fixes a CORS-iframe topology bug (main → same-origin → cross-origin frames were lost) and bumps version to 1.2.1-beta.0.

Priority	Category	Check	Status
High	Security	No hardcoded secrets	Pass
High	Security	Input validation	Pass — readiness config passed as structured arg, not string-interpolated
High	Security	AuthZ / IDOR / SQLi	N/A
High	Correctness	Logic & edge cases	Pass — CORS dedup via hasCrossOriginAncestor; readiness preset:disabled short-circuits; merge precedence correct
High	Correctness	Explicit error handling	Pass — catches log at debug & degrade gracefully; DOM.disable guarded by domEnabled flag
High	Correctness	No race conditions	Pass — single CDP session, sequential per-pair loop
Medium	Testing	New code / error paths tested	Pass — 6 topology/CDP + 3 readiness tests
Medium	Testing	Existing tests pass	Pass — 5 SdkTest failures are pre-existing on main (live-CLI/network), not regressions
Medium	Performance	No unbounded fetch	Pass — DOM walk bounded by page tree
Medium	Quality	Patterns / focused	Pass — mirrors canonical percy/percy-playwright index.js
Low	Quality	Names / comments / deps	Pass (after fix) — see Findings

Findings (fixed): Percy.java newly imports com.google.gson.* directly, but gson was undeclared in pom.xml (resolved only transitively via Playwright) — a future Playwright upgrade could silently break compilation. Fix: added com.google.code.gson:gson:2.10.1 as a direct dependency, pinned to the version Playwright 1.44.0 already resolves (no version skew). Build + offline tests still green.

Verification: JDK 17 / Maven 3.9.15. mvn dependency:tree + compile succeed; new tests 6/6 + 3/3 pass; existing CORS/cookie mock tests pass. The 5 remaining SdkTest failures are identical on main (verified via worktree).

Commits pushed: 8c4d1ad (declare gson as direct dependency).

Overall: ✅ Pass — Approve. No human-decision blockers; pre-existing live-CLI SdkTest failures predate this PR.

_{Posted by the BrowserStack stack:pr-review harness.}

[aryanku-dev]

Claude Code PR Review

PR: #33 • Head: 824737e • Reviewers: stack:code-reviewer

Summary

Adds (1) closed-shadow-DOM capture via a page-level CDP session (DOM.getDocument with pierce:true, a recursive walkNodes collector, and Runtime.callFunctionOn to stash each closed root in a window.__percyClosedShadowRoots WeakMap), and (2) honoring data-percy-ignore / ignoreIframeSelectors on cross-origin iframes plus a corrected CORS frame-walk for main(A) → same-origin(A) → cross-origin(B) topologies with descendant dedupe. gson is promoted to a direct dependency for CDP JSON parsing. Two new test classes (522 LOC) cover the topology fix, DOM.enable/disable pairing (success/exception/enable-failure), per-host loop isolation, and the ignore-selector matrix. CI is fully green (Java 8/11/17/21, Analyze×3, CodeQL, Semgrep, submit-maven).

Review Table

Priority	Category	Check	Status	Notes
High	Security	No hardcoded secrets/credentials	Pass	None introduced.
High	Security	Input validation / injection safe	Pass	JS sent to evaluate/callFunctionOn is static; iframe URL/selectors passed as bound args, not concatenated into JS. No SQL/shell.
High	Security	No unsafe deserialization / eval	Pass	gson parses CDP responses into typed JsonObject; el.matches try/caught; no eval of remote content.
High	Security	AuthZ/AuthN sound	N/A	No auth surface touched.
High	Correctness	No null-pointer / unchecked access	Pass	walkNodes guards every field with node.has(...); cliConfig null-checked; flag map cast guarded by instanceof.
High	Correctness	Error handling / resource cleanup	Pass	CDP session detached in finally; DOM.disable gated on domEnabled; per-pair and outer try/catch isolate failures (3 pairing tests).
High	Correctness	Concurrency / thread safety	N/A	Single-threaded snapshot flow; no shared mutable state added.
Medium	Testing	New code has tests	Pass	New tests cover the topology fix, dedupe, enable/disable pairing (3 paths), per-host isolation, selector resolution matrix.
Medium	Testing	Error/edge cases tested	Pass	about:blank/empty/no-host filtered; empty closedPairs early-returns; non-array/non-string selectors → empty no-op.
Medium	Testing	Existing tests pass	Pass	CI Test on Java 8/11/17/21 green.
Medium	Performance	No N+1 / unbounded	Pass	DOM.getDocument(depth:-1,pierce:true) once per snapshot; ignore-flag check runs before the expensive serialize.
Medium	Performance	Heavy work backgrounded	N/A	Synchronous snapshot flow.
Medium	Quality	Follows patterns	Pass	Consistent with existing file; package-private visibility intentional for testability.
Medium	Quality	Focused change	Pass	Scoped to closed-shadow + CORS-iframe ignore handling.
Low	Quality	Names / no dead code	Pass	Thorough Javadoc; Option A vs B trade-off documented; only intentional debug logs.
Low	Quality	Comments explain why	Pass	Code-level docs comprehensive; deferred OOPIF work has a tracked TODO.
Low	Quality	No unnecessary deps	Pass	gson made a direct dep with a comment explaining why; version matches Playwright 1.44.0's transitive.

Findings

No blocking issues found.

Non-blocking observations (informational):

• The gson version (2.10.1) is manually kept in sync with Playwright 1.44.0's transitive version; a future Playwright bump could drift. The comment documents this and a direct pin is the safer choice.
• OOPIF closed-shadow capture is deferred (TODO at processFrame); top-page capture works. Matches the documented design and is ticketed. The closed-shadow walker intentionally skips iframe documents (same approach as the Python SDK).

Note: the PR's Percy "visual change needs review" status is a manual dashboard approval, separate from this code review.

---

Verdict: PASS