@shaferllc/keel 0.68.0 → 0.77.0

package/docs/testing.md

@@ -90,6 +90,258 @@ kernel.use(requestLogger());
 const client = testClient(kernel);
 ```
 
+## Authenticated requests
+
+The client's `withX` methods return a **copy**, so a client configured once can be
+reused without leaking into other tests:
+
+```ts
+const authed = client.withToken("tok_123"); // Authorization: Bearer tok_123
+
+await authed.get("/me");
+await client.get("/me"); // still anonymous
+```
+
+| Method | Sends |
+|--------|-------|
+| `withToken(token)` | `Authorization: Bearer <token>` |
+| `withBasicAuth(user, pass)` | `Authorization: Basic <base64>` |
+| `withHeader(name, value)` / `withHeaders({…})` | any header |
+| `withCookie(name, value)` / `withCookies({…})` | a `Cookie` header |
+| `acceptJson()` | `Accept: application/json` |
+
+## Forms and uploads
+
+```ts
+await client.form("/login", { email: "a@b.com", password: "s3cret" }); // url-encoded
+await client.multipart("/avatar", { file: new Blob([png]), name: "ada" }); // file upload
+```
+
+## More response assertions
+
+```ts
+res.assertOk(); // 2xx
+res.assertCreated(); // 201
+res.assertNoContent(); // 204
+res.assertUnauthorized(); // 401
+res.assertForbidden(); // 403
+res.assertNotFound(); // 404
+res.assertUnprocessable(); // 422
+res.assertServerError(); // 5xx
+```
+
+**`assertJsonContains` is a subset match** — the one you usually want. It pins the
+fields the test is about and ignores the rest, so adding a field to a response
+doesn't break twenty tests:
+
+```ts
+res.assertJsonContains({ user: { email: "a@b.com" } });
+```
+
+`assertJson` still deep-equals the whole body, when that's what you mean.
+
+```ts
+res.assertSee("Welcome back"); // body contains
+res.assertDontSee("Sign up");
+
+res.assertHeader("content-type", "application/json");
+res.assertHeaderMissing("x-debug");
+
+res.assertCookie("session"); // was set
+res.assertCookie("session", "abc123"); // ...with this value
+res.assertCookieMissing("admin");
+
+res.dump(); // print status, headers, body — when you're stuck
+```
+
+### Validation
+
+A failed `validate()` returns a 422 with per-field errors, so a test can assert on
+the field rather than the message:
+
+```ts
+const res = await client.post("/users", { email: "nope" });
+
+res.assertValidationErrors("email", "password");
+res.assertNoValidationError("name");
+```
+
+## Test doubles
+
+Keel's fakes swap out a real backend for a recording one, so a test can assert
+that something *would* have happened without it actually happening — no email
+sent, no card charged, no file uploaded.
+
+| Fake | Replaces | Assertions |
+|------|----------|------------|
+| [`fakeMail()`](./mail.md#in-tests) | the mailer | `assertSent`, `assertQueued`, … |
+| [`fakeQueue()`](./queues.md#in-tests) | the queue | `assertPushed`, `assertNothingPushed`, … |
+| [`fakeDisk()`](./storage.md#testing) | a storage disk | `assertExists`, `assertContents`, … |
+| [`events().fake()`](./events.md#testing) | the emitter | `assertEmitted`, `assertNotEmitted`, … |
+| [`hash.fake()`](./hashing.md) | PBKDF2 | — (just makes it fast) |
+
+```ts
+const mailer = fakeMail();
+const queue = fakeQueue();
+
+await registerUser({ email: "ada@example.com" });
+
+mailer.assertQueued((m) => m.subject === "Welcome");
+queue.assertPushed(SendWelcome);
+```
+
+For anything else, `swap()` replaces a container binding:
+
+```ts
+swap(PaymentGateway, () => new FakeGateway());
+```
+
+### Spies
+
+The smallest double: a function that records how it was called.
+
+```ts
+import { spy, spyOn, restoreSpies } from "@shaferllc/keel/core";
+
+const send = spy<[string], void>();
+notify(send);
+
+assert.equal(send.callCount, 1);
+assert.ok(send.calledWith("hello"));
+```
+
+`spyOn` replaces a method on an object. It **calls through** by default — so you're
+observing, not stubbing — until you tell it otherwise:
+
+```ts
+const charge = spyOn(gateway, "charge"); // still really charges
+charge.returns(receipt); // now it doesn't
+
+restoreSpies(); // put every spied method back
+```
+
+## Controlling time
+
+Testing "this token expires in an hour" shouldn't take an hour.
+
+```ts
+import { freezeTime, timeTravel, restoreTime } from "@shaferllc/keel/core";
+
+freezeTime("2026-07-11T12:00:00Z");
+
+const token = await jwt.sign({ sub: "1" }, { expiresIn: "1h" });
+assert.ok(await jwt.verify(token)); // valid now
+
+timeTravel(61 * 60 * 1000); // an hour and a minute later
+assert.equal(await jwt.verify(token), null); // expired
+
+restoreTime();
+```
+
+`freezeTime()` mocks `Date` and `Date.now()`. It does **not** mock timers — a
+`setTimeout` still fires on the real clock — and `new Date("2020-01-01")` still
+parses normally. Only "what time is it *now*" is frozen.
+
+## Resetting state between tests
+
+Keel's fakes, disks, queues, and cache are process-global, so one test can leak
+into the next. `resetState()` puts it all back:
+
+```ts
+import { resetState } from "@shaferllc/keel/core";
+
+afterEach(() => resetState());
+```
+
+It restores every fake (mail, queue, disk, hash), unfreezes the clock, drops event
+listeners, empties the cache, and gives you a fresh lock store. It does **not**
+touch the database.
+
+For that, `truncate()`:
+
+```ts
+afterEach(() => truncate("comments", "posts", "users")); // children before parents
+```
+
+It deletes rows rather than rolling back a transaction, so it works on every driver
+(D1, Postgres, libSQL) instead of only the ones with savepoints.
+
+## Database assertions
+
+Assert against the database directly, rather than through an endpoint:
+
+```ts
+import { assertDatabaseHas, assertDatabaseMissing, assertDatabaseCount } from "@shaferllc/keel/core";
+
+await client.post("/users", { email: "ada@example.com" });
+
+await assertDatabaseHas("users", { email: "ada@example.com" });
+await assertDatabaseHas("users", { active: 1 }, 1); // exactly one match
+await assertDatabaseMissing("users", { email: "deleted@example.com" });
+await assertDatabaseCount("users", 1);
+await assertDatabaseEmpty("sessions");
+```
+
+A failure tells you what it looked for and how many rows the table actually holds.
+
+## Console tests
+
+Run a command in-process — no subprocess, so it's fast and you can assert on it:
+
+```ts
+import { runCommand } from "@shaferllc/keel/core";
+import { run } from "@shaferllc/keel/cli";
+import { createApplication } from "../bootstrap/app.js";
+
+const result = await runCommand(() => run(["node", "keel", "routes"], { createApplication }));
+
+result
+  .assertSucceeded() // exit code 0
+  .assertOutputContains("GET  /users")
+  .assertOutputMatches(/POST\s+\/users/);
+```
+
+You pass the command **in**, because a command needs an *application*, and only your
+app knows how to build one. That's also why `run()` takes a `createApplication`
+factory rather than importing one. Anything that prints and sets an exit code works,
+so this is equally good for testing a function you wrote yourself.
+
+`console.log`/`warn` are captured as stdout and `console.error` as stderr; a
+command that *throws* is recorded as a failure rather than blowing up the test.
+
+`assertFailed()`, `assertExitCode(n)`, and `assertErrorContains(text)` cover the
+rest. `result.stdout`, `result.stderr`, and `result.exitCode` are there if you'd
+rather assert by hand.
+
+## Browser tests
+
+Keel doesn't ship a browser driver — that's [Playwright](https://playwright.dev)'s
+job, and wrapping it would only put a thinner API in front of a better one.
+
+The test client injects requests *without a server*, which is what makes it fast;
+a browser needs a real one. Start the app on a port, point Playwright at it, and
+tear it down:
+
+```ts
+import { serve } from "@hono/node-server";
+import { chromium } from "playwright";
+
+const server = serve({ fetch: new HttpKernel(app).build().fetch, port: 3001 });
+const browser = await chromium.launch();
+
+const page = await browser.newPage();
+await page.goto("http://localhost:3001/login");
+await page.fill("[name=email]", "ada@example.com");
+await page.click("button[type=submit]");
+await page.waitForURL("**/dashboard");
+
+await browser.close();
+server.close();
+```
+
+Everything else on this page — the fakes, `freezeTime`, `resetState`, the database
+assertions — works the same in a browser test, because it's the same process.
+
 ## API reference
 
 ### `testClient(target)`

package/docs/watch.md

@@ -0,0 +1,118 @@
+# Watch
+
+Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
+scheduled tasks flowing through your app, and shows them in a single-page UI at
+`/watch`, with every request linked to the queries and logs it produced.
+
+It ships as a Keel [package](./packages.md) and is its reference implementation:
+one `register()` turns it on, and its watchers observe the framework's
+instrumentation event stream — they patch nothing, so installing Watch changes no
+behaviour, only visibility.
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { WatchServiceProvider } from "@shaferllc/keel/watch";
+
+export const providers = [AppServiceProvider, WatchServiceProvider];
+```
+
+Publish the config and create the table:
+
+```bash
+keel vendor:publish --tag watch-config   # writes config/watch.ts
+keel migrate                             # creates watch_entries
+```
+
+Then open `http://localhost:3000/watch`.
+
+> Watch exposes requests, payloads, and stack traces. It is gated shut in
+> production by default (see [Access](#access)) — keep it that way, or lock it
+> down with your own check.
+
+## What it records
+
+A tab per type, each behind an on/off switch:
+
+| Watcher | Records |
+|---------|---------|
+| Requests | method, path, status, duration, headers (auth/cookies redacted) |
+| Queries | SQL, bindings, duration, connection; slow queries are tagged |
+| Exceptions | class, message, stack, the request that threw |
+| Logs | every log line, at any level |
+| Mail | sent messages (subject, recipients, body) |
+| Jobs | queued jobs as they complete or fail |
+| Notifications | deliveries and their channels |
+| Cache | hits and misses *(off by default — noisy)* |
+| Events | app events *(off by default — noisy)* |
+| Schedule | scheduled tasks as they run |
+
+Clicking any entry shows its full detail and **everything else in its batch** —
+the request it belonged to and every query, log, and exception that request
+produced.
+
+## Configuration
+
+`config/watch.ts` (publish it, then edit):
+
+```ts
+export default {
+  enabled: env("WATCH_ENABLED", true),
+  path: "watch",                 // the dashboard mounts at /watch
+  storage: "database",           // "database" persists; "memory" is a per-process ring
+  connection: undefined,         // which DB connection (default when omitted)
+  table: "watch_entries",
+  limit: 100,                    // API page size; the memory ring is 10× this
+  sampling: 1,                   // record this fraction of entries (0–1)
+  slowQueryMs: 100,              // queries at/above this are tagged "slow"
+  ignorePaths: [],               // request paths to skip
+  retentionHours: 24,            // keel watch:prune deletes entries older than this
+  watchers: { cache: false, event: false /* … the rest default on */ },
+};
+```
+
+### Storage
+
+- **`database`** (default) — a `watch_entries` table via any registered
+  connection. Survives restarts, shared across processes; needs `keel migrate`.
+- **`memory`** — a per-process ring buffer. Zero setup, great for a single dev
+  process or the edge; entries vanish on restart and aren't shared.
+
+## Access
+
+By default the dashboard is open only when `app.debug` is on or the app isn't in
+production. Anywhere else, lock it to your own check:
+
+```ts
+import { Watch } from "@shaferllc/keel/watch";
+import { auth } from "@shaferllc/keel/core";
+
+Watch.auth(() => auth().check() && Boolean(auth().user()?.isAdmin));
+```
+
+The gate guards the JSON API too, so entries can't be read by anyone the
+dashboard wouldn't show them to.
+
+## Pruning
+
+With database storage, keep the table small:
+
+```bash
+keel watch:prune            # delete entries older than retentionHours
+keel watch:prune --hours=6
+```
+
+Schedule it (see [Scheduling](./scheduling.md)) to run it automatically.
+
+## How it works
+
+Watch never wraps or monkey-patches the framework. The core emits a typed
+[instrumentation event stream](./packages.md#observing-the-framework) —
+`db.query`, `request.handled`, `exception`, `job.*`, and so on — and each watcher
+is just a listener that turns an event into a stored entry, stamped with the
+current request id so related entries group into one batch. Recording is
+fire-and-forget: it never blocks or breaks the request it's watching, and the
+store's own queries are filtered out so it never records itself.
+```