[pull] master from supabase:master

.claude/skills/studio-testing/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: studio-testing
+description: Testing strategy for Supabase Studio. Use when writing tests, deciding what
+  type of test to write, extracting logic from components into testable utility
+  functions, or reviewing test coverage. Covers unit tests, component tests,
+  and E2E test selection criteria.
+---
+
+# Studio Testing Strategy
+
+How to write and structure tests for `apps/studio/`. The core principle: push
+logic out of React components into pure utility functions, then test those
+functions exhaustively. Only use component tests for complex UI interactions.
+Use E2E tests for features shared between self-hosted and platform.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new tests for Studio code
+- Deciding which type of test to write (unit, component, E2E)
+- Extracting logic from a component to make it testable
+- Reviewing whether test coverage is sufficient
+- Adding a new feature that needs tests
+
+## Rule Categories by Priority
+
+| Priority | Category         | Impact   | Prefix     |
+| -------- | ---------------- | -------- | ---------- |
+| 1        | Logic Extraction | CRITICAL | `testing-` |
+| 2        | Test Coverage    | CRITICAL | `testing-` |
+| 3        | Component Tests  | HIGH     | `testing-` |
+| 4        | E2E Tests        | HIGH     | `testing-` |
+
+## Quick Reference
+
+### 1. Logic Extraction (CRITICAL)
+
+- `testing-extract-logic` - Remove logic from components into `.utils.ts` files
+  as pure functions: args in, return out
+
+### 2. Test Coverage (CRITICAL)
+
+- `testing-exhaustive-permutations` - Test every permutation of utility functions:
+  happy path, malformed input, empty values, edge cases
+
+### 3. Component Tests (HIGH)
+
+- `testing-component-tests-ui-only` - Only write component tests for complex UI
+  interaction logic, not business logic
+
+### 4. E2E Tests (HIGH)
+
+- `testing-e2e-shared-features` - Write E2E tests for features used in both
+  self-hosted and platform; cover clicks AND keyboard shortcuts
+
+## Decision Tree: Which Test Type?
+
+```
+Is the logic a pure transformation (parse, format, validate, compute)?
+  YES -> Extract to .utils.ts, write unit test with vitest
+  NO  -> Does the feature involve complex UI interactions?
+           YES -> Is it used in both self-hosted and platform?
+                    YES -> Write E2E test in e2e/studio/features/
+                    NO  -> Write component test with customRender
+           NO  -> Can you extract the logic to make it pure?
+                    YES -> Do that, then unit test it
+                    NO  -> Write a component test
+```
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/testing-extract-logic.md
+rules/testing-exhaustive-permutations.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Real codebase references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+
+## Codebase References
+
+| What                    | Where                                                                                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Util test examples      | `tests/components/Grid/Grid.utils.test.ts`, `tests/components/Billing/TaxID.utils.test.ts`, `tests/components/Editor/SpreadsheetImport.utils.test.ts` |
+| Component test examples | `tests/features/logs/LogsFilterPopover.test.tsx`, `tests/components/CopyButton.test.tsx`                                                              |
+| E2E test example        | `e2e/studio/features/filter-bar.spec.ts`                                                                                                              |
+| E2E helpers pattern     | `e2e/studio/utils/filter-bar-helpers.ts`                                                                                                              |
+| Custom render           | `tests/lib/custom-render.tsx`                                                                                                                         |
+| MSW mock setup          | `tests/lib/msw.ts` (`addAPIMock`)                                                                                                                     |
+| Test README             | `tests/README.md`                                                                                                                                     |
+| Vitest config           | `vitest.config.ts`                                                                                                                                    |
+| Related skills          | `e2e-studio-tests` (running E2E), `vitest` (API reference), `vercel-composition-patterns` (component architecture)                                    |

.claude/skills/studio-testing/rules/testing-component-tests-ui-only.md

