Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs: consolidate agent instructions and verification guidance (#21381)

p0nyaaa7028d16fc
diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md
index 744f7abca8..2b84a5da42 100644
--- a/.claude/skills/verify/SKILL.md
+++ b/.claude/skills/verify/SKILL.md
@@ -1,58 +1,43 @@
---
name: verify
-description: Build, launch, and drive Bytebase end-to-end to verify a change against the running app (backend + production frontend bundle + Playwright).
+description: Build and drive Bytebase with the Playwright E2E harness when a change needs verification against the running app.
---
-# Verifying Bytebase changes against the running app
+# Verify against the running app
-## Build the app (production bundle, embedded)
+Run commands from the repository root unless a command changes directory.
+Read [the E2E README](../../../frontend/tests/e2e/README.md) for prerequisites,
+license configuration, browser selection, and troubleshooting. Before writing
+or changing tests, read [the E2E instructions](../../../frontend/tests/e2e/AGENTS.md).
+
+## Build
```bash
-pnpm --dir frontend release # vite build → backend/server/dist
+pnpm --dir frontend release
go build -tags embed_frontend -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
```
-The `embed_frontend` tag is required — without it the binary serves no UI.
+The `embed_frontend` tag is required to serve the UI. Rebuild the affected
+frontend bundle/backend binary after code changes so the test exercises the fix.
-## Drive it with the e2e harness
+## Run the affected scenario
-The harness (`frontend/tests/e2e/`) boots a fresh instance per run: embedded
-Postgres, first-signup admin (`[email protected]` / `12345678`), and sample
-instances via `POST /v1/actuator:setupSample` (hr_prod / hr_test with the
-employee schema).
+With `BYTEBASE_E2E_LICENSE` configured as described in the README:
```bash
cd frontend
-export BYTEBASE_E2E_LICENSE=$(grep BB_DEV_ENTERPRISE_LICENSE .env.dev-local | cut -d= -f2)
-pnpm exec playwright test sql-editor/<spec>.spec.ts --reporter=list
+pnpm exec playwright test sql-editor/sql-editor-lsp.spec.ts --reporter=list
```
-- License is mandatory (suite is enterprise-only); the dev enterprise JWT in
- `frontend/.env.dev-local` works.
-- If the Playwright browser download hangs (it has here — 40min stall), use
- the locally installed Chrome instead: `export BYTEBASE_BROWSER_CHANNEL=chrome`
- (wired through `playwright.config.ts` `use.channel`).
-- Server boot takes 3–6 min (embedded PG + migrations + sample instances);
- it is spent in globalSetup, not test time.
-
-## Iterating without a 6-min reboot per attempt
-
-For debugging, boot a standalone server once and drive it with a plain
-Playwright script; a reusable pair of scripts exists in session scratchpads
-under `lsp-debug/` (boot-server.mjs / drive.mjs pattern): spawn
-`bytebase-build/bytebase --port <p> --data <tmp>` with `PG_URL=""`, poll
-`/healthz`, signup/login via `/v1/auth/*`, `POST /v1/actuator:setupSample`,
-poll `/v1/instances` until the sample databases appear.
-
-## Gotchas observed
-
-- `ControlOrMeta+a` select-all in Monaco is unreliable on macOS headless
- Chrome — clear buffers by backspacing the measured content length
- (see `setBuffer` in `sql-editor/sql-editor-lsp.spec.ts`).
-- Clicking a suggest-widget row to accept is flaky; assert on the row's
- visibility and dismiss with Escape.
-- The LSP connection indicator text ("connected") lives in a hover tooltip —
- don't locate it; assert on websocket frames instead (see the
- `page.on("websocket")` frame capture in the LSP spec).
-- Backend LSP capabilities: completion (trigger chars `.` and space) and
- executeCommand only — no hover.
+Replace the example spec with the scenario relevant to the change. The harness
+owns disposable server startup, authentication, sample-instance provisioning,
+and teardown; use its current implementation rather than hand-rolling bootstrap.
+When a browser download is unavailable, `BYTEBASE_BROWSER_CHANNEL=chrome` selects
+a locally installed Chrome.
+
+## Evidence
+
+Verify the user-visible outcome, including the failure path relevant to the
+change. For LSP work, consult the existing LSP spec's buffer helpers and websocket
+assertions; connection status is a tooltip, not persistent page text.
+Report the scenario, result, and any missing prerequisite or unverified behavior.
diff --git a/AGENTS.md b/AGENTS.md
index 9f907debec..7a4891cb30 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,3 @@
-This file provides guidance to AI coding assistants when working with code in this repository.
-
## Design Principles
Bytebase is the standard for database development. Every product and engineering decision serves that goal, built on three principles:
@@ -8,264 +6,61 @@ Bytebase is the standard for database development. Every product and engineering
2. **Govern change and access as code.** Reviewed, enforced, and recorded by policy, not by discipline.
3. **Make the safe path the easy path.** Safe by default, simple by design — so no one routes around it.
-## Agent skills
-
-### Issue tracker
-
-Issues are tracked in Linear via Linear MCP when available, falling back to `linctl`; agent-created issues go to Linear team `BOT`; GitHub PRs may link back to Linear issues, but GitHub Issues and PRs are not the triage surface. See `docs/agents/issue-tracker.md`.
-
-### Triage labels
-
-Triage roles use the default canonical labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. See `docs/agents/triage-labels.md`.
-
-### Domain docs
-
-This repo uses a single-context domain-doc layout. See `docs/agents/domain.md`.
-
-## Project Architecture
-
-- Database schema is defined in `./backend/migrator/migration/LATEST.sql`
-- Database migration files are in `./backend/migrator/<<version>>/`
- - `TestLatestVersion` in `./backend/migrator/migrator_test.go` needs update after new migration files are added
- - `./backend/migrator/migration/LATEST.sql` should be updated for DDL migrations
-- Files in `./backend/store` are mappings to the database tables
-
-Anything that writes SQL against the metadata database is governed by
-[`backend/store/AGENTS.md`](backend/store/AGENTS.md): composite-primary-key
-predicates, pagination ordering, and transaction row-lock ordering. That means
-all of `backend/store/` — including the CEL-to-SQL filter builders, which live
-there and not in the service layer — plus the raw metadata reads in the
-`backend/tests/` collision tests. Read it before adding or modifying a query, a
-paginated list, or a multi-row transaction.
-
-## Testing
-
-Test API and workflow behavior against Postgres only — engine dialects and DDL
-fidelity belong in [omni](https://github.com/bytebase/omni), so never write
-`TestFooForMySQL` beside `TestFooForPostgreSQL`. A test earns a Bytebase server
-boot only if it needs a background runner, a real rollout, or the audit trail —
-those live in `backend/tests`, the only package that may start one; everything
-else asserts in `backend/api/v1` or `backend/store`.
-
-A package needing a real metadata Postgres shares one through
-`testcontainer.Main` and `testcontainer.NewMetadataDB`, never its own
-container; a package needing a target engine shares one the same way through
-`testcontainer.SharedPgContainer` and its siblings, with `NewPgDatabase` for
-a database per test. Prefer needing none: extract the
-decide-and-convert half of a handler as functions over plain data, and where
-state is genuinely read declare an interface beside the handler and fake it, as
-`backend/api/mcp` does with `serverStore` — never one interface over the whole
-store, which has 305 methods.
-Every fake needs a contract test run against the real store too, or it drifts
-into testing itself.
-
-## Development Workflow
-
-**ALWAYS follow these steps after making code changes:**
-
-### Go Code Changes
+## Read before working
-1. **Format** — Run `gofmt -w` on modified files
-2. **Lint** — Run `golangci-lint run --allow-parallel-runners` to catch issues
- - **Important**: Run golangci-lint repeatedly until there are no issues (the linter has a max-issues limit and may not show all issues in a single run)
-3. **Auto-fix** — Use `golangci-lint run --fix --allow-parallel-runners` to fix issues automatically
-4. **Test** — Run relevant tests before committing
-5. **Build** — `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
-6. **Tidy** — After upgrading Go dependencies, run `go mod tidy` to clean up `go.mod` and `go.sum`
+- Before exploring domain behavior, read [domain guidance](docs/agents/domain.md).
+- For frontend work, read [frontend/AGENTS.md](frontend/AGENTS.md); before changing UI, also read the [UX contract](docs/agents/frontend-ux.md).
+- Before adding or modifying metadata SQL, pagination, or multi-row transactions anywhere in the repo, read [backend/store/AGENTS.md](backend/store/AGENTS.md). This includes CEL-to-SQL filters and raw reads in tests.
+- For issue operations, read [issue-tracker.md](docs/agents/issue-tracker.md). Linear is the tracker; agent-created issues go to team `BOT`. For triage, also read [triage-labels.md](docs/agents/triage-labels.md).
+- Before creating a PR, complete [docs/pre-pr-checklist.md](docs/pre-pr-checklist.md).
+- `AGENTS.md` files are the instruction source of truth; `CLAUDE.md` files import them.
-### Frontend Code Changes
+## Metadata and API conventions
-1. **Fix** — Run `pnpm --dir frontend fix` to auto-fix Biome issues (format, lint, organize imports)
-2. **Check** — Run `pnpm --dir frontend check` to validate without modifying files (for CI)
-3. **Type check** — Run `pnpm --dir frontend type-check`
-4. **Test** — Run `pnpm --dir frontend test`
+- The metadata schema is `backend/migrator/migration/LATEST.sql`; migrations live in `backend/migrator/migration/<major.minor>/`.
+- New migrations require updating `TestLatestVersion` in `backend/migrator/migrator_test.go`; DDL changes also update `LATEST.sql`.
+- Metadata JSONB uses `protojson.Marshal`: keys are camelCase (`taskRun`), not proto snake_case (`task_run`).
+- Follow Google language style guides and AIPs for API/proto design. AIPs take precedence over the proto guide. Enum values use `HELLO`, not `TYPE_HELLO`.
+- Use American English. Avoid collection names ending in `List`.
-### Proto Changes
+## Test placement
-1. **Format** — Run `buf format -w proto`
-2. **Lint** — Run `buf lint proto`
-3. **Generate** — Run `cd proto && buf generate`
+Test API and workflow behavior against PostgreSQL. Engine dialect and DDL fidelity tests belong in omni.
-## Build/Test Commands
+- Test logic in its owning package. Use `backend/api/v1` for service behavior and `backend/store` for metadata queries, collision isolation, and transaction contention.
+- A backend test boots a Bytebase server only when it needs a background runner, real rollout, or audit trail; these tests live in `backend/tests`. Browser E2E tests use the separate frontend harness.
+- Packages needing metadata PostgreSQL use `testcontainer.Main` and `testcontainer.NewMetadataDB`. Target-engine tests use `testcontainer.SharedPgContainer` or its siblings, with `NewPgDatabase` for a database per test. Use these shared fixtures instead of package-owned or per-test containers.
+- Prefer pure functions for handler decisions and conversions. When state reads are necessary, define a narrow interface beside the handler and fake it, as `backend/api/mcp` does with `serverStore`; avoid an interface over the entire store. Every fake requires a contract test against the real store too.
+- New or modified composite-key methods require collision coverage. Prove colliding keys exist, assert the intended effect in the target scope, and assert the other scope is unchanged. Use the lowest test layer that exercises the behavior. Existing API collision tests remain regression coverage; fixture details are in the pre-PR checklist.
-### Backend
+## Verification
-```bash
-# Build
-go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go
-
-# Start backend
-PG_URL=postgresql://bbdev@localhost/bbdev go run ./backend/bin/server/main.go --port 8080 --data . --debug
-
-# Run single test
-go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^TestFunctionName$
-
-# Run multiple tests
-go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^(TestFunctionName|TestFunctionNameTwo)$
-
-# Lint
-golangci-lint run --allow-parallel-runners
-```
-
-### Frontend
-
-```bash
-# Install dependencies
-pnpm --dir frontend i
-
-# Dev server
-pnpm --dir frontend dev
-
-# Fix (Biome: format, lint, organize imports)
-pnpm --dir frontend fix
-
-# Check (validate without modifying, for CI)
-pnpm --dir frontend check
+During iteration, run focused checks for the changed behavior. Before handoff, run the applicable final gates below. Correct failures before rerunning; repeat when fixes expose further issues, rather than rerunning unchanged failures. Report any unavailable prerequisite or remaining failure explicitly. Inspect formatter/autofix output for unrelated edits.
-# Type check
-pnpm --dir frontend type-check
+### Go changes
-# Test
-pnpm --dir frontend test
-```
+1. Run `gofmt -w` on modified Go files.
+2. Run `golangci-lint run --fix --allow-parallel-runners`, then `golangci-lint run --allow-parallel-runners` until clean after corrections. Run at repo root without filenames so package context is available.
+3. Run tests for changed packages and affected behavior, including required collision or contention coverage.
+4. Build: `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`.
+5. After dependency changes, run `go mod tidy` and recheck affected code.
-### Proto
+For focused tests, quote the regex:
```bash
-# Format
-buf format -w proto
-
-# Lint
-buf lint proto
-
-# Generate
-cd proto && buf generate
+go test -v -count=1 ./backend/store/ -run '^(TestFunctionName|TestFunctionNameTwo)$'
```
-### Database
-
-```bash
-# Connect to Postgres
-psql -U bbdev bbdev
-```
-
-## Code Style
-
-### General
-
-- Follow Google style guides for all languages
- - [Go](https://google.github.io/styleguide/go/)
- - [TypeScript](https://google.github.io/styleguide/tsguide.html) and [JavaScript](https://google.github.io/styleguide/jsguide.html)
-- Write clean, minimal code; fewer lines is better
-- Prioritize simplicity for effective and maintainable software
-- Only include comments that are essential to understanding functionality or convey non-obvious information
-- Keep comments short while preserving necessary information
-
-### Go
-
-- Use standard Go error handling with detailed error messages
-- Always use `defer` for resource cleanup like `rows.Close()` (sqlclosecheck)
-- Avoid using `defer` inside loops (revive) — use IIFE or scope properly
-
-### API and Proto
-
-- Follow [AIPs](https://google.aip.dev/general)
-- When AIP and the proto guide conflict, AIP takes precedence
-- Use `HELLO` for enum names, not `TYPE_HELLO`
-
-### Frontend
-
-- Follow TypeScript style with strict type checking
-- **i18n**: All user-facing display text in the UI must be defined and maintained in locale files under `./frontend/src/locales/` using the i18n internationalization system. Do not hardcode any display strings directly in the source code
- - **No Empty Objects**: Do not add empty JSON objects (e.g., `"key": {}`) to locale files. Remove any empty objects you encounter
-- **Button Spacing**: Use `gap-x-2` for ALL button groups (modals, drawers, toolbars, inline actions). Never use `space-x` for buttons. See `./frontend/.claude/BUTTON_SPACING_STANDARDIZATION.md` for full guidelines
-
-### React
-
-The product frontend is built in React. **All product UI code is React** — use the stack and component patterns below. The only Vue runtime is the isolated `pev2` adapter under `frontend/src/apps/explain-visualizer/`.
-
-The canonical design foundations and workflow recipes are in
-[`docs/agents/frontend-ux.md`](docs/agents/frontend-ux.md). New and directly
-modified UI must follow it; unrelated legacy UI is governed by its incremental
-baseline and must not gain new violations.
-
-The canonical frontend ownership map is in `./frontend/AGENTS.md`. In summary:
-
-- `frontend/src/app/` owns bootstrap, layouts, and router infrastructure.
-- `frontend/src/routes/` owns route modules and route-local code.
-- `frontend/src/modules/` owns reusable application subsystems.
-- `frontend/src/components/ui/` owns shared UI primitives; `frontend/src/components/` contains other genuinely shared product components.
-- `frontend/src/stores/`, `frontend/src/api/`, `frontend/src/hooks/`, and `frontend/src/lib/` contain cross-route infrastructure. Existing `types/` and `utils/` are compatibility surfaces, not default homes for owner-specific code.
-- Do not introduce a generic feature bucket or recreate the migration-era framework namespace.
-- Historical frontend migration plans under `docs/superpowers/` preserve the paths that existed when they were written; use `frontend/AGENTS.md`, not those plans, for current placement decisions.
-
-**Stack**: React + [Base UI](https://base-ui.com/) (`@base-ui/react`) + Tailwind CSS v4 + shadcn-style component patterns
-
-**Component patterns**:
-- Build UI components in the shadcn style — `class-variance-authority` (cva) for variant props, `clsx`/`tailwind-merge` for class merging
-- Wrap Base UI primitives (Button, Tabs, Input, etc.) with styled variants in `./frontend/src/components/ui/`
-- Use `useTranslation()` from `react-i18next` for i18n
-- Use CSS custom properties (`--color-accent`, `--color-error`, `--color-control-border`, etc.) for theme tokens, defined in `./frontend/src/assets/css/tailwind.css`
-
-**Shared UI primitives**:
-- For React UI code, prefer shared components from `./frontend/src/components/ui/` over native HTML controls or ad hoc styled elements
-- Before adding or modifying an interactive UI element, first check whether a matching component already exists in `./frontend/src/components/ui/`
-- Use shared UI components for common controls such as buttons, inputs, selects, dialogs, dropdowns, tooltips, tabs, checkboxes, radios, switches, tables, and form controls when available
-- Do not hand-roll native controls with Tailwind classes when a shared component exists
-- Native HTML controls are allowed only when the shared component does not support the required browser behavior, accessibility behavior, or integration pattern
-- When touching existing React UI, opportunistically replace nearby native or ad hoc controls with shared UI components if behavior remains equivalent and the scope stays reasonable
-
-**Tailwind CSS v4**:
-- CSS-first config in `./frontend/src/assets/css/tailwind.css` — no JS config file
-- Custom utilities use `@utility`, design tokens use `@theme`
-- Default border color is `currentcolor` (compat shim in `tailwind.css` preserves v3 behavior)
-
-**State & build**:
-- React app state lives under `./frontend/src/stores/` — the core slices are in `stores/app/`, consumed via the `useAppStore` hook. Routing helpers live in `./frontend/src/app/router/`
-- React `.tsx` is compiled by esbuild (`react-tsx-transform` Vite plugin) and type-checked with `tsc --build` via `pnpm --dir frontend type-check`
-
-### Imports
-
-- Use organized imports (sorted by the import path)
-
-### Formatting
-
-- Use linting/formatting tools before committing
-
-### Error Handling
-
-- Be explicit but concise about error cases
-
-## Naming
-
-- Use American English
-- Avoid plurals like "xxxList" for simplicity and to prevent singular/plural ambiguity stemming from poor design
-
-## Pull Request Guidelines
-
-**Before running `gh pr create`, walk through [`docs/pre-pr-checklist.md`](docs/pre-pr-checklist.md).** It covers the breaking-change review, composite-PK query safety, and lint/test gates — the checks that lint and CI can't catch on their own.
+### Frontend changes
-- **Code Review** — Follow [Google's Code Review Guideline](https://google.github.io/eng-practices/)
-- **Author Responsibility** — Authors are responsible for driving discussions, resolving comments, and promptly merging pull requests
-- **Description** — Clearly describe what the PR changes and why
-- **Testing** — Include information about how the changes were tested
+Run `pnpm --dir frontend fix`, `pnpm --dir frontend check`, `pnpm --dir frontend type-check`, and `pnpm --dir frontend test`.
-## Common Go Lint Rules
+For browser verification, read [frontend/tests/e2e/README.md](frontend/tests/e2e/README.md); before writing tests, read its [AGENTS.md](frontend/tests/e2e/AGENTS.md).
-Always follow these guidelines to avoid common linting errors:
+### Proto changes
-- **Unused Parameters** — Prefix unused parameters with underscore (e.g., `func foo(_ *Bar)`)
-- **Modern Go Conventions** — Use `any` instead of `interface{}` (since Go 1.18)
-- **Confusing Naming** — Avoid similar names that differ only by capitalization
-- **Identical Branches** — Don't use if-else branches that contain identical code
-- **Unused Functions** — Mark unused functions with `// nolint:unused` comment if needed for future use
-- **Function Receivers** — Don't create unnecessary function receivers; use regular functions if receiver is unused
-- **Proper Import Ordering** — Maintain correct grouping and ordering of imports
-- **Consistency** — Keep function signatures, naming, and patterns consistent with existing code
-- **Export Rules** — Only export (capitalize) functions and types that need to be used outside the package
-- **Linting Command** — Always run `golangci-lint run --allow-parallel-runners` without appending filenames to avoid "function not defined" errors (functions are defined in other files within the package)
+Run `buf format -w proto`, `buf lint proto`, and `(cd proto && buf generate)`. Verify generated Go/frontend changes with their corresponding gates.
-## Miscellaneous
+### Documentation changes
-- The database JSONB columns store JSON marshalled by `protojson.Marshal` in Go code. `protojson.Marshal` produces camelCased keys rather than the snake_case keys defined in the proto files. e.g. `task_run` becomes `taskRun`
-- When modifying multiple files, run file modification tasks in parallel whenever possible, instead of processing them sequentially
+Check local links, referenced paths/symbols, and shell examples. Code build/test gates do not apply to documentation-only changes.
diff --git a/backend/store/AGENTS.md b/backend/store/AGENTS.md
index bbab7bce34..3f8cc1efa9 100644
--- a/backend/store/AGENTS.md
+++ b/backend/store/AGENTS.md
@@ -25,12 +25,11 @@ When writing or modifying queries on these tables:
a full declared non-partial UNIQUE key that contains the same scope columns;
verify alternate keys in `LATEST.sql`. Never filter by `id` or another locally
unique identifier alone
-- When adding a new store method touching a composite-PK table, add a
- corresponding `TestCollision_*` test in `backend/tests/`, built on
- `setupCollidingProjects` + `fixture.completeRolloutB` for setup and
- `snapshotProject` / `assertProjectUnchanged` for assertions — all going through
- the public gRPC API, no store access. Run with:
- `go test -v -count=1 ./backend/tests/ -run "^(TestClaim|TestCollision)" -timeout 5m`
+- New or modified composite-key methods require collision tests under the root
+ [test-placement policy](../../AGENTS.md#test-placement). For store-level tests,
+ create equal local keys in distinct scopes and verify both the intended effect
+ and isolation. For tests requiring runners, rollouts, or the audit trail, use
+ the API collision fixture described in the pre-PR checklist.
- Which tables the shared snapshot already covers, and the two (`plan_webhook_delivery`,
`sheet_blob_ref`) that need table-specific handling because they have no public
read API, are listed in [`docs/pre-pr-checklist.md`](../../docs/pre-pr-checklist.md)
diff --git a/backend/tests/AGENTS.md b/backend/tests/AGENTS.md
new file mode 100644
index 0000000000..5f7cc45d03
--- /dev/null
+++ b/backend/tests/AGENTS.md
@@ -0,0 +1,6 @@
+# Backend workflow tests
+
+Follow the root [test-placement policy](../../AGENTS.md#test-placement).
+Before writing metadata SQL, read [store instructions](../store/AGENTS.md).
+For collision fixture usage, read [README.md](README.md) and
+[the pre-PR collision checklist](../../docs/pre-pr-checklist.md#step-3c-verify-collision-test-coverage).
diff --git a/backend/tests/CLAUDE.md b/backend/tests/CLAUDE.md
index cbf28fbe9e..43c994c2d3 100644
--- a/backend/tests/CLAUDE.md
+++ b/backend/tests/CLAUDE.md
@@ -1 +1 @@
-@../store/AGENTS.md
diff --git a/docs/agents/exploratory-qa.md b/docs/agents/exploratory-qa.md
new file mode 100644
index 0000000000..810ece59fd
--- /dev/null
+++ b/docs/agents/exploratory-qa.md
@@ -0,0 +1,219 @@
+# Exploratory and Release QA
+
+Doctrine for pre-release regression QA. Distilled from gaps between what methodical
+walks find and what humans file. Use this guide for an explicitly scoped exploratory or release QA pass. Apply
+coverage requirements to the agreed area; routine test edits follow
+[the E2E authoring guide](../../frontend/tests/e2e/AGENTS.md).
+
+
+---
+
+### Who we are
+
+> We are QA engineers in pre-release regression. Our defining trait is **curiosity
+> tempered by logic**. We touch every button to see what happens; we also know what
+> *should* happen and why — by deducing from sibling screens, from commit history,
+> from the user's mental model. We trust what users see over what the codebase
+> asserts. We are skeptical: a button that renders is not a button that works.
+> We are persistent: a bug noticed once but not yet reproduced is not yet found.
+> Everything below follows from this.
+
+---
+
+## Part I — Principles for finding bugs
+
+Ranked from most to least important. Grouped by tier for skimming, but the order
+within and across tiers reflects impact.
+
+### Tier 1 — Mindset (foundational)
+
+These are not techniques. They are who you have to *be* before any technique helps.
+
+#### 1. Be curious — touch every clickable thing
+
+Open every dropdown, click every checkbox, type into every input, right-click
+everywhere. Explore paths the docs don't list. Curiosity is the source of finding;
+without it, no method produces anything. A page is "checked" only after you have
+probed every interactive element on it.
+
+**In practice:** enumerate every `button`, `input`, `checkbox`, `dropdown`,
+`menuitem`, and right-click target on the screen before declaring it covered.
+
+#### 2. Be logical — reason about expected behavior
+
+Curiosity without logic is noise. Before flagging anything, ask: *what should this
+screen do, and why?* Deduce expected behavior from related views, from how comparable
+products work, from the underlying data model, from commit history. Cross-reference:
+if X holds on screen A, screen B's behavior must follow. *New* is not *broken*;
+*weird* is not always *bug* — but verify with reasoning, not assumption.
+
+**In practice:** when a behavior looks off, write down "I expected X because Y"
+before declaring it a defect. If your *why* is "it just feels wrong," you haven't
+reasoned yet.
+
+#### 3. Be the user — narrate the experience
+
+Stop describing what the codebase does. Describe what a person sees and feels.
+"I clicked Run and waited five seconds for nothing to happen" surfaces bugs that
+"Run button has class X" never will. Users notice in 30 seconds what exhaustive
+automation misses in an hour.
+
+**In practice:** after each interaction, ask "what would a customer say happened
+just now?" If the answer is interesting, file it.
+
+### Tier 2 — Coverage (what to test)
+
+Once you have the right mindset, these principles direct *where* to look.
+
+#### 4. Stress what looks static
+
+Static screens pass. Bugs hide under load. For every input field: try empty,
+near-empty, full-to-the-limit, beyond-the-limit, unicode, emoji, very long strings,
+special characters. For every button: click rapidly, click many times in succession,
+click during loading, click while another action is in flight. For every list or
+table: empty state, one item, hundreds, thousands. Bugs that are invisible at rest
+become loud under pressure.
+
+**In practice:** every CUJ has a "stressed" variant. Add it deliberately, don't
+wait to discover it.
+
+**Enumerate, don't just stress.** Before declaring an area covered, list every
+clickable leaf (button, icon, toggle, menuitem) in that area and click each one
+once. Coverage holes — like a Schema-diagram tab nobody opened, or a Copy button
+nobody clicked in admin mode — come from following CUJs without enumeration.
+
+#### 5. Test sequences, not just isolated actions
+
+Bugs cluster at the boundaries between actions, not inside them. Build interaction
+graphs: *switch context → return → re-engage*. *Open dialog → cancel → reopen*.
+*Trigger A → trigger B in flight → trigger A again*. The third action in a chain
+is where state corruption lives. A test of "X works" and "Y works" does not prove
+that "X then Y" works.
+
+**In practice:** for every pair of major actions, walk A→B and B→A. For every
+modal, sidebar, or tab, test the re-engagement path after closing.
+
+**Side-effects across unrelated views.** Open view A → trigger an unrelated action
+in B → return to A and assert A is unchanged. Each half is "correct" in isolation —
+the bug only exists when both views are alive at the same time. Example: opening
+the History sidebar then running a query in the editor silently nuked the history
+list. Running and history-search worked fine alone.
+
+#### 6. Vary the data, not just the queries
+
+Renderers break on shapes other than the happy case. The same surface against
+different data — NULLs, wide rows, deeply-nested objects, binary, errors, large
+strings, special characters, multi-statement, empty result — exercises a different
+code path each time. A single happy-path test is a smoke test, not a stress test.
+
+**In practice:** keep a "data variety" pass per result-rendering surface. Each
+variant is its own test.
+
+#### 7. Test from real user states, not just admin
+
+Admin bypasses most gates. The interesting bugs live at permission boundaries —
+visible only to scoped users. Maintain a fixture user roster (no-membership, viewer,
+developer, admin) and run the same tour as each. The bugs that ship are the ones
+admins can't see.
+
+**In practice:** every CUJ touching permissions runs at least twice — admin and
+non-admin. Helpers for grant/revoke make this cheap.
+
+#### 8. Let the diff drive the work
+
+The bug surface is what changed. `git log` since the previous release ranks risk.
+Weight exploration time toward high-delta surfaces; do not spend cycles on code
+that has been stable for a year.
+
+**In practice:** read the diff before designing CUJs. Score each CUJ by lines-changed
+in its surface area. Walk highest-risk first while you're still fresh.
+
+### Tier 3 — Observation (how to see)
+
+Curiosity and coverage put you in front of the bug. These principles ensure you
+*see* it.
+
+#### 9. Look at the screen, not just the DOM
+
+JS evals tell you what's *there*. Screenshots tell you what a user *sees*. They
+disagree more often than you'd expect: contrast, overlap, truncation, two-line
+expansion of single-line widgets, disabled-looking-but-clickable controls. Most
+visual bugs are invisible to DOM-only inspection.
+
+**In practice:** after every meaningful state change, capture a screenshot and
+read it like an image, not a log. Describe what you see in plain language before
+moving on.
+
+**And read every word.** Form labels, dropdown options, helper text, version
+banners, confirm-dialog titles — read them one by one. Duplicate wording (a field
+labeled "Expiration" with a "4 hours" dropdown that *also* says "hours" inline),
+backwards version banners ("New version 3.17.1 available" while you're on 3.18),
+and placebo confirm dialogs ("Delete this saved query?" with no body
+text) all hide in plain text we breeze past.
+
+#### 10. Record video for transient bugs
+
+Some bugs only exist in motion: a button that blinks on hover, a modal that flashes
+and disappears, an overlay that flickers during a race condition, an animation that
+stutters. Screenshots miss these entirely. Run a screen recorder for every
+exploratory session; review at half speed when something feels off.
+
+**In practice:** keep a video capture running continuously. Mark timestamps when
+something feels off; review and trim before filing.
+
+#### 11. Profile network per action
+
+Every user click has a request budget. Anything fanning out to `List*` endpoints on
+a simple switch, or repeating identical requests, or firing more than a handful of
+calls on a navigation — is suspect. Performance regressions hide from functional
+tests.
+
+**In practice:** capture `performance.getEntriesByType('resource')` before and
+after each action; diff the count and the URLs.
+
+#### 12. Read commit messages — they name risk surfaces
+
+Each "refactor: migrate X" is a hypothesis to test. Each "fix: cannot Y" is a
+region of recent fragility. Commit history is the engineering team's confession
+about where the bugs were; it tells you where the next ones probably are. Use it.
+
+**In practice:** before exploring an area, `git log --oneline <prev-release>..HEAD -- <area>`.
+Treat each commit as a target.
+
+### Tier 4 — Discipline (how to verify honestly)
+
+Once you think you have a finding, these principles prevent self-deception.
+
+#### 13. Distinguish "wired up" from "works"
+
+Three layers before ✓: render (DOM exists), interactive (click registers a state
+change), end-to-end (action produces a user-visible outcome). Do not conflate
+them. Many automation tools fire events that the framework's handlers do not
+register — the click looks made but nothing happens downstream.
+
+**In practice:** for every control, confirm a state change after the click —
+not just that the click was issued.
+
+#### 14. When DOM and screen disagree, trust the screen
+
+The user sees the screen. If your selector reports one thing and the rendered
+output shows another, your selector is wrong — not the product. Stop debugging
+the product; debug your observation.
+
+**In practice:** when JS state surprises you, screenshot first, then debug the
+selector. The image is ground truth.
+
+#### 15. Compare across surfaces — same widget, every page
+
+The same button, the same icon, the same toggle should render the same way on
+every page that uses it. The Issues-page Save button should look like the
+SQL-Editor Save button should look like the Settings-page Save button — same
+size, same color, same hover state, same affordance. Single-surface walks miss
+this entire bug class because they only ever see one instance of each widget.
+
+Visual consistency is *the* tell of a well-maintained design system; lapses are
+*the* tell of a recent migration that didn't quite finish.
+
+**In practice:** keep a list of widgets that should be identical (Save, Cancel,
+the avatar dropdown, status badges, etc.) and screenshot each one on at least
+three different surfaces. Diff the images visually; mismatches are bugs.
diff --git a/docs/agents/frontend-ux.md b/docs/agents/frontend-ux.md
index 05db7def5e..26d0554c95 100644
--- a/docs/agents/frontend-ux.md
+++ b/docs/agents/frontend-ux.md
@@ -161,6 +161,10 @@ Use semantic utilities backed by CSS custom properties:
Do not choose a dialog merely because the implementation is smaller. Choose the
surface from task complexity, user context, and expected navigation.
+### Dialog Defaults
+
+- **Dialog sizing contract** — `DialogContent` and `AlertDialogContent` are padded (`p-6`) by default; don't add inner padding wrappers, and override with `p-*` on the content element when needed. `DialogContent` defaults to a wide content size (`max-w-[max(48rem,55vw)]`); pass `max-w-*` (and `w-*` if needed) for smaller dialogs. Keep component defaults free of responsive variants like `2xl:max-w-*` — tailwind-merge can't replace them with a caller's unprefixed utility, so they silently win on wide screens.
+
## Form Workflows
### Shared Form Anatomy
@@ -250,10 +254,50 @@ The required structure is:
- Create is enabled when required fields are valid. Update additionally
requires dirty state.
- An always-mounted edit sheet MUST use the stable-entity ref, keyed inner form,
- and full-entity loading pattern in `frontend/AGENTS.md`.
+ and full-entity loading pattern below.
- Nested selects, menus, and popovers MUST use their portal option or another
shared overlay primitive; do not raise them with an ad hoc z-index.
+#### Edit Sheet Lifecycle
+
+- **Edit sheets must populate from props reliably** — when a Sheet is always-mounted via `<Sheet open={open}>` (the standard pattern), `useState` initializers only run on first mount, which means switching the entity being edited (e.g. clicking Edit on a different row) won't repopulate fields. Use the **outer wrapper + inner form + stable-entity ref + key** pattern. The ref freezes the last-open entity so the inner form stays visually stable through the Sheet's close animation (which is ~200ms), while the `key` forces a fresh mount when a new entity is opened. Example from `CreateUserSheet`:
+ ```tsx
+ function CreateUserSheet(props: Props) {
+ const { open, user, onClose } = props;
+ // Freeze the entity while open=false so the inner form stays visually
+ // stable during the Sheet's close animation. Base UI's Dialog.Portal
+ // unmounts after the animation, at which point the form unmounts with it.
+ const openEntityRef = useRef(user);
+ if (open) {
+ openEntityRef.current = user;
+ }
+ const stableUser = openEntityRef.current;
+ return (
+ <Sheet open={open} onOpenChange={(next) => !next && onClose()}>
+ <SheetContent width="standard">
+ <UserForm
+ key={stableUser?.name ?? "new"}
+ user={stableUser}
+ onClose={props.onClose}
+ onCreated={props.onCreated}
+ onUpdated={props.onUpdated}
+ />
+ </SheetContent>
+ </Sheet>
+ );
+ }
+ function UserForm({ user, ... }: InnerProps) {
+ // useState initializers read directly from `user` — always fresh
+ // because the inner component mounts fresh on every open.
+ const [title, setTitle] = useState(user?.title ?? "");
+ // ...
+ }
+ ```
+ Do **not** guard the inner form with `{open && ...}` — that would unmount it at the start of the close animation, leaving a blank sheet sliding off-screen for ~200ms. Base UI's Dialog.Portal already handles the mount/unmount lifecycle around the animation.
+- **Edit sheets must disable Update until dirty** — capture initial values at mount (inside the inner form component, so they reflect the just-mounted entity prop) and compute `isDirty` via `useMemo` comparing current state to captured initials. Gate the Update button on `isFormValid && isDirty`. Create mode is always "dirty" so Create is enabled as soon as required fields are valid.
+- **Fetch the full entity before opening an edit sheet** — list APIs often return partial objects. Synchronous cache lookups like `store.getX(id)` can return a stub with only name/email/title fields, leaving nested fields (e.g. `workloadIdentityConfig.subjectPattern`) undefined. Use the async `getOrFetchX` form in row-click handlers so the Sheet receives a fully-hydrated entity — otherwise parsed/derived fields will be empty on first edit.
+
+
#### Sheet Widths
New ordinary product flows MUST use a standard tier:
diff --git a/docs/pre-pr-checklist.md b/docs/pre-pr-checklist.md
index 2f8ddd8c72..6e25d60f71 100644
--- a/docs/pre-pr-checklist.md
+++ b/docs/pre-pr-checklist.md
@@ -5,9 +5,13 @@ skip condition — check it first to avoid unnecessary work.
## 1. Determine What Changed
+Fetch main with an explicit destination so `origin/main` exists even in checkouts
+without remote-tracking refs. Continue with the diff only after the fetch succeeds.
+
```bash
-git diff main...HEAD --stat
-git diff main...HEAD
+git fetch origin +refs/heads/main:refs/remotes/origin/main
+git diff origin/main...HEAD --stat
+git diff origin/main...HEAD
```
Use the diff output to decide which sections below apply.
@@ -100,8 +104,13 @@ This is the exact bug pattern that caused BYT-9259. Fix the query first.
If the diff adds or modifies a store method that touches a composite-PK table:
-1. Check if a corresponding `TestCollision*` or `TestClaim*` test exists in `backend/tests/`
-2. If not, add one using `setupCollidingProjects` and `assertProjectUnchanged` from
+1. Check that existing coverage exercises the changed behavior. Follow the root
+ [test-placement policy](../AGENTS.md#test-placement): query isolation belongs
+ in `backend/store`; runner, rollout, and audit behavior belongs in `backend/tests`.
+ Store tests must create colliding keys in distinct scopes, assert the intended
+ target effect, and prove the other scope is unchanged. Add or extend coverage
+ when the existing test does not exercise the changed method or path.
+2. For server-backed collision tests, use `setupCollidingProjects` and `assertProjectUnchanged` from
`backend/tests/collision_helper_test.go`. The shared snapshot covers `plan`,
`issue`, `task`, `task_run`, `plan_check_run`, `task_run_log`, `db_group`,
`release`, and `sheet_blob_ref` (public APIs where one exists). `plan_webhook_delivery`
@@ -146,7 +155,12 @@ modified store method on a composite-PK table.** Write the tests before continui
Only run after steps 3b and 3c are resolved.
+Run the store suite and the existing API collision suite. Run the full store
+suite because isolation tests also use behavior-specific names rather than a
+shared `TestCollision` prefix.
+
```bash
+go test -v -count=1 ./backend/store/ -timeout 5m
go test -v -count=1 ./backend/tests/ -run "^(TestClaim|TestCollision)" -timeout 5m
```
@@ -161,7 +175,7 @@ If you removed `Server.StoreForTest()`, renamed `assertFooCollide`, etc.,
grep for stale references that would now lie to the reader:
```bash
-git diff main...HEAD --name-only -- '*.go' | xargs -I{} grep -l 'OldSymbolName' AGENTS.md docs/ backend/ 2>/dev/null
+rg -n --hidden -F 'OldSymbolName' AGENTS.md CLAUDE.md docs backend frontend .claude --glob '*.md'
```
For each match, either delete the prose or update it to reference the
@@ -230,34 +244,17 @@ description.
**Skip if:** no code changes (docs-only PR).
-Run the checks relevant to the files you changed:
-
-**Go changes:**
-```bash
-gofmt -w <changed .go files>
-golangci-lint run --allow-parallel-runners
-```
-Run golangci-lint repeatedly until zero issues (the linter has a max-issues limit).
-
-**Frontend changes:**
-```bash
-pnpm --dir frontend check
-pnpm --dir frontend type-check
-```
-
-**Proto changes:**
-```bash
-buf lint proto
-```
+Complete the applicable [root verification gates](../AGENTS.md#verification)
+for Go, frontend, and proto changes. Use that section as the command source of
+truth.
## 8. Test Gate
**Skip if:** no code changes.
-- Run tests for every changed package
-- For store changes touching composite-PK tables, run the collision tests (section 3d)
-- For Go changes: `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
-- For new migration files: update `TestLatestVersion` in `backend/migrator/migrator_test.go`
+Confirm the root verification gates covered every changed package and affected
+behavior. For composite-key changes, also complete section 3d; for contention
+changes, complete section 5. New migrations require updating `TestLatestVersion`.
## 9. Final Verification
diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md
index 2adbb343ff..1db4d0d090 100644
--- a/frontend/AGENTS.md
+++ b/frontend/AGENTS.md
@@ -7,7 +7,12 @@ This file provides additional guidance to AI coding assistants working under `./
## React
-- All product UI code is React. Write new UI following the stack and component patterns in the root `../AGENTS.md` and the shadcn guidance below. The `pev2` adapter under `src/apps/explain-visualizer/` is the only Vue runtime exception.
+- All product UI code is React. Use React, Base UI, Tailwind CSS v4, and the shadcn-style component patterns below. The `pev2` adapter under `src/apps/explain-visualizer/` is the only Vue runtime exception.
+
+## Localization
+
+- All user-facing UI text belongs in `src/locales/` and is consumed through `useTranslation()` from `react-i18next`.
+- Locale files must not contain empty JSON objects; remove them when encountered.
## UX contract
@@ -61,12 +66,8 @@ React UI components live in `src/components/ui/` and follow shadcn-style pattern
### Rules
- **Use existing UI components first** — check `src/components/ui/` before writing custom markup. Use `Badge` not styled spans, `Alert` not custom callout divs, `Separator` not `<hr>` or `border-t` divs
-- **Use semantic color tokens** — `bg-accent`, `text-control`, `border-control-border`, `bg-error`, `text-warning`, etc. Never use raw color values like `bg-blue-500`, `text-gray-600`, or `bg-red-500`. Semantic tokens are defined as CSS custom properties in `src/assets/css/tailwind.css`
-- **Use `gap-*` not `space-x-*` / `space-y-*`** — always use `flex gap-*` or `grid gap-*` for spacing between children
-- **Use `size-*` for equal dimensions** — `size-4` not `w-4 h-4`
- **Use `truncate` shorthand** — not `overflow-hidden text-ellipsis whitespace-nowrap`
- **Use `cn()` for conditional classes** — import from `@/lib/utils`, don't write manual template literal ternaries
-- **No manual `dark:` overrides** — use semantic tokens that handle theming
- **Overlay layering policy** — React overlays use three semantic families: `overlay`, `agent`, and `critical`.
- Standard app overlays mount into `overlay`.
- The shared primitives in `src/components/ui/` are the `overlay` entry points; they are not for agent-owned or critical surfaces.
@@ -84,48 +85,6 @@ React UI components live in `src/components/ui/` and follow shadcn-style pattern
- Do not hide raw global overlay classes in constants, imported helpers, `cn()` inputs, or interpolated template literals. A value like `fixed inset-0 z-50` is still forbidden even when it is not written directly in `className`.
- When adding or changing React overlays, run `pnpm --dir frontend check` or `node frontend/scripts/check-react-layering.mjs` before handing off. The scanner is intended to catch raw high-z overlays, forbidden body portals, and policy drift in feature code.
- The scanner is a guardrail, not proof of policy compliance. It intentionally avoids full static analysis, so imported, dynamic, shadowed, or complex expressions may be unresolved; passing the check does not permit raw global z-index overlays or body portals.
-- **Dialog vs Sheet** — use `<Sheet>` (right-side drawer, in `src/components/ui/sheet.tsx`) for **creating or editing a resource**. Use `<Dialog>` for **confirmations, single-field prompts, critical interrupts, and read-only result displays**. The dividing line is whether the user is filling out a form with multiple fields — drawers keep the parent list/table visible behind a scrim and scale to multi-section forms, while dialogs are for short blocking interactions. `AlertDialog` is the right pick for destructive confirms that need an explicit acknowledgment.
-- **Dialog sizing contract** — `DialogContent` and `AlertDialogContent` are padded (`p-6`) by default; don't add inner padding wrappers, and override with `p-*` on the content element when needed. `DialogContent` defaults to a wide content size (`max-w-[max(48rem,55vw)]`); pass `max-w-*` (and `w-*` if needed) for smaller dialogs. Keep component defaults free of responsive variants like `2xl:max-w-*` — tailwind-merge can't replace them with a caller's unprefixed utility, so they silently win on wide screens.
-- **Sheet width tiers** — `<SheetContent>` accepts a `width` variant. Pick the tier that matches the form complexity; don't inline ad-hoc widths. Add a new tier to `sheet.tsx` only if a genuinely new size is needed.
- - `narrow` (384px) — single-field pickers, short 2–3 field forms, environment/project selection, read-only display sheets
- - `standard` (704px, default) — 3–6 field forms, permission transfer lists, typical create/edit resources (role, user, group, service account, workload identity, request role)
- - `wide` (832px) — forms with CEL expression builders, nested tables, multi-tab layouts, multi-step wizards (custom approval rule, data export wizard)
-- **Edit sheets must populate from props reliably** — when a Sheet is always-mounted via `<Sheet open={open}>` (the standard pattern), `useState` initializers only run on first mount, which means switching the entity being edited (e.g. clicking Edit on a different row) won't repopulate fields. Use the **outer wrapper + inner form + stable-entity ref + key** pattern. The ref freezes the last-open entity so the inner form stays visually stable through the Sheet's close animation (which is ~200ms), while the `key` forces a fresh mount when a new entity is opened. Example from `CreateUserSheet`:
- ```tsx
- function CreateUserSheet(props: Props) {
- const { open, user, onClose } = props;
- // Freeze the entity while open=false so the inner form stays visually
- // stable during the Sheet's close animation. Base UI's Dialog.Portal
- // unmounts after the animation, at which point the form unmounts with it.
- const openEntityRef = useRef(user);
- if (open) {
- openEntityRef.current = user;
- }
- const stableUser = openEntityRef.current;
- return (
- <Sheet open={open} onOpenChange={(next) => !next && onClose()}>
- <SheetContent width="standard">
- <UserForm
- key={stableUser?.name ?? "new"}
- user={stableUser}
- onClose={props.onClose}
- onCreated={props.onCreated}
- onUpdated={props.onUpdated}
- />
- </SheetContent>
- </Sheet>
- );
- }
- function UserForm({ user, ... }: InnerProps) {
- // useState initializers read directly from `user` — always fresh
- // because the inner component mounts fresh on every open.
- const [title, setTitle] = useState(user?.title ?? "");
- // ...
- }
- ```
- Do **not** guard the inner form with `{open && ...}` — that would unmount it at the start of the close animation, leaving a blank sheet sliding off-screen for ~200ms. Base UI's Dialog.Portal already handles the mount/unmount lifecycle around the animation.
-- **Edit sheets must disable Update until dirty** — capture initial values at mount (inside the inner form component, so they reflect the just-mounted entity prop) and compute `isDirty` via `useMemo` comparing current state to captured initials. Gate the Update button on `isFormValid && isDirty`. Create mode is always "dirty" so Create is enabled as soon as required fields are valid.
-- **Fetch the full entity before opening an edit sheet** — list APIs often return partial objects. Synchronous cache lookups like `store.getX(id)` can return a stub with only name/email/title fields, leaving nested fields (e.g. `workloadIdentityConfig.subjectPattern`) undefined. Use the async `getOrFetchX` form in row-click handlers so the Sheet receives a fully-hydrated entity — otherwise parsed/derived fields will be empty on first edit.
### Component Patterns
diff --git a/frontend/tests/e2e/AGENTS.md b/frontend/tests/e2e/AGENTS.md
index 24c32f4454..74aa244428 100644
--- a/frontend/tests/e2e/AGENTS.md
+++ b/frontend/tests/e2e/AGENTS.md
@@ -22,38 +22,17 @@ execSql(env, dbName, `DROP SCHEMA IF EXISTS my_feature_test CASCADE`);
**Why:** A test that owns its fixtures is deterministic. You know exactly what values exist, what's masked, what's not, and what state is left when the test completes. `masking-exemption.spec.ts:createMaskingTestData` is the canonical example.
-### 2. Share a single browser across all tests in a file
+### 2. Isolate browser state by default
-**Do:** Create one `BrowserContext` and `Page` in the file-level `test.beforeAll`, and reuse them across every test in the file.
+Use Playwright's per-test `{ page }` fixture for new independent tests. Serial
+execution does not isolate cookies, local storage, navigation, or in-memory UI
+state. Tests still own their database and policy setup and cleanup.
-```typescript
-let sharedContext: BrowserContext;
-let page: Page;
-
-test.beforeAll(async ({ browser }) => {
- sharedContext = await browser.newContext({ storageState: ".auth/state.json" });
- page = await sharedContext.newPage();
-});
-
-test.afterAll(async () => {
- await sharedContext?.close();
-});
-
-test("my test", async () => {
- // use the shared `page` — no { page } destructuring
- await page.goto(...);
-});
-```
-
-**Don't:** Use Playwright's default per-test `{ page }` fixture. It opens and closes a browser context for every test, which:
-- Costs real time (especially on CI)
-- Triggers NVirtualList first-render timing bugs
-- Makes tests slower for no isolation benefit (we run `workers: 1` anyway)
-
-**Side effects to clean up manually** (since we lose per-test isolation):
-- Reset viewport in `afterAll` if you changed it mid-suite
-- Clear URL/tab state explicitly if it matters (usually via `gotoWithDb` etc.)
-- Reset policy state via API (`revokeAllExemptions`) in `beforeEach` when tests depend on clean state
+A shared context/page is appropriate for a deliberate multi-step scenario or a
+measured setup bottleneck. Document the reason and reset state between independent
+tests. Existing shared-context suites can remain; preserve their cleanup when
+editing them. Keep a dependent user journey in one test rather than relying on
+another test's leftovers.
### 3. API for setup, browser for verification
@@ -122,10 +101,10 @@ frontend/tests/e2e/
2. **Write page objects** in `<feature>.page.ts` (one class per UI surface). Accept `baseURL` in the constructor so pages can navigate via absolute URLs.
3. **Write spec file** `<feature>.spec.ts`:
- Import `loadTestEnv` from `../framework/env`
- - Declare the shared `page` / `sharedContext` at module level
- - In file-level `test.beforeAll`: `loadTestEnv()`, login, create test data, open the shared browser
- - In `test.afterAll`: close browser, clean up test data via the same code path that created it
-4. **Use the canonical example** — read `frontend/tests/e2e/masking-exemption/masking-exemption.spec.ts` as a reference.
+ - Use the per-test `{ page }` fixture and configured authentication state
+ - Load the test environment and create owned data in setup hooks
+ - Clean up owned data and policy state in teardown hooks
+4. **Use the canonical example** — read `frontend/tests/e2e/masking-exemption/masking-exemption.spec.ts` for API setup and owned fixtures; its shared browser is not the default for new tests.
## Extending the API Client
@@ -152,370 +131,17 @@ Get the correct port from `getInstance(env.instance)` rather than hardcoding the
- **Admin credentials**: hardcoded `[email protected]` / `12345678`. The first user created via `/v1/auth/signup` becomes workspace admin, so e2e signs up this fixture.
- **DBA fixture**: `[email protected]` / `12345678` is created during `globalSetup` and granted `roles/workspaceDBA`. Used as the second approver by plan-detail approval specs. If a spec needs additional users (developer, QA, etc.), provision them the same way in `mode-start-new-bytebase.ts` — don't assume they exist.
----
-
-<!-- Merged from the former PRINCIPLES.md (QA finding/writing doctrine). -->
-
-## QA Principles — Field Manual
-
-Doctrine for pre-release regression QA. Distilled from gaps between what methodical
-walks find and what humans file. Two parts:
-
-- **Part I** — principles for *finding* bugs (during exploration)
-- **Part II** — principles for *writing* tests (once a bug is reproduced)
-
-
----
-
-### Who we are
-
-> We are QA engineers in pre-release regression. Our defining trait is **curiosity
-> tempered by logic**. We touch every button to see what happens; we also know what
-> *should* happen and why — by deducing from sibling screens, from commit history,
-> from the user's mental model. We trust what users see over what the codebase
-> asserts. We are skeptical: a button that renders is not a button that works.
-> We are persistent: a bug noticed once but not yet reproduced is not yet found.
-> Everything below follows from this.
-
----
-
-## Part I — Principles for finding bugs
-
-Ranked from most to least important. Grouped by tier for skimming, but the order
-within and across tiers reflects impact.
-
-### Tier 1 — Mindset (foundational)
-
-These are not techniques. They are who you have to *be* before any technique helps.
-
-#### 1. Be curious — touch every clickable thing
-
-Open every dropdown, click every checkbox, type into every input, right-click
-everywhere. Explore paths the docs don't list. Curiosity is the source of finding;
-without it, no method produces anything. A page is "checked" only after you have
-probed every interactive element on it.
-
-**In practice:** enumerate every `button`, `input`, `checkbox`, `dropdown`,
-`menuitem`, and right-click target on the screen before declaring it covered.
-
-#### 2. Be logical — reason about expected behavior
-
-Curiosity without logic is noise. Before flagging anything, ask: *what should this
-screen do, and why?* Deduce expected behavior from related views, from how comparable
-products work, from the underlying data model, from commit history. Cross-reference:
-if X holds on screen A, screen B's behavior must follow. *New* is not *broken*;
-*weird* is not always *bug* — but verify with reasoning, not assumption.
-
-**In practice:** when a behavior looks off, write down "I expected X because Y"
-before declaring it a defect. If your *why* is "it just feels wrong," you haven't
-reasoned yet.
-
-#### 3. Be the user — narrate the experience
-
-Stop describing what the codebase does. Describe what a person sees and feels.
-"I clicked Run and waited five seconds for nothing to happen" surfaces bugs that
-"Run button has class X" never will. Users notice in 30 seconds what exhaustive
-automation misses in an hour.
-
-**In practice:** after each interaction, ask "what would a customer say happened
-just now?" If the answer is interesting, file it.
-
-### Tier 2 — Coverage (what to test)
-
-Once you have the right mindset, these principles direct *where* to look.
-
-#### 4. Stress what looks static
-
-Static screens pass. Bugs hide under load. For every input field: try empty,
-near-empty, full-to-the-limit, beyond-the-limit, unicode, emoji, very long strings,
-special characters. For every button: click rapidly, click many times in succession,
-click during loading, click while another action is in flight. For every list or
-table: empty state, one item, hundreds, thousands. Bugs that are invisible at rest
-become loud under pressure.
-
-**In practice:** every CUJ has a "stressed" variant. Add it deliberately, don't
-wait to discover it.
-
-**Enumerate, don't just stress.** Before declaring an area covered, list every
-clickable leaf (button, icon, toggle, menuitem) in that area and click each one
-once. Coverage holes — like a Schema-diagram tab nobody opened, or a Copy button
-nobody clicked in admin mode — come from following CUJs without enumeration.
-
-#### 5. Test sequences, not just isolated actions
-
-Bugs cluster at the boundaries between actions, not inside them. Build interaction
-graphs: *switch context → return → re-engage*. *Open dialog → cancel → reopen*.
-*Trigger A → trigger B in flight → trigger A again*. The third action in a chain
-is where state corruption lives. A test of "X works" and "Y works" does not prove
-that "X then Y" works.
-
-**In practice:** for every pair of major actions, walk A→B and B→A. For every
-modal, sidebar, or tab, test the re-engagement path after closing.
-
-**Side-effects across unrelated views.** Open view A → trigger an unrelated action
-in B → return to A and assert A is unchanged. Each half is "correct" in isolation —
-the bug only exists when both views are alive at the same time. Example: opening
-the History sidebar then running a query in the editor silently nuked the history
-list. Running and history-search worked fine alone.
-
-#### 6. Vary the data, not just the queries
-
-Renderers break on shapes other than the happy case. The same surface against
-different data — NULLs, wide rows, deeply-nested objects, binary, errors, large
-strings, special characters, multi-statement, empty result — exercises a different
-code path each time. A single happy-path test is a smoke test, not a stress test.
-
-**In practice:** keep a "data variety" pass per result-rendering surface. Each
-variant is its own test.
-
-#### 7. Test from real user states, not just admin
-
-Admin bypasses most gates. The interesting bugs live at permission boundaries —
-visible only to scoped users. Maintain a fixture user roster (no-membership, viewer,
-developer, admin) and run the same tour as each. The bugs that ship are the ones
-admins can't see.
-
-**In practice:** every CUJ touching permissions runs at least twice — admin and
-non-admin. Helpers for grant/revoke make this cheap.
-
-#### 8. Let the diff drive the work
-
-The bug surface is what changed. `git log` since the previous release ranks risk.
-Weight exploration time toward high-delta surfaces; do not spend cycles on code
-that has been stable for a year.
-
-**In practice:** read the diff before designing CUJs. Score each CUJ by lines-changed
-in its surface area. Walk highest-risk first while you're still fresh.
-
-### Tier 3 — Observation (how to see)
-
-Curiosity and coverage put you in front of the bug. These principles ensure you
-*see* it.
-
-#### 9. Look at the screen, not just the DOM
-
-JS evals tell you what's *there*. Screenshots tell you what a user *sees*. They
-disagree more often than you'd expect: contrast, overlap, truncation, two-line
-expansion of single-line widgets, disabled-looking-but-clickable controls. Most
-visual bugs are invisible to DOM-only inspection.
-
-**In practice:** after every meaningful state change, capture a screenshot and
-read it like an image, not a log. Describe what you see in plain language before
-moving on.
-
-**And read every word.** Form labels, dropdown options, helper text, version
-banners, confirm-dialog titles — read them one by one. Duplicate wording (a field
-labeled "Expiration" with a "4 hours" dropdown that *also* says "hours" inline),
-backwards version banners ("New version 3.17.1 available" while you're on 3.18),
-and placebo confirm dialogs ("Delete this saved query?" with no body
-text) all hide in plain text we breeze past.
-
-#### 10. Record video for transient bugs
-
-Some bugs only exist in motion: a button that blinks on hover, a modal that flashes
-and disappears, an overlay that flickers during a race condition, an animation that
-stutters. Screenshots miss these entirely. Run a screen recorder for every
-exploratory session; review at half speed when something feels off.
-
-**In practice:** keep a video capture running continuously. Mark timestamps when
-something feels off; review and trim before filing.
-
-#### 11. Profile network per action
-
-Every user click has a request budget. Anything fanning out to `List*` endpoints on
-a simple switch, or repeating identical requests, or firing more than a handful of
-calls on a navigation — is suspect. Performance regressions hide from functional
-tests.
-
-**In practice:** capture `performance.getEntriesByType('resource')` before and
-after each action; diff the count and the URLs.
-
-#### 12. Read commit messages — they name risk surfaces
-
-Each "refactor: migrate X" is a hypothesis to test. Each "fix: cannot Y" is a
-region of recent fragility. Commit history is the engineering team's confession
-about where the bugs were; it tells you where the next ones probably are. Use it.
-
-**In practice:** before exploring an area, `git log --oneline <prev-release>..HEAD -- <area>`.
-Treat each commit as a target.
-
-### Tier 4 — Discipline (how to verify honestly)
-
-Once you think you have a finding, these principles prevent self-deception.
-
-#### 13. Distinguish "wired up" from "works"
-
-Three layers before ✓: render (DOM exists), interactive (click registers a state
-change), end-to-end (action produces a user-visible outcome). Do not conflate
-them. Many automation tools fire events that the framework's handlers do not
-register — the click looks made but nothing happens downstream.
-
-**In practice:** for every control, confirm a state change after the click —
-not just that the click was issued.
-
-#### 14. When DOM and screen disagree, trust the screen
-
-The user sees the screen. If your selector reports one thing and the rendered
-output shows another, your selector is wrong — not the product. Stop debugging
-the product; debug your observation.
-
-**In practice:** when JS state surprises you, screenshot first, then debug the
-selector. The image is ground truth.
-
-#### 15. Compare across surfaces — same widget, every page
-
-The same button, the same icon, the same toggle should render the same way on
-every page that uses it. The Issues-page Save button should look like the
-SQL-Editor Save button should look like the Settings-page Save button — same
-size, same color, same hover state, same affordance. Single-surface walks miss
-this entire bug class because they only ever see one instance of each widget.
-
-Visual consistency is *the* tell of a well-maintained design system; lapses are
-*the* tell of a recent migration that didn't quite finish.
-
-**In practice:** keep a list of widgets that should be identical (Save, Cancel,
-the avatar dropdown, status badges, etc.) and screenshot each one on at least
-three different surfaces. Diff the images visually; mismatches are bugs.
-
----
-
-## Part II — Principles for writing tests
-
-Once a bug is reproduced or a CUJ is validated, the next job is locking it in
-durable `.spec.ts` code. These conventions cover both bug-lock tests and CUJ
-tests.
-
-#### A. Assert outcomes, not implementation
-
-Check the user-observable thing. Tests survive refactors only when they verify
-what the user sees, not what the codebase happens to render.
-
-- Bad: `expect(button).toHaveClass('bg-accent')`
-- Good: `await expect(page.getByText('Exit admin mode')).toBeVisible()`
-
-#### B. Bug-lock tests must fail on the buggy build
-
-A passing bug-lock test is a broken test. Each must fail with a message that
-pinpoints the bug. Use `test.fail()` when the bug is known-unfixed. **Never use
-`test.skip()`** — skipping hides regressions instead of catching them.
-
-#### C. Tests own their fixtures, not discover them
-
-Create your own schema, tables, rows in `beforeAll`; drop in `afterAll`. Don't
-discover demo data — discovery-based tests fail when seed data drifts.
-
-#### D. Integration sequences > isolated actions
-
-One spec doing `switch tab → click sidebar → switch project → return → click sidebar`
-catches state-corruption bugs that three isolated specs would miss. Tests should
-read like user stories, not unit tests.
-
-#### E. Visual assertions via screenshot baselines
-
-For visual bugs (icon contrast, overlap, truncation), add
-`await expect(page).toHaveScreenshot('export-dialog.png')` baselines. No JS
-assertion catches "icons too light." Add explicit baselines per visual surface,
-not just on failure.
-
-#### F. Test by role, not just by admin
-
-Build `loginAs('sqlEditorReadUser')` and friends. Same spec, multiple users.
-Permission bugs only surface this way. Use API-based role grant/revoke in
-`beforeAll`/`afterAll` so tests don't lean on seeded IAM.
-
-#### G. Parameterize data-variety in result tests
-
-One spec, many cases: NULL, JSON, binary, wide-row, error, large-string. Each
-a different test case via `test.describe.each`. Closes the gap that single
-happy-path tests leave open.
-
-#### H. Network-budget assertions
-
-For dialogs and switches that shouldn't refetch:
-
-```typescript
-expect(networkLog.count).toBeLessThanOrEqual(N);
-```
-
-Catches performance regressions. Use Playwright's `page.on('request')` per spec.
-
-#### I. One concept per test; name = user behavior
-
-Names become the spec doc. Write them as sentences a PM could read.
-
-- Bad: `'handleClick fires updateCurrentTab'`
-- Good: `'clicking 10000-rows preset updates the displayed export limit'`
-
-#### J. Test boundaries, not just happy paths
-
-Every input gets: empty, max, min, special-chars. Most missed bugs are boundary
-issues. Empty-state, one-item, hundreds, thousands all deserve their own test
-case.
-
-#### K. Test the test before trusting it
-
-Mutate the production code (delete the handler, change the value) and re-run.
-If the test still passes, it isn't actually checking the thing.
-
-#### L. Self-contained state
-
-No test depends on another's leftovers. Every spec sets up and tears down its
-own DB schema, saved queries, IAM bindings. Independence is the only way tests
-survive at scale.
-
-#### M. Assert visual relationships, not absolute thresholds
-
-When a bug is "X looks wrong against Y", phrase the test as a comparison
-between X and Y — not as X must equal some specific value. The fix could pick
-any reasonable shade, size, or position; your test should pass for every
-reasonable choice, not just the one you happened to expect.
-
-- Bad: `expect(maxChannel(block)).toBeLessThan(80)` — pins "dark" to a
- specific RGB threshold; fails if the design system later picks a slightly
- lighter dark, even though the user-visible problem is solved.
-- Good: `expect(maxChannelDelta(block, shell)).toBeLessThan(100)` — asserts
- the block harmonizes with its container. Any reasonable theme passes.
-
-This applies anywhere the bug is contextual: a misaligned button (test
-relative position to its row, not absolute pixels), a row highlight that
-matches the wrong column (test the row container's bg vs the surrounding
-rows, not a literal rgb), a tooltip overlapping its trigger (test
-bounding-rect intersection, not absolute coordinates), an inconsistent
-icon size across surfaces (compare across instances, not against `16px`).
-
-Why this matters: thresholds tied to specific values rot fast — the design
-system revises them and the test fails for a reason unrelated to the bug.
-Relational assertions capture the user's actual judgment ("does this look
-out of place?") and survive any tweak that preserves the relationship. The
-failure message is also more useful: "block (rgb 243/244/246) differs from
-shell (rgb 30/30/30) by 216 channels" tells a future maintainer what was
-wrong; "max channel was 246, expected <80" tells them only that you guessed
-80.
-
----
-
-### Quick reference — mapping principles to bug categories
-
-| Bug class | Principles that catch it |
-|---|---|
-| Visual / layout / contrast | #09 screen · #10 video · E visual baselines · M visual relationships |
-| Permission / role-gated | #07 real user states · F test by role |
-| State corruption / sequence | #05 sequences · D integration sequences |
-| Performance / network | #11 network profiling · H budgets |
-| Render edge cases (data) | #06 data variety · G parameterized data |
-| Stress / load / rapid clicks | #04 stress · J boundary tests |
-| "Wired but broken" | #13 wired vs works · #14 trust screen · K test the test |
-| New regression in migrated code | #08 diff-driven · #12 read commits |
-| Out-of-theme / inconsistent styling | #15 cross-surface compare · M visual relationships |
-| Anything subtle a user notices | #03 be the user · #01 curiosity · #02 logic |
-
----
+## Assertions and regression coverage
-### Closing
+- Assert user-visible outcomes. For a reproduced regression, demonstrate that the test fails on the buggy behavior and passes with the fix; a temporary mutation can establish this when useful.
+- Use `test.fail()` for a known-unfixed regression so an unexpected pass is visible. Explain any skipped coverage.
+- Test permission-sensitive flows as both an authorized and a restricted user.
+- Parameterize relevant data shapes with a loop that declares Playwright `test(...)` cases.
+- For visual bugs, use screenshot baselines or assertions on the relevant visual relationship. Capture request counts when the regression concerns unexpected refetches.
+- Keep sequence-dependent interactions in one user journey; assert its terminal outcome.
-A QA engineer who follows none of these but is genuinely curious will still find
-more bugs than one who follows all of them mechanically. The mindset principles
-in Tier 1 are necessary; the rest are amplifiers. Curiosity tempered by logic,
-applied to the real user's experience — that is the entire craft.
+## Exploratory QA
-The methods are just shape we give to a habit.
+For exploratory or release QA, read [the field manual](../../../docs/agents/exploratory-qa.md).
+Its exhaustive interaction and observation passes apply to that scoped activity,
+not to every E2E test edit.
diff --git a/frontend/tests/e2e/README.md b/frontend/tests/e2e/README.md
index ef9fb425a5..bfcbc05a2d 100644
--- a/frontend/tests/e2e/README.md
+++ b/frontend/tests/e2e/README.md
@@ -94,7 +94,7 @@ into screenshots.
```
frontend/tests/e2e/
├── README.md — this file (human docs)
-├── AGENTS.md — conventions + QA doctrine for AI agents / contributors
+├── AGENTS.md — test-authoring conventions for AI agents / contributors
├── framework/ — shared test infrastructure
│ ├── api-client.ts — Bytebase v1 REST API wrapper
│ ├── env.ts — TestEnv interface, serialization
@@ -120,7 +120,7 @@ frontend/tests/e2e/
1. **`globalSetup`**: Cleans orphaned processes, starts Bytebase + embedded Postgres on a random high port, signs up the admin (`[email protected]` / `12345678`), creates `project-sample`, and calls `PrepareSampleProjectInstance` to provision its instance on `PORT+3`.
2. **Setup project** (runs as a Playwright test before all others): Logs in as the admin, discovers the sample database, adds `hr_prod` on the same instance for multi-database coverage, and saves auth state to `.auth/state.json`.
-3. **Tests run**: Each spec file shares one browser context/page (see [AGENTS.md](./AGENTS.md)). Tests call `loadTestEnv()` to get the API client and env data, create their own test data, and run UI-driven verification.
+3. **Tests run**: New independent tests use isolated browser contexts; existing suites may share a context under the exceptions in [AGENTS.md](./AGENTS.md). Tests call `loadTestEnv()` to get the API client and env data, create their own test data, and run UI-driven verification.
4. **`globalTeardown`**: Kills the server process group, removes temp data dir and PID file.
## Troubleshooting