1 Commits

Author	SHA1	Message	Date
Miranda Limonczenko	9199aad57e	feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120) ... Closes DOCS-1197 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem We do not have any E2E testing established. ## Solution This PR creates an ultra-lean starting place for Docs Playwright: - A CI/CD step that skips on draft and relies on Preview for testing - One simple broken link check for one page The goal: - Playwright is implemented where we want it, with an architecture we want, with set-up steps we can build from The anti-goal of this PR: - We have meaningful tests running ## CI/CD steps <img width="1191" height="72" alt="Screenshot 2026-07-21 at 10 17 06 AM" src="https://github.com/user-attachments/assets/eeb2454c-d864-4574-a050-ce39bb3f083f" /> 1. Checkout a thin slice of the repo (`apps/docs`, `packages`, `patches`). 2. Wait for the Vercel **docs** preview for that commit SHA. 3. Use that preview URL as `PLAYWRIGHT_BASE_URL`. 4. Install Node deps and Chromium. 5. Run `pnpm run e2e:docs` (`--grep @quickstart`). 6. If anything fails, upload the HTML report + traces. Manual runs skip the Vercel wait and default to `https://supabase.com` (or whatever URL you enter), then run the full suite (`pnpm run e2e`). ## What the test checks Because this PR is scaffolding, it is doing something very basic: 1. Opens `/docs/guides/getting-started/quickstarts/nextjs` only if a connected file was edited in CI/CD step 2. Asserts the page loaded and the H1 is visible. 3. Collects docs-owned `/docs/**` links from `#sb-docs-guide-main-article`. 4. HTTP-checks each link (no full navigation) and soft-fails so every broken link is reported. Config keeps it cheap: Chromium only, 1 worker, 2 CI retries, failure screenshots/traces. ## Docs vs Studio/Dashboard The setup of Docs Playwright differs from Studio. | | Docs E2E | Studio E2E | |---|---|---| | Location |`e2e/docs/` | `e2e/studio/` | | What it tests | One published docs page + its links | Many Studio UI flows (tables, auth, storage, …) | | Where the app runs | Already-deployed **Vercel preview** | Built and started **on the runner** | | Backend needed | None | Local Supabase via Docker | | Path filtering | Native `on.pull_request.paths` (skip whole workflow) | `dorny/paths-filter` after checkout (workflow starts, heavy steps gated) | | Parallelism | 1 worker, no shards | Matrix of frameworks × 2 shards | | Retries | 2 in CI | 5 in CI | | Reports | HTML report on failure | Blob reports per shard → merge → PR comment | | Draft handling | Explicit draft skip | No draft skip today | | Manual broader run | Yes (`workflow_dispatch`) | No | The big conceptual difference: **Studio owns the environment** (build Studio, start Supabase, hit `localhost`). **Docs borrows Vercel’s preview** and only asks “does this page and its docs links work on the deployed site?” ## Docs architecture justification The docs architecture is deliberately lightweight because docs are **static, published content served by Vercel**, not an interactive app with a backend. That single fact justifies every difference: - **Borrow the Vercel preview instead of building on the runner.** The preview is already the exact artifact users will see, and Vercel builds it for free on every PR. Rebuilding docs on the runner would duplicate that work and risk testing something different from what ships. Studio, by contrast, needs a running app plus a local Supabase, so it *has* to own its environment. - **No backend.** Docs pages don't need a database or auth to render, so there's nothing to spin up. This is what keeps the job cheap enough to run per-PR. - **Native `paths` filtering.** Since the job is cheap and self-contained, an all-or-nothing skip at the workflow level is sufficient—no need for `dorny/paths-filter` to gate expensive setup steps mid-run like Studio does. - **Low parallelism and modest retries.** One page and its links is a tiny surface, so 1 worker is plenty and there's no sharding to coordinate. Retries exist only to absorb transient network flakiness against a live URL, hence 2 rather than Studio's 5 (which also cushions a heavier, stateful environment). - **Non-blocking + draft skip + manual dispatch.** As initial scaffolding checking link health on a deployed site, it should inform rather than gate merges, avoid burning minutes on drafts, and still be runnable on demand against production. In short: **Studio owns its environment because it must; docs borrows Vercel's preview because it can.** The scope is intentionally minimal today. ## Testing 1. Break a docs-owned link in the Next.js quickstart. 1. Follow README instructions to set up and run e2e docs test. 1. Confirm the suite fails. 1. Restore the broken link and re-run. 1. Confirm the suite **passes** (`1 passed`). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary - **New Features** - Added a GitHub Actions workflow to run Playwright docs end-to-end tests on PRs and via manual dispatch (with optional base URL), including docs-preview waiting and concurrency cancellation. - **Documentation** - Added `e2e/docs` README with setup, how to run the suite (including UI/debug and single-spec), and how base URL selection works. - **Tests** - Added a quickstarts E2E spec that validates the page and soft-checks docs-owned links resolve. - **Chores** - Added shared Playwright configuration/package scripts and an `e2e/docs` `.gitignore` for test outputs. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-07-21 14:59:10 -07:00