@@ -0,0 +1,86 @@
+---
+title: Component Tests Are for Complex UI Logic Only
+impact: HIGH
+impactDescription: prevents slow, brittle tests that should be unit tests
+tags: testing, components, ui, react
+---
+
+## Component Tests Are for Complex UI Logic Only
+
+Only write component tests (`.test.tsx`) when there is complex UI interaction
+logic that cannot be captured by testing utility functions alone.
+
+**Valid reasons for a component test:**
+
+- Conditional rendering based on user interaction sequences
+- Popover/dropdown open/close behavior with keyboard and mouse
+- Form state transitions across multiple steps
+- Components that coordinate multiple async operations visually
+
+**Not a valid reason:** testing a calculation, transformation, parsing, or
+validation that happens to live inside a component. Extract that logic into a
+`.utils.ts` file and unit test it instead.
+
+**Incorrect (rendering a component just to test logic):**
+
+```tsx
+test('formats the display value correctly', () => {
+  render(<PriceDisplay amount={1234} currency="USD" />)
+  expect(screen.getByText('$12.34')).toBeInTheDocument()
+})
+```
+
+This is really testing a formatting function. Extract it:
+
+```ts
+// PriceDisplay.utils.ts
+export function formatPrice(amount: number, currency: string): string { ... }
+
+// PriceDisplay.utils.test.ts
+test('formats USD cents to dollars', () => {
+  expect(formatPrice(1234, 'USD')).toBe('$12.34')
+})
+```
+
+**Correct (component test for real UI interaction logic):**
+
+```tsx
+// Testing popover open/close, filter application, keyboard dismiss
+describe('LogsFilterPopover', () => {
+  test('opens popover and shows filter options', async () => {
+    customRender(<LogsFilterPopover onFiltersChange={vi.fn()} />)
+    await userEvent.click(screen.getByRole('button'))
+    expect(screen.getByText('Apply')).toBeVisible()
+  })
+
+  test('applies selected filters on submit', async () => {
+    const onChange = vi.fn()
+    customRender(<LogsFilterPopover onFiltersChange={onChange} />)
+    // ... interact with UI ...
+    await userEvent.click(screen.getByText('Apply'))
+    expect(onChange).toHaveBeenCalledWith(expectedFilters)
+  })
+
+  test('closes on Escape key', async () => {
+    customRender(<LogsFilterPopover onFiltersChange={vi.fn()} />)
+    await userEvent.click(screen.getByRole('button'))
+    await userEvent.keyboard('{Escape}')
+    expect(screen.queryByText('Apply')).not.toBeInTheDocument()
+  })
+})
+```
+
+**Studio component test conventions:**
+
+```tsx
+// Always use customRender, not raw render
+import { fireEvent } from '@testing-library/react'
+// Use userEvent for popovers, fireEvent for dropdowns
+import userEvent from '@testing-library/user-event'
+import { customRender } from 'tests/lib/custom-render'
+// Use addAPIMock for API mocking in beforeEach
+import { addAPIMock } from 'tests/lib/msw'
+```
+
+See `tests/README.md` for full conventions on custom render, MSW mocking,
+and nuqs URL parameter testing.

.claude/skills/studio-testing/rules/testing-e2e-shared-features.md

@@ -0,0 +1,98 @@
+---
+title: E2E Tests for Self-Hosted and Platform Features
+impact: HIGH
+impactDescription: ensures critical shared features work across deployment targets
+tags: testing, e2e, playwright, self-hosted, platform
+---
+
+## E2E Tests for Self-Hosted and Platform Features
+
+If a feature exists in both self-hosted and the Supabase platform, create an
+E2E test to cover it. E2E tests live in `e2e/studio/features/*.spec.ts`.
+
+**What to cover in E2E tests:**
+
+- Mouse/click interactions AND keyboard shortcuts (Tab, Enter, Escape, Arrow keys)
+- Full user flows end-to-end
+- Both adding and removing/clearing state
+- Setup and teardown (create resources in `try`, clean up in `finally`)
+
+**Incorrect (only tests mouse clicks):**
+
+```ts
+test('can add a filter', async ({ page }) => {
+  await page.getByRole('button', { name: 'Add filter' }).click()
+  await page.getByRole('option', { name: 'id' }).click()
+  // ... only click-based interactions
+})
+```
+
+**Correct (covers clicks AND keyboard shortcuts):**
+
+```ts
+test.describe('Basic Filter Operations', () => {
+  test('can add a filter by clicking', async ({ page }) => {
+    await addFilter(page, ref, 'id', 'equals', '1')
+    await expect(page.getByTestId('filter-condition')).toBeVisible()
+  })
+})
+
+test.describe('Keyboard Navigation - Freeform Input', () => {
+  test('Enter selects column from suggestions', async ({ page }) => {
+    await getFilterBarInput(page).press('Enter')
+    await expect(page.getByTestId('operator-input')).toBeFocused()
+  })
+
+  test('Backspace on empty input highlights last condition', async ({ page }) => {
+    await addFilter(page, ref, 'id', 'equals', '1')
+    await getFilterBarInput(page).press('Backspace')
+    await expect(page.getByTestId('filter-condition')).toHaveAttribute('data-highlighted', 'true')
+  })
+
+  test('Escape clears highlight', async ({ page }) => {
+    // ...
+    await getFilterBarInput(page).press('Escape')
+    await expect(page.getByTestId('filter-condition')).toHaveAttribute('data-highlighted', 'false')
+  })
+})
+```
+
+**E2E helper pattern:** Extract reusable interactions into helper files at
+`e2e/studio/utils/*-helpers.ts`:
+
+```ts
+// e2e/studio/utils/filter-bar-helpers.ts
+export async function addFilter(page, ref, column, operator, value) {
+  await selectColumnFilter(page, column)
+  await selectOperator(page, column, operator)
+  // ... fill value, wait for API response
+}
+
+export async function setupFilterBarPage(page, ref, editorUrl) {
+  await page.goto(editorUrl)
+  await enableFilterBar(page)
+  await page.reload()
+}
+```
+
+This keeps spec files focused on assertions while helpers handle the
+interaction mechanics.
+
+**Always use try/finally for resource cleanup:**
+
+```ts
+test('filters the table', async ({ page, ref }) => {
+  const tableName = await createTable(page, ref)
+  try {
+    await setupFilterBarPage(page, ref, editorUrl)
+    await navigateToTable(page, ref, tableName)
+    await addFilter(page, ref, 'id', 'equals', '1')
+    // assertions...
+  } finally {
+    await dropTable(page, ref, tableName)
+  }
+})
+```
+
+For E2E execution details (running tests, selectors, debugging), use the
+`e2e-studio-tests` skill.

