@specific.dev/spectest 0.35.0 → 0.36.0

package/dist/components/postgres.d.ts

@@ -1,3 +1,4 @@
+import type { ServiceSetupContext } from "../index.js";
 import { type SqlClient } from "../sql.js";
 export interface PostgresOptions {
     /** Image tag for the official `postgres` image. Default `"18-alpine"`.
@@ -32,6 +33,28 @@ export interface PostgresOptions {
     args?: string[];
     /** Extra environment variables forwarded to the container. */
     env?: Record<string, string>;
+    /**
+     * One-shot hook that runs after the ready probe passes, before any
+     * dependent service starts and before any test. This is where schema
+     * and seed data go: the daemon captures the result into the
+     * warm-template snapshot, so it never runs again on a warm start or a
+     * fork.
+     *
+     * The argument is the full test context plus this service's `name` and
+     * its {@link PostgresHelpers}, so the instrumented client is already
+     * built:
+     *
+     * ```ts
+     * db: postgres({
+     *   database: "todos", user: "todos", password: "todos",
+     *   setup: async ({ helpers }) => {
+     *     await helpers.client`CREATE TABLE todos (
+     *       id SERIAL PRIMARY KEY, text TEXT NOT NULL)`;
+     *   },
+     * }),
+     * ```
+     */
+    setup?: (args: ServiceSetupContext<PostgresHelpers>) => void | Promise<void>;
 }
 /** Helpers a `postgres(...)` service exposes on `ctx.svc.<name>`. */
 export interface PostgresHelpers {
@@ -67,6 +90,7 @@ export interface PostgresHelpers {
  * ```
  */
 export declare function postgres(opts: PostgresOptions): {
+    setup?: ((args: ServiceSetupContext<PostgresHelpers>) => void | Promise<void>) | undefined;
     env: {
         POSTGRES_DB: string;
         POSTGRES_USER: string;

package/dist/components/postgres.js

@@ -54,5 +54,10 @@ export function postgres(opts) {
                 `@${name}:${port}/${encodeURIComponent(opts.database)}`;
             return { client: new SQL(url, { label: name }) };
         },
+        // The user's hook, forwarded verbatim — postgres() declares none of
+        // its own. If it ever gains one, CHAIN the user's after it (the way
+        // `serviceGroup` chains a group hook after the primary part's) rather
+        // than letting either one win.
+        ...(opts.setup ? { setup: opts.setup } : {}),
     };
 }

package/dist/index.d.ts

@@ -455,8 +455,17 @@ export interface ServiceDefinition<H extends Record<string, any> = Record<string
 }
 /** A services map — what users pass to `environment.services`. Entries
  * can be plain `ServiceConfig` literals or `ServiceDefinition`s that
- * carry a `helpers` factory (e.g. what `postgres(...)` returns). */
-export type ServicesMap = Record<string, ServiceConfig>;
+ * carry a `helpers` factory (e.g. what `postgres(...)` returns).
+ *
+ * The entry type is `ServiceDefinition`, not `ServiceConfig`: at runtime
+ * the map really does hold `helpers`/`setup` (the daemon reads them off
+ * each entry), and both are optional, so every plain `ServiceConfig`
+ * still satisfies it. Narrowing this to `ServiceConfig` — the wire type,
+ * which by definition carries no functions — made the natural way to
+ * hoist a services map out of `index.ts` (`… satisfies ServicesMap`) fail
+ * the typecheck on any service declaring a hook, while the same literal
+ * written inline passed. */
+export type ServicesMap = Record<string, ServiceDefinition<any>>;
 /** Awaited return type of a service's `helpers` factory, or `never` if
  * the service doesn't ship one. */
 type HelpersOf<D> = D extends {
@@ -1390,16 +1399,43 @@ export declare function expect(actual: Locator, message?: string): LocatorAssert
 export declare function expect(actual: Browser, message?: string): BrowserAssertion;
 export declare function expect(actual: Provenanced, message?: string): Expectation;
 /**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed from a
+ * recorded op. `message` is required (it's the second argument) and reads as
+ * the natural follow-on to "assert …" (e.g.
+ * `expectRaw(id, "id matches the generated value")`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
  */
 export declare function expectRaw(actual: unknown, message: string): Expectation;
 /** `node:assert/strict` re-exported for users who prefer Node's built-in API. */

package/dist/index.js

@@ -657,16 +657,43 @@ function buildBrowserMatchers(session, negated, message) {
     };
 }
 /**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed from a
+ * recorded op. `message` is required (it's the second argument) and reads as
+ * the natural follow-on to "assert …" (e.g.
+ * `expectRaw(id, "id matches the generated value")`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
  */
 export function expectRaw(actual, message) {
     // Force the raw form so no stray tag is read even if a wrapped value is

package/dist/inspect.d.ts

@@ -106,8 +106,14 @@ export interface Carrier<T> {
  * `null`/`undefined` are also admitted: a nullish leaf can't carry the symbol
  * tag, but `adoptNullishTag` recovers its provenance at runtime, so
  * `expect(rows[0]?.text)` and `expect(dep.status.readyReplicas)` stay on
- * `expect`. To assert on a value with no provenance (a computed number, a raw
- * WebSocket frame), use `expectRaw(value, message)` instead.
+ * `expect`.
+ *
+ * When this gate rejects a value, the fix is usually to stop flattening it —
+ * `.transform(label, fn)` instead of a decode-then-`.unwrap()`, `toHaveLength`
+ * instead of `.length` — not to switch to `expectRaw`, which accepts anything
+ * but renders the assertion unlinked. Reach for `expectRaw(value, message)`
+ * only when the value never flowed from a recorded op at all (a computed
+ * number, a frame off a raw WebSocket); see its own doc comment.
  */
 export type Provenanced = {
     unwrap(): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",