@zerotal/arch 1.7.0

package/docs/testing/browser.md

@@ -0,0 +1,153 @@
+---
+title: Browser Tests
+description: Drive a real browser against a running Zerotal app with Playwright to test Flow and Inertia UIs end-to-end.
+---
+
+# Browser Tests
+
+Browser tests exercise the parts of your app that only exist in a real browser, by
+driving a live server with Playwright and asserting on what the user sees.
+
+Some behavior only exists in a real browser — [Flow](/docs/flow)'s WebSocket
+bridge and Alpine runtime, [Inertia](/docs/inertia) client navigation, focus and
+keyboard handling. This page covers **[Playwright](https://playwright.dev)** pointed
+at a running server, which is what to use for cross-browser end-to-end coverage.
+
+> **Testing Flow's bridge?** [`FlowBrowser`](/docs/testing/flow-browser) ships in
+> `@zerotal/testing`, needs no extra dependency, and runs inside `bun test` alongside
+> the rest of your suite. It drives a headless page against a real server and can
+> assert on the WebSocket transport itself — whether the socket upgraded, what frames
+> crossed the wire. Reach for Playwright when you need several browsers, or coverage
+> beyond Flow.
+
+> **Note** — Unit and [HTTP tests](/docs/testing/http) run on Bun's test runner. Browser tests
+> run under Playwright's own runner (`*.e2e.ts` / `*.spec.ts`), separately from
+> `bun test`.
+
+## Setup
+
+Install Playwright in your app:
+
+```bash
+# in your project root
+bun add -d @playwright/test
+bunx playwright install --with-deps
+```
+
+Add a `playwright.config.ts` that boots your app with the `webServer` option, so the
+server starts once for the whole run and is torn down after:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+
+const PORT = 3000;
+const BASE_URL = `http://localhost:${PORT}`;
+
+export default defineConfig({
+  testDir: "./e2e",
+  testMatch: "**/*.e2e.ts",
+  timeout: 30_000,
+  use: { baseURL: BASE_URL, trace: "on-first-retry" },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+  ],
+  // Boot the server once for the run (no --hot, to avoid reload flakiness)
+  webServer: {
+    command: "bun run start",
+    url: BASE_URL,
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+Wire up scripts in `package.json`:
+
+```json
+// package.json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  }
+}
+```
+
+## Writing a test
+
+Specs live in `e2e/` and use Playwright's `test`/`expect`. Drive the page through
+roles and assert on what the user sees:
+
+```typescript
+// e2e/navigate.e2e.ts
+import { test, expect } from "@playwright/test";
+
+test.describe("SPA navigation", () => {
+  test("swaps content without a full page reload", async ({ page }) => {
+    await page.goto("/pulse/counter");
+    // A full reload would clear this marker; an SPA swap keeps it.
+    await page.evaluate(() => ((window as any).__spa = true));
+
+    await page.getByRole("link", { name: "Components" }).click();
+    await expect(page).toHaveURL(/\/pulse\/components/);
+    await expect(page.getByRole("heading", { name: "Native Components" })).toBeVisible();
+
+    const kept = await page.evaluate(() => (window as any).__spa);
+    expect(kept).toBe(true); // no full reload happened
+  });
+});
+```
+
+```bash
+# in your project root
+bun run test:e2e
+```
+
+## Waiting for the client to boot
+
+Flow pages finish wiring once Alpine has walked the DOM and fired
+`alpine:initialized`. A fast click can land before that and silently no-op (a flaky,
+browser-dependent failure). Wait for readiness before interacting:
+
+```typescript
+// e2e/support/gotoReady.ts
+import type { Page } from "@playwright/test";
+
+export async function gotoReady(page: Page, url: string): Promise<void> {
+  await page.addInitScript(() => {
+    (window as any).__alpineReady = false;
+    document.addEventListener("alpine:initialized", () => ((window as any).__alpineReady = true));
+  });
+  await page.goto(url);
+  await page.waitForFunction(() => (window as any).__alpineReady === true, null, {
+    timeout: 10_000,
+  });
+}
+```
+
+Then `await gotoReady(page, "/pulse/counter")` instead of `page.goto(...)` for
+interactive Flow pages.
+
+> **Warning** — Clicking before `alpine:initialized` fires is the most common source
+> of browser-test flakiness. Use `gotoReady` (or an equivalent readiness wait) on any
+> page driven by Flow's Alpine runtime.
+
+## Tips
+
+- **Seed deterministic state.** If a flow needs data, seed it before the run (or use
+  pages backed by in-memory state). Browser tests don't share the transactional
+  rollback that [database tests](/docs/testing/database) use.
+- **Prefer role/label selectors** (`getByRole`, `getByLabel`) over CSS — they're
+  resilient to markup changes and assert accessibility.
+- **Run cross-browser in CI.** The three projects above cover Chromium, Firefox, and
+  WebKit; enable retries on CI to absorb transient flakiness.
+
+## Next steps
+
+- [HTTP Tests](/docs/testing/http) — faster tests for anything not needing a browser.
+- [Database Tests](/docs/testing/database) — seed and roll back data for backed flows.
+- [Flow](/docs/flow) / [Inertia](/docs/inertia) — the client runtimes these tests exercise.
+- [Deployment](/docs/deployment) — `bun run start`, the command the `webServer` boots.

package/docs/testing/console.md

@@ -0,0 +1,130 @@
+---
+title: Console Tests
+description: Run CLI commands in-process from a test and assert their output, exit code, and side effects.
+---
+
+# Console Tests
+
+Console tests exercise your [CLI commands](/docs/commands) — generators, migrations,
+maintenance tasks — without spawning a subprocess. `Artisan.call()` runs a registered
+command **in-process**, captures everything it printed, and returns its exit code.
+
+```typescript
+// in a test file
+import { Artisan } from "zerotal";
+```
+
+> **Note** — `Artisan.call()` needs a `CommandRunner` bound under `commands` in the
+> container — present in `web` and `console` runtime modes. When you boot the app with
+> [`createTestApp()`](/docs/testing/http), commands are registered for you.
+
+## Running a command
+
+`Artisan.call(name, parameters?)` returns `{ code, output }` — `code` is `0` on
+success, and `output` is everything the command wrote via `info`/`warn`/`error`/etc.:
+
+```typescript
+// src/tests/CacheClearTest.ts
+import { describe, it, expect } from "bun:test";
+import { Artisan } from "zerotal";
+
+describe("cache:clear", () => {
+  it("clears the cache and reports success", async () => {
+    const { code, output } = await Artisan.call("cache:clear");
+
+    expect(code).toBe(0);
+    expect(output).toContain("Cache cleared");
+  });
+});
+```
+
+Pass arguments and flags as a parameter map. Booleans become bare flags when `true`;
+everything else becomes a `key=value` token, mirroring how the CLI parses argv:
+
+```typescript
+// in a test file
+await Artisan.call("migrate", { "--fresh": true });
+await Artisan.call("make:model", { name: "Post", "--migration": true });
+```
+
+Output is captured, so nothing leaks to the test runner's console.
+
+## Asserting side effects
+
+Commands usually do work — touch the database, queue a job, write a file. Assert the
+_effect_, not just the output, using the [database](/docs/testing/database) and
+[mocking](/docs/testing/mocking) helpers:
+
+```typescript
+// src/tests/PruneUsersTest.ts
+import { Artisan } from "zerotal";
+import { assertDatabaseCount, QueueFake } from "@zerotal/testing";
+
+it("prune:users deletes stale accounts and queues a report", async () => {
+  const queue = QueueFake.install();
+
+  const { code } = await Artisan.call("prune:users", { "--days": 30 });
+
+  expect(code).toBe(0);
+  await assertDatabaseCount("users", 5);
+  queue.assertDispatched(PruneReportJob);
+
+  queue.restore();
+});
+```
+
+## Unit-testing a command class
+
+For a focused test of a single command's logic, instantiate it directly and inject a
+`BufferWriter` to capture output. The `_writer`, `args`, and `flags` fields are
+internal — the runner normally sets them — so a unit test reaches in with a cast:
+
+```typescript
+// src/tests/GreetCommandTest.ts
+import { expect } from "bun:test";
+import { BufferWriter } from "zerotal";
+import { GreetCommand } from "../app/commands/GreetCommand.ts";
+
+const cmd = new GreetCommand();
+const buffer = new BufferWriter();
+
+// These are internal fields the CommandRunner usually populates:
+(cmd as any)._writer = buffer; // capture output instead of printing
+(cmd as any).args = { name: "Alice" };
+(cmd as any).flags = {};
+
+await cmd.run();
+
+expect(buffer.flush()).toContain("Hello, Alice");
+```
+
+> **Tip** — Prefer `Artisan.call()` for end-to-end command behavior — it wires the
+> runner for you. Reach for direct instantiation only when you deliberately want to
+> bypass the runner.
+
+## Which approach should I use?
+
+- **`Artisan.call(name, params?)`** — the default. Use it whenever you want the real
+  command behavior: argument parsing, flag defaults, container resolution, and the
+  command's full `run()`. Assert on `code` and `output`, plus any side effects.
+- **Direct instantiation + `BufferWriter`** — only for unit-testing one command's
+  logic in isolation. You bypass the runner, so you must set `_writer`, `args`, and
+  `flags` yourself.
+
+## References
+
+The console-testing surface lives in `@zerotal/core`:
+
+| Member               | Signature                                                                                              | Description                                                      |
+| -------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `Artisan.call`       | `call(name: string, parameters?: Record<string, string \| boolean \| number>): Promise<ArtisanResult>` | Run a registered command in-process and capture its output.      |
+| `ArtisanResult`      | `{ code: number; output: string }`                                                                     | Exit code (`0` = success) and the captured output string.        |
+| `BufferWriter`       | `class BufferWriter implements OutputWriter`                                                           | Capturing writer; collects output in memory instead of printing. |
+| `BufferWriter.flush` | `flush(): string`                                                                                      | Return all captured output as one string and clear the buffer.   |
+
+## Next steps
+
+- [Commands](/docs/commands) — writing and registering commands.
+- [Database](/docs/testing/database) — asserting a command's DB effects.
+- [Mocking](/docs/testing/mocking) — asserting queued jobs and sent mail.
+- [HTTP Tests](/docs/testing/http) — boot the app and exercise it over real requests.

package/docs/testing/database.md

@@ -0,0 +1,238 @@
+---
+title: Database Testing
+description: Keep database tests isolated with per-test transactional rollback and assert on rows and stored files.
+---
+
+# Database Testing
+
+Tests that touch the database must stay isolated — one test's writes can't leak into
+the next. Zerotal wraps each test in a transaction that **rolls back** when it finishes,
+and ships assertions for checking rows and stored files.
+
+```typescript
+// in a test file
+import {
+  migrateDatabase,
+  refreshDatabase,
+  withDatabase,
+  assertDatabaseHas,
+  assertDatabaseMissing,
+  assertDatabaseCount,
+} from "@zerotal/testing";
+```
+
+> **Note** — These helpers are part of the [testing toolkit](/docs/testing/index) and
+> only run inside `bun test`. Install the package as a dev dependency if it isn't
+> already: `bun add -d @zerotal/testing`.
+
+## Building the schema
+
+A test needs tables before it needs rows. Build them by running the project's own
+[migrations](/docs/migrations) rather than by writing the schema a second time:
+
+```typescript
+// tests/Feature/PostTest.ts
+import { migrateDatabase } from "@zerotal/testing";
+
+beforeAll(async () => {
+  app = await createApp();
+  await migrateDatabase();
+});
+```
+
+A hand-written `CREATE TABLE` in a test is a second definition of the same tables,
+and the two drift. A column added in a migration is missing from the test schema
+until something fails for a reason that has nothing to do with the change you
+made. Running the migrations themselves means the schema under test is the schema
+that ships.
+
+```typescript
+// signature
+function migrateDatabase(options?: MigrateDatabaseOptions): Promise<string[]>;
+```
+
+| Option       | Type          | Default                 | Purpose                         |
+| ------------ | ------------- | ----------------------- | ------------------------------- |
+| `connection` | `SQLInstance` | the active connection   | Which database to migrate.      |
+| `path`       | `string`      | `"database/migrations"` | Where the migration files live. |
+| `table`      | `string`      | `"migrations"`          | Tracking-table name.            |
+
+It returns the names of the migrations it applied, and is idempotent — a second
+call applies nothing. `refreshDatabase({ migrate: true })` runs it for you, which
+is usually what you want:
+
+```typescript
+// in a test file
+describe("Post", () => {
+  refreshDatabase({ connection: db, migrate: true });
+  // …the real schema, and every test rolled back after itself
+});
+```
+
+For a file-backed or server test database — where migrating once up front beats
+migrating per test file — `bun zt test --migrate` applies them before the suite
+starts. An `:memory:` database belongs to the process that opened it, so there is
+nothing for a parent process to migrate; use `refreshDatabase({ migrate: true })`
+there.
+
+## Which rollback helper do I use?
+
+Both run your test inside a transaction that rolls back, leaving the database
+untouched. Choose by scope:
+
+- **`refreshDatabase`** — call once in a `describe` block to roll back _every_ test in
+  it, and (optionally) install a connection and run schema setup once. Reach for this
+  in feature suites where many tests share the same tables.
+- **`withDatabase`** — wrap a _single_ `it()` body when only that one test needs
+  rollback. No `describe`-level setup.
+
+## refreshDatabase — suite-level rollback
+
+Call it once inside a `describe` block. Every `it()` in that block runs inside a
+transaction that rolls back when the test ends, so each test starts from the same
+clean baseline:
+
+```typescript
+// tests/Feature/UserTest.ts
+import { describe, it } from "bun:test";
+import { refreshDatabase, assertDatabaseHas, assertDatabaseMissing } from "@zerotal/testing";
+import { SQL } from "bun";
+import { User } from "../app/models/User.ts";
+
+const db = new SQL(":memory:");
+
+describe("User", () => {
+  refreshDatabase({ connection: db, migrate: true });
+
+  it("creates a user", async () => {
+    await User.create({ email: "a@b.com" });
+    await assertDatabaseHas("users", { email: "a@b.com" });
+  }); // ← rolled back; next test starts clean
+
+  it("starts clean", async () => {
+    await assertDatabaseMissing("users", { email: "a@b.com" });
+  });
+});
+```
+
+```typescript
+// signature
+function refreshDatabase(options?: RefreshDatabaseOptions): void;
+```
+
+| Option       | Type                           | Required | Purpose                                                                              |
+| ------------ | ------------------------------ | -------- | ------------------------------------------------------------------------------------ |
+| `connection` | `SQLInstance`                  | no       | Install as the model connection for this suite. Omit to use the existing connection. |
+| `migrate`    | `boolean \| string`            | no       | Run the project's migrations first. A string names a different directory.            |
+| `setup`      | `(db: SQLInstance) => unknown` | no       | Runs once before the suite and is **committed**, so every test sees it.              |
+| `teardown`   | `(db: SQLInstance) => unknown` | no       | Runs once after all tests complete.                                                  |
+
+Both `migrate` and `setup` are committed (they are the schema and any shared
+fixtures), while each test's own writes happen inside the rolled-back transaction.
+
+> **Warning** — `refreshDatabase()` only works inside a `bun test` run; it pulls
+> `beforeAll`/`afterEach` from `bun:test`. Calling it outside the test runner throws.
+
+## withDatabase — per-test wrapper
+
+When you want rollback for a single test rather than a whole block, wrap the test body:
+
+```typescript
+// in a test file
+import { withDatabase } from "@zerotal/testing";
+
+it(
+  "creates a user",
+  withDatabase(async () => {
+    await User.create({ email: "a@b.com" });
+    await assertDatabaseHas("users", { email: "a@b.com" });
+  }),
+); // ← transaction rolled back here
+```
+
+```typescript
+// signature
+function withDatabase(fn: () => Promise<void>): () => Promise<void>;
+```
+
+A test failure inside the callback still rolls the transaction back, then re-throws so
+the assertion is reported.
+
+## Database assertions
+
+Each assertion runs a `COUNT(*)` against the current connection and throws a
+descriptive error when the expectation fails:
+
+```typescript
+// in a test file
+import { assertDatabaseHas, assertDatabaseMissing, assertDatabaseCount } from "@zerotal/testing";
+
+await assertDatabaseHas("users", { email: "alice@example.com", role: "admin" });
+await assertDatabaseMissing("users", { email: "deleted@example.com" });
+await assertDatabaseCount("posts", 5);
+await assertDatabaseCount("posts", 2, { published: 1 }); // optional where filter
+```
+
+| Function                                | Throws when                       |
+| --------------------------------------- | --------------------------------- |
+| `assertDatabaseHas(table, where)`       | No row matches `where`.           |
+| `assertDatabaseMissing(table, where)`   | A matching row exists.            |
+| `assertDatabaseCount(table, n, where?)` | The matching row count isn't `n`. |
+
+## Storage assertions
+
+For tests that write to a [storage](/docs/storage) disk, assert file presence without
+reading bytes. Pass a disk name or a `StorageDriver` instance:
+
+```typescript
+// in a test file
+import { assertStoredFile, assertMissingFile } from "@zerotal/testing";
+
+await assertStoredFile("local", "uploads/avatar.jpg");
+await assertMissingFile("local", "uploads/old.jpg");
+```
+
+> **Note** — A disk name routes through the `Storage` facade (needs
+> `StorageProvider` registered); a `StorageDriver` instance lets isolated unit tests
+> skip the facade entirely.
+
+## Arranging rows
+
+Use [factories](/docs/orm/factories) to build the records a test acts on, and
+[seeders](/docs/seeding) for shared fixtures:
+
+```typescript
+// in a test file
+import { UserFactory } from "../database/factories/UserFactory.ts";
+import { PostFactory } from "../database/factories/PostFactory.ts";
+
+const editor = await UserFactory.state("editor").create();
+const posts = await PostFactory.for(editor).count(3).create();
+```
+
+Factories suppress model observers by default, so seeding rows doesn't fire emails or
+jobs — call `.dispatchEvents()` when a test needs the full lifecycle.
+
+> **Tip** — `.for(editor)` injects the parent's primary key as the `<Model>Id`
+> foreign key, so child rows line up with the record you created.
+
+## References
+
+| Function                | Signature                                                                             | Description                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `migrateDatabase`       | `(options?: MigrateDatabaseOptions) => Promise<string[]>`                             | Build the schema by running the project's migrations.                    |
+| `refreshDatabase`       | `(options?: RefreshDatabaseOptions) => void`                                          | Roll back every test in a `describe` block; optional connection + setup. |
+| `withDatabase`          | `(fn: () => Promise<void>) => () => Promise<void>`                                    | Wrap one `it()` body in a transaction that always rolls back.            |
+| `assertDatabaseHas`     | `(table: string, where: Record<string, unknown>) => Promise<void>`                    | Pass when at least one row matches `where`.                              |
+| `assertDatabaseMissing` | `(table: string, where: Record<string, unknown>) => Promise<void>`                    | Pass when no row matches `where`.                                        |
+| `assertDatabaseCount`   | `(table: string, expected: number, where?: Record<string, unknown>) => Promise<void>` | Pass when the matching row count equals `expected`.                      |
+| `assertStoredFile`      | `(diskOrDriver: string \| StorageDriver, path: string) => Promise<void>`              | Pass when the file exists on the disk or driver.                         |
+| `assertMissingFile`     | `(diskOrDriver: string \| StorageDriver, path: string) => Promise<void>`              | Pass when the file is absent from the disk or driver.                    |
+
+## Next steps
+
+- [Testing overview](/docs/testing/index) — the full toolkit and a first test.
+- [Factories](/docs/orm/factories) — generating model records for tests.
+- [Seeding](/docs/seeding) — reusable fixtures across dev and tests.
+- [Database](/docs/database) — transactions and the raw `DB` layer being rolled back.
+- [HTTP Tests](/docs/testing/http) — drive these rolled-back rows through real requests.