dima/supabase

0 Fork 0

mirror of https://github.com/supabase/supabase.git synced 2026-10-05 09:25:06 +03:00

Files

T

Miranda LimonczenkoandCopilot Autofix powered by AI 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

features

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

utils

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

.gitignore

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

package.json

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

playwright.config.ts

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

README.md

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

tsconfig.json

feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120 )

2026-07-21 14:59:10 -07:00

README.md

Supabase Docs E2E Tests

Playwright end-to-end tests for the docs site under apps/docs. Add new docs journeys under features/. They all run together as one suite.

Setup

Install the Playwright browser once from this directory:

cd e2e/docs
pnpm exec playwright install chromium

Choosing a target URL

Tests run against whatever PLAYWRIGHT_BASE_URL points to, defaulting to the local docs dev server at http://localhost:3001.

Local docs server — in a separate terminal, start docs from the repo root:
```
pnpm dev:docs
```

A deployed site — set the base URL inline:

PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs

If the target is a protected Vercel preview, also set VERCEL_AUTOMATION_BYPASS_SECRET so the tests can bypass deployment protection.

The local docs server requires a full monorepo install and credentials for some content, so the quickest way to run the suite is against a deployed site. Reach for the local server only when you need to test unpublished content changes.

Running the tests

From the repo root:

pnpm e2e:docs

Or from this directory:

pnpm run e2e:docs

UI mode for debugging

pnpm e2e:docs:ui

Run a single file

pnpm run e2e:docs -- features/<name>.spec.ts

Debugging

View the HTML report after a run:

pnpm -C e2e/docs exec playwright show-report

Traces and screenshots for failures are saved in test-results/.

CI

.github/workflows/docs-e2e.yml runs this suite on pull requests that touch the tested docs pages or e2e/docs. When the PR changes apps/docs, the workflow waits for the matching Vercel preview and points PLAYWRIGHT_BASE_URL at it. When only the harness or workflow changes, Vercel skips the docs preview, so the suite falls back to production. Draft PRs are skipped until marked ready for review. The workflow can also be triggered manually with an optional base_url input that defaults to production.