fix(docs) Add smoke test for local development without credentials (#48218)

Closes DOCS-1210
Closes DOCS-1209

#48226 needs to merge first for CI failure

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Test coverage and several small bug fixes discovered during
implementation.

## What is the current behavior?

Nothing verified that `pnpm run dev:docs` keeps working without private
credentials.
We value this command working, especially for community contributors.

However, this issue can go undetected by employees at Supabase since
many of us have credentials in place. We do not want this to go a week
before finding and fixing like in the previous instance.

## What is the new behavior?

- **New Playwright test suite**:
`e2e/docs/local-smoke/no-credentials.spec.ts` boots the docs dev server
with zero GitHub App/Supabase secrets and checks 5 routes covering each
known failure point.
- **CI**: a new `local-dev-smoke` job in `docs-tests.yml` runs this
suite with no credentials configured.


## Additional bugs resolved

Setting up this test exposed other issues that are fixed in this PR:

- **Troubleshooting.utils.ts crash** — Unguarded Supabase call pattern,
crashing every troubleshooting article. Added the same guard as previous
fixes.
- **Missing manifest.json** — middleware.ts statically imports
public/markdown/manifest.json, which is gitignored and only generated by
a build step that's skipped in local dev. On a fresh checkout it doesn't
exist, so middleware fails to compile and takes down every page. Fixed
by committing a placeholder [] (real builds still regenerate the full
file).
- **Phantom @code-hike/mdx import** — apps/docs/app/layout.tsx imported
@code-hike/mdx/styles.css, but only apps/www actually declares that
dependency. Worked by accident whenever both apps were installed
together; broke in CI's docs-only install. Turned out to be dead code
(nothing in docs actually uses code-hike), so fixed by deleting the
unused imports rather than adding the dependency.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary by CodeRabbit

* **New Features**
* Added a credential-free “local smoke” end-to-end test suite for key
documentation routes.

* **Bug Fixes**
* Improved troubleshooting behavior when required external service
credentials are missing.
* Updated federated “wrappers” documentation pages to gracefully show a
fallback message when external content can’t be fetched.

* **Tests**
* Added a dedicated local-smoke Playwright runner and enhanced CI
path-based triggering and reporting (failure-focused artifacts).

* **Chores**
* Refined docs workflow path filters and adjusted docs markdown
manifest/ignore rules for generated content.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

e2e/docs/.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 /test-results/
 /playwright-report/
+/playwright-report-local-smoke/
 /blob-report/
 /playwright/.cache/

e2e/docs/local-smoke/no-credentials.spec.ts

@@ -0,0 +1,72 @@
+import { expect, test } from '@playwright/test'
+
+const SUPABASE_URL_ERROR = /supabaseUrl is required/i
+
+function collectPageErrors(page: import('@playwright/test').Page) {
+  const errors: string[] = []
+  page.on('pageerror', (err) => errors.push(err.message))
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') errors.push(msg.text())
+  })
+  return errors
+}
+
+test.describe('docs dev runs locally without credentials', () => {
+  test('a normal guide page renders and the feedback widget does not crash', async ({ page }) => {
+    const errors = collectPageErrors(page)
+
+    const response = await page.goto('/docs/guides/database/postgres/row-level-security')
+    expect(response?.ok(), `expected 200, got ${response?.status()}`).toBeTruthy()
+
+    const yesButton = page.getByRole('button', { name: 'Yes', exact: true })
+    await expect(yesButton).toBeVisible()
+    await yesButton.click()
+
+    expect(errors.some((message) => SUPABASE_URL_ERROR.test(message))).toBeFalsy()
+  })
+
+  test('database-advisors page renders (full content or graceful fallback, never a crash)', async ({
+    page,
+  }) => {
+    const response = await page.goto('/docs/guides/database/database-advisors')
+    expect(response?.ok(), `expected 200, got ${response?.status()}`).toBeTruthy()
+
+    await expect(
+      page.getByRole('heading', { name: 'Performance and Security Advisors' })
+    ).toBeVisible()
+  })
+
+  test('a troubleshooting article page renders without Supabase credentials', async ({ page }) => {
+    const errors = collectPageErrors(page)
+
+    const response = await page.goto('/docs/guides/troubleshooting/rls-simplified-BJTcS8')
+    expect(response?.status(), `expected 200, got ${response?.status()}`).toBe(200)
+
+    await expect(page.getByRole('heading', { name: 'RLS Simplified' })).toBeVisible()
+
+    expect(errors.some((message) => SUPABASE_URL_ERROR.test(message))).toBeFalsy()
+  })
+
+  test('a federated guide missing locally returns a clean 404, not a crash', async ({ page }) => {
+    const response = await page.goto('/docs/guides/graphql')
+    expect(response?.status()).toBe(404)
+  })
+
+  test('the wrappers overview page renders without GitHub credentials', async ({ page }) => {
+    const errors = collectPageErrors(page)
+
+    const response = await page.goto('/docs/guides/database/extensions/wrappers/overview')
+    expect(response?.status(), `expected 200, got ${response?.status()}`).toBe(200)
+
+    await expect(page.getByRole('heading', { name: 'Foreign Data Wrappers' })).toBeVisible()
+
+    expect(errors.some((message) => SUPABASE_URL_ERROR.test(message))).toBeFalsy()
+  })
+
+  test('a federated wrappers page missing locally returns a clean 404, not a crash', async ({
+    page,
+  }) => {
+    const response = await page.goto('/docs/guides/database/extensions/wrappers/stripe')
+    expect(response?.status()).toBe(404)
+  })
+})