.claude/skills/studio-testing/rules/testing-exhaustive-permutations.md

@@ -0,0 +1,84 @@
+---
+title: Test Every Permutation of Utility Functions
+impact: CRITICAL
+impactDescription: catches edge cases and regressions in business logic
+tags: testing, utils, coverage, permutations
+---
+
+## Test Every Permutation of Utility Functions
+
+Once logic is extracted into a pure function, test it exhaustively. Every code
+path should have a test. Don't just test the happy path.
+
+**What to cover:**
+
+- Valid inputs (happy path for each branch)
+- Invalid / malformed inputs
+- Empty values, null values, missing fields
+- Edge cases (timestamps with colons, special characters, boundary values)
+- Security-sensitive inputs (XSS payloads, external URLs) where relevant
+
+**Incorrect (only tests the happy path):**
+
+```ts
+describe('formatFilterURLParams', () => {
+  test('parses a filter', () => {
+    const result = formatFilterURLParams('id:gte:20')
+    expect(result).toStrictEqual({ column: 'id', operator: 'gte', value: '20' })
+  })
+})
+```
+
+**Correct (tests every permutation):**
+
+```ts
+describe('formatFilterURLParams', () => {
+  test('parses valid filter', () => {
+    const result = formatFilterURLParams('id:gte:20')
+    expect(result).toStrictEqual({ column: 'id', operator: 'gte', value: '20' })
+  })
+
+  test('handles timestamp with colons in value', () => {
+    const result = formatFilterURLParams('created:gte:2024-01-01T00:00:00')
+    expect(result).toStrictEqual({
+      column: 'created',
+      operator: 'gte',
+      value: '2024-01-01T00:00:00',
+    })
+  })
+
+  test('rejects malformed filter with missing parts', () => {
+    const result = formatFilterURLParams('id')
+    expect(result).toBeUndefined()
+  })
+
+  test('rejects unrecognized operator', () => {
+    const result = formatFilterURLParams('id:nope:20')
+    expect(result).toBeUndefined()
+  })
+
+  test('allows empty filter value', () => {
+    const result = formatFilterURLParams('name:eq:')
+    expect(result).toStrictEqual({ column: 'name', operator: 'eq', value: '' })
+  })
+})
+```
+
+**Another real example -- `inferColumnType` tests every data type:**
+
+```ts
+describe('inferColumnType', () => {
+  test('defaults to text for empty data', () => { ... })
+  test('defaults to text for missing column', () => { ... })
+  test('defaults to text for null values', () => { ... })
+  test('detects integer', () => { ... })       // "42" -> int8
+  test('detects float', () => { ... })          // "161.72" -> float8
+  test('detects boolean', () => { ... })        // "true"/"false" -> bool
+  test('detects boolean with nulls', () => { ... })
+  test('detects JSON object', () => { ... })    // "{}" -> jsonb
+  test('detects timestamp', () => { ... })      // multiple formats -> timestamptz
+})
+```
+
+The goal: if someone changes the function, at least one test should break for
+any behavioral change.