@strav/testing 0.4.31 → 1.0.0-alpha.25

package/README.md

@@ -1,82 +1,45 @@
 # @strav/testing
 
-Testing utilities for the [Strav](https://www.npmjs.com/package/@strav/core) framework. Provides HTTP testing helpers, authentication simulation, transaction-based test isolation, and model factories.
-
-## Install
-
-```bash
-bun add -d @strav/testing
-```
-
-Requires `@strav/core` as a peer dependency.
-
-## TestCase
-
-Boots the app, provides HTTP helpers, and wraps each test in a rolled-back transaction for full isolation.
+Small, focused testing utilities for Strav apps and the framework itself.
 
 ```ts
-import { describe, test, expect } from 'bun:test'
-import { TestCase } from '@strav/testing'
-
-const t = await TestCase.boot({
-  auth: true,
-  routes: () => import('./start/api_routes'),
-})
-
-describe('Posts API', () => {
-  test('list posts', async () => {
-    const res = await t.get('/api/posts')
-    expect(res.status).toBe(200)
-  })
-
-  test('create post as authenticated user', async () => {
-    const user = await UserFactory.create()
-    await t.actingAs(user)
-
-    const res = await t.post('/api/posts', { title: 'Hello' })
-    expect(res.status).toBe(201)
-  })
-})
+import {
+  bootTestApp,
+  isPostgresAvailable,
+  MemStream,
+  stubFetch,
+} from '@strav/testing'
+
+if (!await isPostgresAvailable()) {
+  test.skip('integration: …', () => {})
+} else {
+  // real Postgres flow
+}
+
+const stdout = new MemStream()
+const fetch = stubFetch(async (req) => Response.json({ ok: true }))
 ```
 
-### HTTP Methods
+Canonical docs live in [`docs/testing/README.md`](../../docs/testing/README.md).
 
-```ts
-await t.get('/path')
-await t.post('/path', body)
-await t.put('/path', body)
-await t.patch('/path', body)
-await t.delete('/path')
-```
-
-### Auth Helpers
-
-```ts
-await t.actingAs(user)        // authenticate as user
-t.withHeaders({ 'X-Custom': 'value' })
-t.withoutAuth()               // clear auth token
-```
+## What ships
 
-## Factory
+| Surface | Notes |
+|---|---|
+| `bootTestApp({ config, schemas, migrations, providers })` | Replaces the ~50-line `beforeAll` boilerplate every e2e was rolling. Auto-supplies the standard four providers, applies schemas + migrations against `setupDb`, returns `{ app, setupDb, dispose }`. |
+| `composeTestConfig(overrides)` | Merges logger + database defaults with per-test overrides. Used internally by `bootTestApp`; exported for tests that want the config tree without the orchestrator. |
+| `TenantManagerProvider` | Standard 3-line wiring extracted from m5 / m6 / m7. |
+| `MemStream` | In-memory `NodeJS.WritableStream` for asserting on stdout / stderr. Pairs with `ConsoleOutput`. |
+| `stubFetch(handler)` | Typed `fetch` replacement. Confines the `as unknown as typeof fetch` cast to one place. |
+| `isPostgresAvailable()` | Cached probe — returns `false` when env is missing or connection fails. |
+| `createTestDatabase()` | Construct a fresh `PostgresDatabase` from `DB_HOST`/`DB_PORT`/etc. |
+| `resetSchema(db)` | DROP + recreate `public` schema. |
+| `connectedRoleBypassesRls(db)` | True for SUPERUSER / BYPASSRLS roles — tests use it to degrade RLS assertions. |
+| `testDatabaseUrl()` | Returns the Postgres URL or `null` when env is missing. |
 
-Lightweight model factory for test data seeding.
-
-```ts
-import { Factory } from '@strav/testing'
-
-const UserFactory = Factory.define(User, (seq) => ({
-  pid: crypto.randomUUID(),
-  name: `User ${seq}`,
-  email: `user-${seq}@test.com`,
-  passwordHash: 'hashed',
-}))
-
-const user = await UserFactory.create()
-const users = await UserFactory.createMany(5)
-const user = await UserFactory.create({ name: 'Custom' })
-const instance = UserFactory.make()  // in-memory only, no DB
-```
+## Subpaths
 
-## License
+- `@strav/testing/postgres` — narrow import for just the Postgres helpers.
+- `@strav/testing/brain` — `stubBrainProvider({ embed, model? })`. Requires `@strav/brain` installed (peer-optional).
 
-MIT
+Deferred to follow-up slices: `stubPaymentDriver`, `stubSocialDriver` — extract when the inline forms in `tests/e2e/m{6,7}-*/` show overlap.

package/package.json

@@ -1,44 +1,38 @@
 {
   "name": "@strav/testing",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.25",
+  "description": "Strav testing utilities — in-memory stream, typed fetch stub, Postgres availability probe + schema reset, bootTestApp orchestrator, stub providers.",
   "type": "module",
-  "description": "Testing utilities for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./*": "./src/*.ts"
+    "./brain": "./src/brain/index.ts",
+    "./cache": "./src/cache/index.ts",
+    "./postgres": "./src/postgres/index.ts"
   },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/database": "1.0.0-alpha.25",
+    "@strav/kernel": "1.0.0-alpha.25"
+  },
   "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/http": "0.4.31",