e2e/docs/package.json

@@ -5,7 +5,8 @@
   "type": "module",
   "scripts": {
     "e2e:docs": "playwright test",
-    "e2e:ui": "playwright test --ui"
+    "e2e:ui": "playwright test --ui",
+    "e2e:docs:local-smoke": "playwright test --config=playwright.local-smoke.config.ts"
   },
   "dependencies": {
     "@playwright/test": "^1.59.1"

e2e/docs/playwright.local-smoke.config.ts

@@ -0,0 +1,56 @@
+import { defineConfig } from '@playwright/test'
+
+const IS_CI = !!process.env.CI
+
+const WEB_SERVER_PORT = Number(process.env.WEB_SERVER_PORT) || 3001
+
+export default defineConfig({
+  testDir: './local-smoke',
+  testMatch: /.*\.spec\.ts/,
+  timeout: 90_000,
+  forbidOnly: IS_CI,
+  retries: IS_CI ? 2 : 0,
+  maxFailures: 3,
+  expect: {
+    timeout: 15_000,
+  },
+  fullyParallel: false,
+  workers: 1,
+  use: {
+    baseURL: `http://localhost:${WEB_SERVER_PORT}`,
+    browserName: 'chromium',
+    headless: true,
+    // Higher than usual: each run boots a fresh dev server, so the first
+    // request to a route pays Next.js's on-demand compile cost.
+    navigationTimeout: 60_000,
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
+    video: 'off',
+  },
+  reporter: IS_CI
+    ? [['list'], ['html', { open: 'never', outputFolder: './playwright-report-local-smoke' }]]
+    : [
+        ['list'],
+        ['html', { open: 'never', outputFolder: './playwright-report-local-smoke' }],
+        ['json', { outputFile: './test-results/local-smoke-results.json' }],
+      ],
+  outputDir: './test-results',
+  // Explicitly cleared so this suite is credential-free even if the local
+  // .env.local has real secrets, and never reused so a server already
+  // running on this port (possibly with real credentials) can't be reused.
+  webServer: {
+    command: 'pnpm --workspace-root run dev:docs',
+    port: WEB_SERVER_PORT,
+    timeout: 4 * 60 * 1000,
+    reuseExistingServer: false,
+    env: {
+      DOCS_GITHUB_APP_PRIVATE_KEY: '',
+      DOCS_GITHUB_APP_ID: '',
+      DOCS_GITHUB_APP_INSTALLATION_ID: '',
+      SUPABASE_SECRET_KEY: '',
+      OPENAI_API_KEY: '',
+      DOCS_REVALIDATION_KEYS: '',
+      DOCS_REVALIDATION_OVERRIDE_KEYS: '',
+    },
+  },
+})