test: consolidate coverage around public API workflows with Vitest

.codex/environments/environment.toml

@@ -16,17 +16,17 @@ command = "bun run dev"
 [[actions]]
 name = "Preview gallery"
 icon = "run"
-command = "bun run build && bun install --frozen-lockfile && bun browser-tests/server.ts"
+command = "bun run build && bun install --frozen-lockfile && bun dev/server.ts"
 
 [[actions]]
 name = "Check"
 icon = "test"
 command = "bun run check"
 
 [[actions]]
-name = "Browser tests"
+name = "Tests"
 icon = "test"
-command = "bun run build && bun install --frozen-lockfile && bun run test:browser"
+command = "bun run build && bun install --frozen-lockfile && bun run test"
 
 [[actions]]
 name = "Build"

.github/workflows/check.yml

@@ -55,16 +55,14 @@ jobs:
         run: bun run check:links
       - name: Check formatting
         run: bun run format:check
-      - name: Test source
-        run: bun run test
       - name: Verify packed consumer
-        run: bun run test:package
+        run: bun run check:package
       - name: Verify starter integration
-        run: bun run test:starter
+        run: bun run check:starter
       - name: Install browser
         run: bash scripts/install-test-browser.sh
-      - name: Test embedding in Chromium
-        run: bun run test:browser
+      - name: Test
+        run: bun run test
       - name: Verify lockfile is unchanged
         run: git diff --exit-code -- bun.lock
 

.oxlintrc.json

@@ -29,5 +29,33 @@
         }
       }
     ]
-  }
+  },
+  "overrides": [
+    {
+      "files": ["tests/**"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": ["bun:test", "@playwright/test"],
+            "patterns": [
+              {
+                "group": ["./**", "../**", ".", ".."],
+                "message": "Use repository-root @/ imports for test fixtures."
+              },
+              {
+                "group": [
+                  "@/src/**",
+                  "@/dev/**",
+                  "**/dist/**",
+                  "@altertable/data-app/dist/**"
+                ],
+                "message": "Test consumer workflows through @altertable/data-app/<entry>, not private implementation modules."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
 }

CONTRIBUTING.md

@@ -4,6 +4,7 @@ Use the Bun and Node.js versions in `.bun-version` and `.node-version`.
 
 ```fish
 bun install --frozen-lockfile
+bash scripts/install-test-browser.sh
 bun run check
 ```
 
@@ -36,12 +37,21 @@ fallbacks minimal.
 
 ## Verify changes
 
-Tests should tell the package's public usage stories: define an operation,
-authorize and query it, compose a view, or embed an app. Exercise published
-entries so build and export mistakes are observable. Test private logic in
-isolation only when its complexity warrants it, such as cancellation, streaming,
-SQL escaping, or authenticated bridge sessions. Avoid tests that repeat trivial
-helpers, file layout, or every component prop.
+Write high-level public API tests with Vitest in `tests/public-api`. Define an
+operation, authorize and query it, compose a view, or embed an app through
+`@altertable/data-app/<entry>`. Assert consumer-visible results and errors. Supply
+data and failures through public dependency injection; do not import private
+source, fabricate internal state, or assert implementation details. Prefer queries by role and accessible name, or by label for form fields. Scope
+content assertions to the relevant region, status, alert, or dialog; use text
+queries for prose with no meaningful role. Do not invent ARIA roles for tests.
+Group browser workflows by consumer capability in `apps-*.test.ts`; keep tests
+self-contained and setup local until repetition warrants sharing it.
+
+`bun run test` runs the complete suite against the built package. Browser
+workflows launch Chromium through Playwright from Vitest. They use public
+consumer fixtures, an isolated local server, and a fresh browser context per
+test. Build first; run one file with `bun run test tests/public-api/apps-export.test.ts`
+or one workflow with `bun run test -t "workflow name"`.
 
 Update the relevant guide when changing public behavior. In documentation prose,
 write functions as `functionName()` and components as `<ComponentName>`. Keep JSDoc for
@@ -63,10 +73,9 @@ checks. Build before running consumer tests individually.
 | `bun run check:links`          | Validate local files, images, and heading links     |
 | `bun run check:links:external` | Check external URLs (requires network access)       |
 | `bun run format`               | Format source and docs                              |
-| `bun run test`                 | Verify public contracts and complex isolated logic  |
-| `bun run test:package`         | Verify the npm archive as a consumer                |
-| `bun run test:starter`         | Typecheck, lint, and build the starter              |
-| `bun run test:browser`         | Verify browser interactions in Chromium             |
+| `bun run test`                 | Verify high-level public API workflows with Vitest  |
+| `bun run check:package`        | Verify the npm archive as a consumer                |
+| `bun run check:starter`        | Typecheck, lint, and build the starter              |
 | `bun run check:workflows`      | Validate workflows and shell scripts                |
 
 Markdown checks cover all authored `.md` files, including `AGENTS.md` and the
@@ -79,18 +88,15 @@ It skips local development URLs and checks reachability without external heading
 validation. It stays outside required checks because third-party availability and
 rate limits can cause failures unrelated to a change.
 
-For browser changes, run `bash scripts/install-test-browser.sh` once, then
-`bun run test:browser`.
-
 Run `bun run dev` to preview UI examples at `http://127.0.0.1:27418/gallery`
 and a playground at `/playground` (`dev/playground.tsx`, querying the demo
 tables `scripts/dev.ts` seeds). It builds once, then rebuilds `dist` when `src`
 changes; open pages reload on package, fixture, and playground edits. Restart it after changing
-`browser-tests/server.ts`; rerun `bun run build` to refresh declarations. Add `?delay=2000` to a host page URL
+`dev/server.ts`; rerun `bun run build` to refresh declarations. Add `?delay=2000` to a host page URL
 to delay its SQL responses and inspect loading states. It needs Docker: SQL runs
 against a mocked Altertable API
 ([altertable-mock](https://github.com/altertable-ai/altertable-mock), DuckDB)
-started with Testcontainers and stopped on exit. Browser tests keep fixtures.
+started with Testcontainers and stopped on exit. Public API tests use their own deterministic consumer fixtures.
 
 Open the **Widgets** tab (`/gallery?view=widgets`) for one ready example of each
 composable data display inside `<VisualizationWidget>`. The other tabs cover