docs(tests): record CDP probe-writing traps in the probes README

1 files changed, 13 insertions, 0 deletions

diff --git a/tests/gallery-probes/README.md b/tests/gallery-probes/README.md
index a062bfc..9b5ce7d 100644
--- a/tests/gallery-probes/README.md
+++ b/tests/gallery-probes/README.md
@@ -11,3 +11,16 @@ driven over the DevTools protocol (Node global WebSocket/fetch, no playwright).
 
 Both exit nonzero on failure. The gallery's componentization work (widgets.js extraction)
 uses a green run of these as its no-regression gate per batch.
+
+## Traps when writing new checks
+
+- Dispatch clicks on the element that owns the listener, not an ancestor; drive drags
+  with in-page synthetic PointerEvents (setPointerCapture stubbed).
+- A `find()` by textContent that matches nothing returns undefined, and the dispatch
+  no-ops silently — the check then fails looking like a widget bug. Match glyphs
+  exactly against the builder source (e.g. the transport stop button is '⏹' U+23F9,
+  not '■' U+25A0), and prefer asserting the find() hit before dispatching.
+- Reduced-motion emulation must be set before Page.navigate (launch on about:blank,
+  Emulation.setEmulatedMedia, then navigate) or the page's matchMedia snapshot misses it.
+- Kill stale headless Chromes after a crashed run; bracket the pkill pattern
+  (`pkill -f 'remote-debugging-port=934[5]'`) so it can't match its own command line.