-    "@strav/view": "0.4.31",
-    "@strav/database": "0.4.31",
-    "@strav/signal": "0.4.31",
-    "@strav/cli": "0.4.31",
-    "playwright-core": "^1.45.0"
+    "@strav/brain": "1.0.0-alpha.25",
+    "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {
-    "@strav/signal": {
-      "optional": true
-    },
-    "@strav/cli": {
-      "optional": true
-    },
-    "playwright-core": {
+    "@strav/brain": {
       "optional": true
     }
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "playwright-core": "^1.45.0"
-  }
+  "devDependencies": null
 }

package/src/boot_test_app.ts

@@ -0,0 +1,169 @@
+/**
+ * Boot a tested Application with the standard four providers
+ * (`ConfigProvider` → `LoggerProvider` → `DatabaseProvider` →
+ * `TenantManagerProvider`) pre-installed, real Postgres reset, schemas
+ * applied, optional migrations run, and the per-test providers wired
+ * on top. Returns the started `app`, the admin-level `setupDb` (kept
+ * open until `dispose()`), and the `dispose()` cleanup that pairs with
+ * `afterAll`.
+ *
+ * Replaces the ~50 LOC `beforeAll` boilerplate that every integration
+ * / e2e suite was rolling by hand. Per-test variation (custom config
+ * sub-trees, schemas, migrations, post-boot `useDriver` hand-wiring,
+ * HTTP server spin-up) lives where it always did.
+ *
+ * ```ts
+ * import { afterAll, beforeAll, describe } from 'bun:test'
+ * import {
+ *   bootTestApp,
+ *   isPostgresAvailable,
+ *   type BootTestAppResult,
+ * } from '@strav/testing'
+ * import { RagProvider, ragVectorSchema, applyRagVectorMigration } from '@strav/rag'
+ *
+ * const PG = await isPostgresAvailable()
+ *
+ * describe.skipIf(!PG)('M5 e2e', () => {
+ *   let booted: BootTestAppResult
+ *   beforeAll(async () => {
+ *     booted = await bootTestApp({
+ *       config: { rag: { ... } },
+ *       schemas: [tenantSchema, articleSchema, ragVectorSchema],
+ *       migrations: [(db, registry) => applyRagVectorMigration(db, { dimension: 4, registry })],
+ *       providers: [new StubBrainProvider(), new RagProvider()],
+ *     })
+ *   })
+ *   afterAll(() => booted.dispose())
+ *
+ *   // test cases pull from `booted.app.resolve(...)` and `booted.setupDb`.
+ * })
+ * ```
+ *
+ * The orchestration order, per spec from the e2e survey:
+ *
+ *   1. `createTestDatabase()` → admin connection for setup.
+ *   2. `resetSchema(setupDb)` → DROP + CREATE `public`.
+ *   3. Apply each schema's `emitCreateTable(schema, { registry }).sql`.
+ *   4. Run each migration with `(setupDb, registry)`.
+ *   5. Construct config via `composeTestConfig(config)` (auto-supplies
+ *      logger + database.url unless overridden).
+ *   6. `new Application()`, `useProviders([Config, Logger, Database,
+ *      TenantManager, ...userProviders])` unless `skipDefaultProviders`.
+ *   7. Bind `SchemaRegistry` as a singleton with `schemas` registered.
+ *   8. `await app.start({ signalHandlers: false })`.
+ */
+
+import {
+  DatabaseProvider,
+  PostgresDatabase,
+  type Schema,
+  SchemaRegistry,
+  emitCreateTable,
+} from '@strav/database'
+import {
+  Application,
+  ConfigProvider,
+  LoggerProvider,
+  type ServiceProvider,
+} from '@strav/kernel'
+import { type ConfigOverrides, composeTestConfig } from './compose_test_config.ts'
+import { createTestDatabase } from './postgres/create_test_database.ts'
+import { resetSchema } from './postgres/reset_schema.ts'
+import { TenantManagerProvider } from './tenant_manager_provider.ts'
+
+/** Migration hook signature — runs against `setupDb` before `app.start`. */
+export type TestMigration = (
+  db: PostgresDatabase,
+  registry: SchemaRegistry,
+) => Promise<void> | void
+
+export interface BootTestAppOptions {
+  /**
+   * Per-test config sub-trees. `logger` and `database` keys are
+   * auto-supplied unless overridden here. Other keys (`rag`, `payment`,
+   * `social`, `encryption`, …) are passed through verbatim.
+   */
+  config?: ConfigOverrides
+  /**
+   * Schemas registered in the `SchemaRegistry` singleton AND applied
+   * via `emitCreateTable(schema, { registry }).sql` against `setupDb`
+   * before `app.start`. Order matters when there are FK dependencies.
+   */
+  schemas?: readonly Schema[]
+  /**
+   * Migrations to run after `schemas` are applied. Each receives the
+   * admin connection + the registry so it can compose SQL the same way
+   * the production migration helpers do.
+   */
+  migrations?: readonly TestMigration[]
+  /**
+   * Per-test service providers — appended after the standard four
+   * (`Config`, `Logger`, `Database`, `TenantManager`). Order within
+   * this list matters for the kernel's topological sort.
+   */
+  providers?: readonly ServiceProvider[]
+  /**
+   * Opt out of the standard four. Useful for tests that need a custom
+   * `LoggerProvider`, no `DatabaseProvider`, etc. When `true`, you own
+   * the entire provider list via `providers`. Default `false`.
+   */
+  skipDefaultProviders?: boolean
+}
+
+export interface BootTestAppResult {
+  /** Started Application — call `resolve(X)` from test cases. */
+  app: Application
+  /**
+   * Admin-level Postgres connection used to apply DDL + migrations and
+   * to run setup queries (seeding tenants, asserting schema state). Kept
+   * open until `dispose()`.
+   */
+  setupDb: PostgresDatabase
+  /** Cleanup: shutdown app + close setupDb. Use in `afterAll`. */
+  dispose(): Promise<void>
+}
+
+export async function bootTestApp(options: BootTestAppOptions = {}): Promise<BootTestAppResult> {
+  const setupDb = createTestDatabase()
+  await resetSchema(setupDb)
+
+  const schemas = options.schemas ?? []
+  const registry = new SchemaRegistry().registerAll(schemas)
+
+  for (const schema of schemas) {
+    await setupDb.execute(emitCreateTable(schema, { registry }).sql)
+  }
+
+  for (const migration of options.migrations ?? []) {
+    await migration(setupDb, registry)
+  }
+
+  const configData = composeTestConfig(options.config ?? {})
+
+  const app = new Application()
+  const defaults = options.skipDefaultProviders
+    ? []
+    : [
+        new ConfigProvider(configData),
+        new LoggerProvider(),
+        new DatabaseProvider(),
+        new TenantManagerProvider(),
+      ]
+  app.useProviders([...defaults, ...(options.providers ?? [])])
+
+  // Bind the SchemaRegistry singleton so repositories that need it can
+  // resolve through the container instead of getting hand-wired.
+  app.singleton(SchemaRegistry, () => registry)
+
+  await app.start({ signalHandlers: false })
+
+  let disposed = false
+  const dispose = async (): Promise<void> => {
+    if (disposed) return
+    disposed = true
+    await app.shutdown()
+    await setupDb.close({ timeout: 2 })
+  }
+
+  return { app, setupDb, dispose }
+}

package/src/brain/index.ts

@@ -0,0 +1 @@
+export { stubBrainProvider, type StubBrainOptions } from './stub_brain_provider.ts'

package/src/brain/stub_brain_provider.ts

@@ -0,0 +1,72 @@
+/**
+ * Stub `BrainManager` wired as a `ServiceProvider` for tests that need
+ * deterministic embeddings without dialing an actual brain backend.
+ *
+ * Extracted from `tests/e2e/m5-rag/`. The provider declares
+ * `name: 'brain'` and `dependencies: ['config']`, matching the real
+ * `BrainProvider`'s shape — `RagProvider` (which declares
+ * `dependencies: ['config', 'brain']`) resolves the stub correctly
+ * when both are in the provider list.
+ *
+ * ```ts
+ * import { stubBrainProvider } from '@strav/testing/brain'
+ *
+ * const provider = stubBrainProvider({
+ *   embed: (text) => bagOfWords(text), // returns number[]
+ * })
+ *
+ * app.useProviders([
+ *   new ConfigProvider({ ... }),
+ *   new LoggerProvider(),
+ *   new DatabaseProvider(),
+ *   provider,             // ← stub registered here
+ *   new RagProvider(),    // ← resolves the stub for its embed calls
+ * ])
+ * ```
+ *
+ * The `embed` callback is per-text — the helper maps over the input
+ * array internally. Only `embed` is stubbed; other `BrainManager`
+ * surface (`chat`, `stream`, `runWithTools`, …) throws when called.
+ * V1 scope is rag-style tests; broader stubs land when a second
+ * use case appears.
+ */
+
+import { BrainManager } from '@strav/brain'
+import { type Application, ServiceProvider } from '@strav/kernel'
+
+export interface StubBrainOptions {
+  /**
+   * Returns the embedding vector for a single text. The provider maps
+   * the user's `embed` over `texts` internally to produce `number[][]`.
+   */
+  embed: (text: string) => number[]
+  /** Model identifier surfaced on `embed` results. Default `'stub'`. */
+  model?: string
+}
+
+export function stubBrainProvider(options: StubBrainOptions): ServiceProvider {
+  const model = options.model ?? 'stub'
+  const userEmbed = options.embed
+  return new (class StubBrainProvider extends ServiceProvider {
+    override readonly name = 'brain'
+    override readonly dependencies = ['config']
+    override register(app: Application): void {
+      app.singleton(BrainManager, () => buildStub(userEmbed, model))
+    }
+  })()
+}
+
+function buildStub(
+  embed: (text: string) => number[],
+  model: string,
+): BrainManager {
+  const stub = {
+    embed: async (texts: readonly string[]) => ({
+      embeddings: texts.map(embed),
+      model,
+      usage: { inputTokens: 0 },
+      raw: null,
+    }),
+  }
+  return stub as unknown as BrainManager
+}

package/src/cache/index.ts

@@ -0,0 +1,2 @@
+export { isMemcachedAvailable } from './is_memcached_available.ts'
+export { isRedisAvailable } from './is_redis_available.ts'

package/src/cache/is_memcached_available.ts

@@ -0,0 +1,75 @@
+/**
+ * Cheap connection probe over Bun's TCP socket — opens a connection,
+ * sends `version\r\n`, expects a `VERSION ...\r\n` reply. Cached for
+ * the lifetime of the test process.
+ *
+ * Returns `false` if `MEMCACHED_HOST` / `MEMCACHED_PORT` are missing
+ * OR the probe fails. Pair with
+ * `describe.skipIf(!await isMemcachedAvailable())`.
+ */
+
+let cachedAvailability: boolean | null = null
+
+export async function isMemcachedAvailable(): Promise<boolean> {
+  if (cachedAvailability !== null) return cachedAvailability
+  const host = process.env['MEMCACHED_HOST']
+  const portStr = process.env['MEMCACHED_PORT']
+  if (host === undefined || host === '' || portStr === undefined || portStr === '') {
+    cachedAvailability = false
+    return false
+  }
+  const port = Number(portStr)
+  if (!Number.isFinite(port) || port <= 0) {
+    cachedAvailability = false
+    return false
+  }
+  try {
+    cachedAvailability = await probe(host, port)
+  } catch {
+    cachedAvailability = false
+  }
+  return cachedAvailability
+}
+
+function probe(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (ok: boolean): void => {
+      if (settled) return
+      settled = true
+      resolve(ok)
+    }
+    const timeout = setTimeout(() => finish(false), 2_000)
+    void Bun.connect({
+      hostname: host,
+      port,
+      socket: {
+        open(socket) {
+          socket.write('version\r\n')
+        },
+        data(socket, chunk) {
+          const bytes = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+          const text = new TextDecoder().decode(bytes)
+          const ok = text.startsWith('VERSION')
+          // Settle before closing — `socket.end()` synchronously fires
+          // the `close` callback, which would beat `finish(ok)` to the
+          // settle line and report a false negative.
+          clearTimeout(timeout)
+          finish(ok)
+          socket.end()
+        },
+        error(_socket, _error) {
+          clearTimeout(timeout)
+          finish(false)
+        },
+        close() {
+          clearTimeout(timeout)
+          if (!settled) finish(false)
+        },
+      },
+    }).catch(() => {
+      clearTimeout(timeout)
+      finish(false)
+    })
+  })
+}

package/src/cache/is_redis_available.ts

@@ -0,0 +1,39 @@
+/**
+ * Cheap connection probe — opens `Bun.RedisClient` against
+ * `REDIS_URL`, sends `PING`, reports. Cached for the lifetime of the
+ * test process.
+ *
+ * Returns `false` if `REDIS_URL` is missing OR the connection / PING
+ * fails. Pair with `describe.skipIf(!await isRedisAvailable())`.
+ */
+
+import { RedisClient } from 'bun'
+
+let cachedAvailability: boolean | null = null
+
+export async function isRedisAvailable(): Promise<boolean> {
+  if (cachedAvailability !== null) return cachedAvailability
+  const url = process.env['REDIS_URL']
+  if (url === undefined || url === '') {
+    cachedAvailability = false
+    return false
+  }
+  let client: RedisClient | undefined
+  try {
+    client = new RedisClient(url)
+    // `send('PING', [])` is supported on every Bun.RedisClient build —
+    // safer than `ping()` which isn't on the typed surface.
+    const reply = await client.send('PING', [])
+    cachedAvailability = reply === 'PONG' || reply === 'OK' || typeof reply === 'string'
+    return cachedAvailability
+  } catch {
+    cachedAvailability = false
+    return false
+  } finally {
+    try {
+      client?.close()
+    } catch {
+      // Already closed / never connected — nothing to clean.
+    }
+  }
+}

package/src/compose_test_config.ts

@@ -0,0 +1,47 @@
+/**
+ * Merge per-test config overrides with the standard test defaults.
+ *
+ * Defaults supplied:
+ *
+ *   - `logger`: silent + stderr channel — keeps `bun test` output clean.
+ *   - `database.url`: composed from `DB_*` env vars via `testDatabaseUrl()`.
+ *
+ * Both are deep-merged with `overrides`. Pass `logger` or `database` in
+ * `overrides` to replace the default for that key. Other keys
+ * (`rag`, `payment`, `social`, `encryption`, etc.) are taken verbatim
+ * from `overrides`.
+ *
+ * Throws when `DB_*` env vars are missing AND no `database.url` override
+ * is supplied — `bootTestApp` callers gate via `isPostgresAvailable()`
+ * first, so the throw should only fire in misconfigured environments.
+ */
+
+import { testDatabaseUrl } from './postgres/test_database_url.ts'
+
+export type ConfigOverrides = Record<string, unknown>
+
+const DEFAULT_LOGGER = {
+  default: 'main',
+  level: 'silent',
+  channels: { main: { driver: 'stderr' } },
+} as const
+
+export function composeTestConfig(overrides: ConfigOverrides = {}): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...overrides }
+
+  if (!('logger' in merged)) {
+    merged.logger = { ...DEFAULT_LOGGER }
+  }
+
+  if (!('database' in merged)) {
+    const url = testDatabaseUrl()
+    if (url === null) {
+      throw new Error(
+        'composeTestConfig: missing DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_DATABASE env. Source .env.test, run docker-compose up, or pass `database` explicitly in overrides.',
+      )
+    }
+    merged.database = { url }
+  }
+
+  return merged
+}

package/src/index.ts

@@ -1,17 +1,33 @@
-export { TestCase } from './test_case.ts'
-export type { TestCaseOptions } from './test_case.ts'
-export { Factory } from './factory.ts'
+// Public API of @strav/testing.
+//
+// V1 ships the small utilities that get re-implemented inline in every
+// test: an in-memory writable stream, a typed fetch stub, and the
+// Postgres availability + reset helpers used by integration suites.
+// V2 (this slice) adds bootTestApp + composeTestConfig +
+// TenantManagerProvider for the e2e boot-dance.
 
-// Database management
-export { TestDatabaseManager, cleanupTestDatabase } from './database_manager.ts'
+export {
+  bootTestApp,
+  type BootTestAppOptions,
+  type BootTestAppResult,
+  type TestMigration,
+} from './boot_test_app.ts'
+export { composeTestConfig, type ConfigOverrides } from './compose_test_config.ts'
+export { MemStream } from './mem_stream.ts'
+export { stubFetch, type FetchHandler } from './stub_fetch.ts'
+export { TenantManagerProvider } from './tenant_manager_provider.ts'
 
-// Browser-driven testing (Playwright). Lazy-loads playwright-core only when
-// BrowserTestCase / DemoFlow are actually instantiated.
-export { BrowserTestCase, DemoFlow, runFresh } from './browser/index.ts'
-export type {
-  BrowserTestCaseOptions,
-  BrowserName,
-  MailMode,
-  DemoFlowOptions,
-  ServerHandle,
-} from './browser/index.ts'
+// Postgres helpers — also re-exported under `@strav/testing/postgres`
+// for apps that want to import them without pulling in the rest of
+// the barrel.
+export {
+  connectedRoleBypassesRls,
+  createTestDatabase,
+  isPostgresAvailable,
+  resetSchema,
+  testDatabaseUrl,
+} from './postgres/index.ts'
+
+// Cache availability probes — also re-exported under
+// `@strav/testing/cache` for the same reason.
+export { isMemcachedAvailable, isRedisAvailable } from './cache/index.ts'