Skip to content

ci: play every docs demo tour in a browser at phone and desktop width - #165

Merged
lesnik512 merged 1 commit into
mainfrom
docs/demo-browser-check
Oct 16, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/demo-browser-check

Conversation

@lesnik512

Copy link
Copy Markdown
Member

The docs demos broke three times in a row in ways CI could not see: the tour spotlight drifting off its target (#162, #163) and the phone-width sideways scroll (#164). The docs job only ran mkdocs build --strict, and each fix was verified with throwaway Playwright scripts. This PR keeps that check in the repo and runs it in the docs job.

just docs-demos builds the site, serves site/ on a local port, and drives headless Chromium at 375x740 and 1280x800. On each demo page it plays every scenario's guided tour (and the retry page's herd tour). It checks the page on load, at every tour stop and after each run. A check fails if the page scrolls sideways, if the coach card is not fully inside the viewport once the stop has scrolled into place, if a tour stalls before reaching the stop count it shows ("Step 2 of 5"), or if the page throws. Demo pages are found in the built site, so a new demo page gets checked without anyone editing the list. One run takes about 30s locally, most of it the tours playing in real time, with all ten page and viewport pairs running in parallel.

Design

  • The check is a script in scripts/ run with uvx --with playwright==1.64.0. Keeping it out of pytest keeps Playwright and a browser out of the dev environment and the 11 pytest/floors jobs. The pin lives once, in the justfile, and docs-demos-browser installs the matching Chromium, with --with-deps for the runner's system libraries.
  • Because Playwright is not installed in the project environment, ty would report its import as unresolved. A [[tool.ty.overrides]] entry ignores unresolved-import for scripts/** only, so the rest of the script is still type checked, but Playwright's own types come through as unknown. The other option was adding Playwright to the lint group, which every CI job installs.
  • scripts/* joins benchmarks/* in the coverage omit list, because test-ci measures --cov=. against a 100% floor and nothing imports the script.
  • The script serves the built site/ itself. mkdocs serve would also work, but its livereload connection keeps the page from ever going network-idle.
  • The script advances the tour with a dispatched click on Continue. A real click on a coach that is off screen times out and aborts the run before it can report anything, and the on-screen check already covers whether a person could reach the button. A crash on one page is reported as a problem for that page and does not stop the others.

Testing

On current main: 5 pages x 2 viewports checked, 0 problems.

With #164's CSS change reverted (white-space: nowrap back on .hw-demo .box), it exits 1 with 12 problems, all at 375px: circuit breaker on load, then at stops 1, 2 and 5 and after the run in both scenarios (scrollWidth 379), and full stack on load and at stops 1 and 2 (scrollWidth 379, and 406 at stop 1).

To confirm the other checks fire, I also ran it with three temporary breakages: a 600px coach, a circuit breaker stop whose condition never fires, and a bulkhead page that throws on load. It exited 1 with 29 problems: the coach outside the viewport on every phone tour stop, "tour stalled after 2 of 5 stops" for both circuit breaker scenarios at both widths, and "page error: injected" for bulkhead at both widths.

just lint-ci passes, and just test-ci stays at 100% coverage with 1007 tests passing.

@lesnik512
lesnik512 merged commit 4073099 into main Oct 16, 2026
13 checks passed
@lesnik512
lesnik512 deleted the docs/demo-browser-check branch October 16, 2026 18:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant