@strav/testing 0.4.31 → 1.0.0-alpha.25

package/src/mem_stream.ts

@@ -0,0 +1,50 @@
+/**
+ * In-memory `WritableStream` for tests that assert on stdout/stderr.
+ *
+ * Pairs with `@strav/kernel`'s `ConsoleOutput` and `@strav/cli`'s
+ * command/`runCli` flows — both accept a `NodeJS.WritableStream`
+ * pair, and `MemStream` is the smallest possible double that lets
+ * tests inspect what was written.
+ *
+ * ```ts
+ * import { MemStream } from '@strav/testing'
+ * import { ConsoleOutput } from '@strav/kernel'
+ *
+ * const stdout = new MemStream()
+ * const out = new ConsoleOutput({ stdout: stdout.asWritable(), useColor: false })
+ * out.line('hello')
+ * expect(stdout.text()).toBe('hello\n')
+ * ```
+ *
+ * `asWritable()` exists so callers don't need the `as unknown as
+ * NodeJS.WritableStream` cast at every test site — the cast is
+ * confined to this module's boundary.
+ */
+
+export class MemStream {
+  readonly chunks: string[] = []
+
+  write(chunk: string): boolean {
+    this.chunks.push(chunk)
+    return true
+  }
+
+  /** Concatenated written content. */
+  text(): string {
+    return this.chunks.join('')
+  }
+
+  /** Drop everything written so far. Useful between assertions in a single test. */
+  clear(): void {
+    this.chunks.length = 0
+  }
+
+  /**
+   * Cast to `NodeJS.WritableStream` for APIs that demand the full
+   * Node interface (`ConsoleOutput`, child-process stdio, etc.).
+   * Confines the boundary cast to this method.
+   */
+  asWritable(): NodeJS.WritableStream {
+    return this as unknown as NodeJS.WritableStream
+  }
+}

package/src/postgres/connected_role_bypasses_rls.ts

@@ -0,0 +1,22 @@
+/**
+ * `true` when the connected role is a Postgres SUPERUSER or has the
+ * BYPASSRLS attribute. Such roles ignore `ENABLE ROW LEVEL SECURITY` —
+ * even with `FORCE ROW LEVEL SECURITY` set on a table — so
+ * RLS-isolation assertions can't pass under them. Tests use this to
+ * self-skip the RLS-scoping check while still exercising the rest of
+ * the tenancy path.
+ *
+ * Production setups should run the app under a non-privileged role and
+ * keep BYPASSRLS reserved for the admin pool (`TenantManager`'s
+ * `adminDb`). Local-dev / CI databases often share one superuser for
+ * convenience — this helper lets the suite degrade gracefully there.
+ */
+
+import type { PostgresDatabase } from '@strav/database'
+
+export async function connectedRoleBypassesRls(db: PostgresDatabase): Promise<boolean> {
+  const row = await db.queryOne<{ rolsuper: boolean; rolbypassrls: boolean }>(
+    `SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`,
+  )
+  return Boolean(row?.rolsuper) || Boolean(row?.rolbypassrls)
+}

package/src/postgres/create_test_database.ts

@@ -0,0 +1,20 @@
+/**
+ * Construct a fresh `PostgresDatabase` against the test connection. The
+ * caller owns the close — typically in an `afterAll` hook.
+ *
+ * Throws when env is missing; tests that don't want the throw should
+ * gate via `isPostgresAvailable()` first.
+ */
+
+import { PostgresDatabase } from '@strav/database'
+import { testDatabaseUrl } from './test_database_url.ts'
+
+export function createTestDatabase(): PostgresDatabase {
+  const url = testDatabaseUrl()
+  if (url === null) {
+    throw new Error(
+      'createTestDatabase: missing DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_DATABASE env. Source .env.test or run docker-compose up.',
+    )
+  }
+  return new PostgresDatabase({ url, max: 2 })
+}

package/src/postgres/index.ts

@@ -0,0 +1,5 @@
+export { connectedRoleBypassesRls } from './connected_role_bypasses_rls.ts'
+export { createTestDatabase } from './create_test_database.ts'
+export { isPostgresAvailable } from './is_postgres_available.ts'
+export { resetSchema } from './reset_schema.ts'
+export { testDatabaseUrl } from './test_database_url.ts'

package/src/postgres/is_postgres_available.ts

@@ -0,0 +1,33 @@
+/**
+ * Cheap connection probe with a short timeout. Cached for the lifetime
+ * of the test process — connection state doesn't flip mid-suite.
+ *
+ * Returns `false` if env is missing OR the connection attempt fails
+ * (Postgres down, wrong creds, network unreachable). Pair with
+ * `describe.skipIf(!await isPostgresAvailable())` so suites that need
+ * a real Postgres self-skip when it's not reachable.
+ */
+
+import { PostgresDatabase } from '@strav/database'
+import { testDatabaseUrl } from './test_database_url.ts'
+
+let cachedAvailability: boolean | null = null
+
+export async function isPostgresAvailable(): Promise<boolean> {
+  if (cachedAvailability !== null) return cachedAvailability
+  const url = testDatabaseUrl()
+  if (url === null) {
+    cachedAvailability = false
+    return false
+  }
+  try {
+    const probe = new PostgresDatabase({ url, max: 1 })
+    await probe.queryOne('SELECT 1 AS ok')
+    await probe.close({ timeout: 1 })
+    cachedAvailability = true
+    return true
+  } catch {
+    cachedAvailability = false
+    return false
+  }
+}

package/src/postgres/reset_schema.ts

@@ -0,0 +1,14 @@
+/**
+ * Drop + recreate the `public` schema on the connected database.
+ * Bulletproof isolation between integration test runs at the cost of
+ * a sledgehammer — the integration test database owns its state and
+ * shouldn't be pointed at anything precious.
+ */
+
+import type { PostgresDatabase } from '@strav/database'
+
+export async function resetSchema(db: PostgresDatabase): Promise<void> {
+  await db.execute('DROP SCHEMA IF EXISTS public CASCADE')
+  await db.execute('CREATE SCHEMA public')
+  await db.execute('GRANT ALL ON SCHEMA public TO public')
+}

package/src/postgres/test_database_url.ts

@@ -0,0 +1,33 @@
+/**
+ * Reads the standard env-var contract (`DB_HOST` / `DB_PORT` / `DB_USER` /
+ * `DB_PASSWORD` / `DB_DATABASE`) shared with CI and `.env.test` and
+ * assembles a Postgres URL. Returns `null` when any required variable
+ * is missing — callers self-skip rather than throw, so `bun test` is a
+ * no-op for integration tests in environments without local Postgres.
+ */
+
+interface PgEnv {
+  host: string
+  port: string
+  user: string
+  password: string
+  database: string
+}
+
+function readPgEnv(): PgEnv | null {
+  const host = process.env.DB_HOST
+  const port = process.env.DB_PORT
+  const user = process.env.DB_USER
+  const password = process.env.DB_PASSWORD
+  const database = process.env.DB_DATABASE
+  if (!host || !port || !user || !password || !database) return null
+  return { host, port, user, password, database }
+}
+
+export function testDatabaseUrl(): string | null {
+  const env = readPgEnv()
+  if (env === null) return null
+  // `encodeURIComponent` so a password containing `@` or `:` doesn't
+  // corrupt the URL.
+  return `postgres://${env.user}:${encodeURIComponent(env.password)}@${env.host}:${env.port}/${env.database}`
+}

package/src/stub_fetch.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed `fetch` stub for driver tests that need to assert on outgoing
+ * HTTP without a network round-trip.
+ *
+ * Adapters that take a `fetch` injection point (e.g. `LineSocialDriver`,
+ * pure-fetch brain drivers) typically end up with `as unknown as typeof
+ * fetch` boilerplate in tests because the standard `fetch` signature
+ * (with `preconnect`, etc.) doesn't match a plain async function.
+ * `stubFetch` confines that cast to one place.
+ *
+ * ```ts
+ * import { stubFetch } from '@strav/testing'
+ *
+ * const captured: Request[] = []
+ * const driver = new LineSocialDriver({
+ *   config: { ... },
+ *   fetch: stubFetch(async (req) => {
+ *     captured.push(req)
+ *     if (req.url.includes('/token')) {
+ *       return Response.json({ access_token: 'AT_1', expires_in: 3600 })
+ *     }
+ *     return new Response('not found', { status: 404 })
+ *   }),
+ * })
+ * ```
+ *
+ * The handler receives a `Request` regardless of how the caller invoked
+ * `fetch` (URL + init, URL string, existing Request). Normalization
+ * happens here so the handler doesn't have to branch on input shape.
+ */
+
+export type FetchHandler = (request: Request) => Response | Promise<Response>
+
+export function stubFetch(handler: FetchHandler): typeof fetch {
+  const fn = async (
+    input: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ): Promise<Response> => {
+    const request = normalizeToRequest(input, init)
+    return handler(request)
+  }
+  return fn as unknown as typeof fetch
+}
+
+function normalizeToRequest(
+  input: Parameters<typeof fetch>[0],
+  init: Parameters<typeof fetch>[1],
+): Request {
+  if (input instanceof Request) {
+    // If `init` is provided, the spec says we layer it on; new Request
+    // accepts (Request, RequestInit) and merges accordingly.
+    return init === undefined ? input : new Request(input, init)
+  }
+  // string | URL → construct a Request. URL converts via its toString.
+  return new Request(typeof input === 'string' ? input : input.toString(), init)
+}

package/src/tenant_manager_provider.ts

@@ -0,0 +1,40 @@
+/**
+ * Standard `TenantManager` wiring for tests.
+ *
+ * `DatabaseProvider` doesn't auto-register `TenantManager` — apps wire
+ * it themselves so the binding is explicit (and so apps that don't use
+ * tenancy don't pay for it). Every integration / e2e suite that uses
+ * `TenantManager` defined an identical 3-line `ServiceProvider` to do
+ * the wiring; this is the extracted version.
+ *
+ * ```ts
+ * import { TenantManagerProvider } from '@strav/testing'
+ *
+ * app.useProviders([
+ *   new ConfigProvider({ ... }),
+ *   new LoggerProvider(),
+ *   new DatabaseProvider(),
+ *   new TenantManagerProvider(),
+ *   // your provider here
+ * ])
+ * ```
+ *
+ * The class implements the same shape every e2e was rolling by hand:
+ * declares `database` as a dependency, binds `TenantManager` as a
+ * singleton built from the resolved `PostgresDatabase` + `EventBus`.
+ */
+
+import { PostgresDatabase, TenantManager } from '@strav/database'
+import { type Application, EventBus, ServiceProvider } from '@strav/kernel'
+
+export class TenantManagerProvider extends ServiceProvider {
+  override readonly name = 'tenant'
+  override readonly dependencies = ['database']
+
+  override register(app: Application): void {
+    app.singleton(
+      TenantManager,
+      (c) => new TenantManager(c.resolve(PostgresDatabase), c.resolve(EventBus)),
+    )
+  }
+}

package/CHANGELOG.md

@@ -1,7 +0,0 @@
-# Changelog
-
-## 0.1.1
-
-### Changed
-
-- Applied consistent code formatting across all source files

package/src/browser/db_fresh.ts

@@ -1,38 +0,0 @@
-/**
- * Programmatic equivalent of `bun strav fresh`. Refuses to run unless the
- * caller has set APP_ENV to 'test' or 'local' — the CLI command requires
- * 'local'; we additionally accept 'test' so test runners don't need a flag
- * dance. Lazy-imports `@strav/cli` so packages that don't use BrowserTestCase
- * don't pay the dependency cost.
- */
-export async function runFresh(): Promise<void> {
-  const env = process.env.APP_ENV
-  if (env !== 'test' && env !== 'local') {
-    throw new Error(
-      `runFresh refused: APP_ENV must be 'test' or 'local' (got '${env ?? '<unset>'}'). ` +
-        `This is a safety guard — fresh wipes all tables.`
-    )
-  }
-
-  let freshDatabase: typeof import('@strav/cli/commands/migration_fresh').freshDatabase
-  let bootstrap: typeof import('@strav/cli/cli/bootstrap').bootstrap
-  let shutdown: typeof import('@strav/cli/cli/bootstrap').shutdown
-  let getDatabasePaths: typeof import('@strav/cli/config/loader').getDatabasePaths
-  try {
-    ;({ freshDatabase } = await import('@strav/cli/commands/migration_fresh'))
-    ;({ bootstrap, shutdown } = await import('@strav/cli/cli/bootstrap'))
-    ;({ getDatabasePaths } = await import('@strav/cli/config/loader'))
-  } catch (err) {
-    throw new Error(
-      `runFresh requires @strav/cli to be installed in this workspace. Add it as a peer dependency. (${(err as Error).message})`
-    )
-  }
-
-  const paths = await getDatabasePaths()
-  const { db, registry, introspector } = await bootstrap()
-  try {
-    await freshDatabase(db, registry, introspector, paths.migrations)
-  } finally {
-    await shutdown(db)
-  }
-}

package/src/browser/demo_flow.ts

@@ -1,89 +0,0 @@
-import type { Page } from 'playwright-core'
-import { BrowserTestCase } from './test_case.ts'
-import type { BrowserTestCaseOptions } from './test_case.ts'
-
-export interface DemoFlowOptions extends BrowserTestCaseOptions {
-  /** Default: '/auth/magic' — the conventional magic-link endpoint. */
-  signInEndpoint?: string
-}
-
-/**
- * Opinionated wrapper around {@link BrowserTestCase} that ships the AGON
- * "demo flow" surface: magic-link sign-in via captured mail, fixture
- * composition for slice-by-slice extension, and stricter defaults
- * (`fresh: true`, `mail: 'capture'`).
- *
- * Apps doing general browser testing should reach for `BrowserTestCase`
- * directly; `DemoFlow` exists for the AGON slice-DoD use case.
- */
-export class DemoFlow {
-  readonly tc: BrowserTestCase
-  private readonly signInEndpoint: string
-
-  constructor(tc: BrowserTestCase, options: DemoFlowOptions = {}) {
-    this.tc = tc
-    this.signInEndpoint = options.signInEndpoint ?? '/auth/magic'
-  }
-
-  /** Boot a DemoFlow — defaults `fresh: true`, `mail: 'capture'`. */
-  static async boot(options: DemoFlowOptions = {}): Promise<DemoFlow> {
-    const tc = await BrowserTestCase.boot({
-      fresh: options.fresh ?? true,
-      mail: options.mail ?? 'capture',
-      ...options,
-    })
-    return new DemoFlow(tc, options)
-  }
-
-  /**
-   * Build a fixture function that returns a fresh DemoFlow with `setup`
-   * applied. Fixture flows compose: `withWorkspace` can call
-   * `signedInUser()` and extend it.
-   */
-  static fixture<T extends DemoFlow>(setup: (flow: DemoFlow) => Promise<T>): () => Promise<T> {
-    return async () => {
-      const flow = await DemoFlow.boot()
-      return await setup(flow)
-    }
-  }
-
-  // Direct passthrough to the Playwright page for escape hatches.
-  get page(): Page { return this.tc.page }
-
-  // ---------------------------------------------------------------------------
-  // Delegated DSL
-  // ---------------------------------------------------------------------------
-
-  goto(path: string): Promise<void> { return this.tc.goto(path) }
-  click(selector: string): Promise<void> { return this.tc.click(selector) }
-  fill(selector: string, value: string): Promise<void> { return this.tc.fill(selector, value) }
-  expectUrl(url: string | RegExp): Promise<void> { return this.tc.expectUrl(url) }
-  expectVisible(selector: string, text?: string | RegExp): Promise<void> { return this.tc.expectVisible(selector, text) }
-  expectComputedStyle(
-    selector: string,
-    property: string,
-    matcher: Parameters<BrowserTestCase['expectComputedStyle']>[2],
-  ): Promise<void> {
-    return this.tc.expectComputedStyle(selector, property, matcher)
-  }
-
-  // ---------------------------------------------------------------------------
-  // Auth
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Sign in via the captured magic-link flow. Posts to the configured
-   * endpoint, waits for the captured email, follows the link.
-   */
-  signIn(opts: { email: string; endpoint?: string; subject?: string | RegExp; tokenParam?: string }): Promise<void> {
-    return this.tc.signInWithMagicLink({
-      email: opts.email,
-      endpoint: opts.endpoint ?? this.signInEndpoint,
-      subject: opts.subject,
-      tokenParam: opts.tokenParam,
-    })
-  }
-
-  /** Skip the email loop — mint a session directly for `user`. */
-  signInAs(user: unknown): Promise<void> { return this.tc.signInAs(user) }
-}

package/src/browser/index.ts

@@ -1,11 +0,0 @@
-export { BrowserTestCase } from './test_case.ts'
-export type {
-  BrowserTestCaseOptions,
-  BrowserName,
-  MailMode,
-} from './test_case.ts'
-export { DemoFlow } from './demo_flow.ts'
-export type { DemoFlowOptions } from './demo_flow.ts'
-export { runFresh } from './db_fresh.ts'
-export { startListener, stopListener } from './server_lifecycle.ts'
-export type { ServerHandle } from './server_lifecycle.ts'

package/src/browser/server_lifecycle.ts

@@ -1,42 +0,0 @@
-import { app, Configuration } from '@strav/kernel'
-import { Router, Server } from '@strav/http'
-
-export interface ServerHandle {
-  server: Server
-  router: Router
-  baseUrl: string
-  port: number
-  hostname: string
-}
-
-/**
- * Bind a Bun.serve listener for a router that has already had its routes
- * registered. Forces an ephemeral port (port=0) unless the caller specifies
- * one. The caller owns the lifecycle: call {@link stopListener} to tear down.
- */
-export function startListener(router: Router, options: { port?: number; hostname?: string } = {}): ServerHandle {
-  const config = app.resolve(Configuration)
-  const requestedPort = options.port ?? 0
-  const requestedHost = options.hostname ?? '127.0.0.1'
-
-  // Override config so Server.start() picks up our port/host without the
-  // caller having to mutate their config files.
-  config.set('http.port', requestedPort)
-  config.set('http.host', requestedHost)
-
-  if (!app.has(Server)) app.singleton(Server)
-  const server = app.resolve(Server)
-  server.start(router)
-
-  return {
-    server,
-    router,
-    port: server.port,
-    hostname: server.hostname,
-    baseUrl: `http://${server.hostname}:${server.port}`,
-  }
-}
-
-export function stopListener(handle: ServerHandle): void {
-  handle.server.stop()
-}