@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/src/testing/index.ts

@@ -2,251 +2,354 @@ import { spawn, type ChildProcess } from 'node:child_process';
 import { once } from 'node:events';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import net from 'node:net';
 import path from 'node:path';
 
 import type { ModuleManifest } from '@webstir-io/module-contract';
 
 import { getBackendTestContext, setBackendTestContext } from './context.js';
+import { resolveWorkspaceRoot } from '../workspace.js';
 import type {
-    BackendTestCallback,
-    BackendTestContext,
-    BackendTestHarness,
-    BackendTestHarnessOptions
+  BackendTestCallback,
+  BackendTestContext,
+  BackendTestHarness,
+  BackendTestHarnessOptions,
 } from './types.js';
 
 const DEFAULT_PORT = 4100;
 const DEFAULT_READY_TEXT = 'API server running';
 const DEFAULT_READY_TIMEOUT_MS = 15_000;
 
-export type { BackendTestCallback, BackendTestContext, BackendTestHarness, BackendTestHarnessOptions } from './types.js';
+export type {
+  BackendTestCallback,
+  BackendTestContext,
+  BackendTestHarness,
+  BackendTestHarnessOptions,
+} from './types.js';
 export { getBackendTestContext, setBackendTestContext };
 
-export async function createBackendTestHarness(options: BackendTestHarnessOptions = {}): Promise<BackendTestHarness> {
-    const workspaceRoot = options.workspaceRoot ?? process.env.WEBSTIR_WORKSPACE_ROOT ?? process.cwd();
-    const buildRoot = options.buildRoot ?? process.env.WEBSTIR_BACKEND_BUILD_ROOT ?? path.join(workspaceRoot, 'build', 'backend');
-    const entry = options.entry ?? process.env.WEBSTIR_BACKEND_TEST_ENTRY ?? path.join(buildRoot, 'index.js');
-    const manifestPath =
-        options.manifestPath ??
-        process.env.WEBSTIR_BACKEND_TEST_MANIFEST ??
-        path.join(workspaceRoot, '.webstir', 'backend-manifest.json');
-    const readyText = options.readyText ?? process.env.WEBSTIR_BACKEND_TEST_READY ?? DEFAULT_READY_TEXT;
-    const readyTimeoutMs =
-        options.readyTimeoutMs ?? readInt(process.env.WEBSTIR_BACKEND_TEST_READY_TIMEOUT, DEFAULT_READY_TIMEOUT_MS);
-
-    if (!existsSync(entry)) {
-        throw new Error(
-            `Backend test entry not found at ${entry}. Run the backend build before executing backend tests.`
-        );
-    }
+export async function createBackendTestHarness(
+  options: BackendTestHarnessOptions = {},
+): Promise<BackendTestHarness> {
+  const resolvedEnv = { ...process.env, ...(options.env ?? {}) };
+  const workspaceRoot = resolveWorkspaceRoot({
+    workspaceRoot: options.workspaceRoot,
+    env: resolvedEnv,
+  });
+  const buildRoot = resolveWorkspacePath(
+    workspaceRoot,
+    options.buildRoot ??
+      resolvedEnv.WEBSTIR_BACKEND_BUILD_ROOT ??
+      path.join(workspaceRoot, 'build', 'backend'),
+  );
+  const entry = resolveWorkspacePath(
+    workspaceRoot,
+    options.entry ?? resolvedEnv.WEBSTIR_BACKEND_TEST_ENTRY ?? path.join(buildRoot, 'index.js'),
+  );
+  const manifestPath = resolveWorkspacePath(
+    workspaceRoot,
+    options.manifestPath ??
+      resolvedEnv.WEBSTIR_BACKEND_TEST_MANIFEST ??
+      path.join(workspaceRoot, '.webstir', 'backend-manifest.json'),
+  );
+  const readyText =
+    options.readyText ?? resolvedEnv.WEBSTIR_BACKEND_TEST_READY ?? DEFAULT_READY_TEXT;
+  const readyTimeoutMs =
+    options.readyTimeoutMs ??
+    readInt(resolvedEnv.WEBSTIR_BACKEND_TEST_READY_TIMEOUT, DEFAULT_READY_TIMEOUT_MS);
 
-    const requestedPort = options.port ?? readInt(process.env.WEBSTIR_BACKEND_TEST_PORT, DEFAULT_PORT);
-    const port = await findOpenPort(requestedPort);
-    const env = createRuntimeEnv({
-        workspaceRoot,
-        port,
-        overrides: options.env
-    });
-    const manifest = await loadManifest(manifestPath);
-    const child = spawn(process.execPath, [entry], {
-        cwd: workspaceRoot,
-        env,
-        stdio: ['ignore', 'pipe', 'pipe']
-    });
+  if (!existsSync(entry)) {
+    throw new Error(
+      `Backend test entry not found at ${entry}. Run the backend build before executing backend tests.`,
+    );
+  }
 
-    try {
-        await waitForReady(child, readyText, readyTimeoutMs);
-    } catch (error) {
-        await stopProcess(child);
-        throw error;
-    }
+  const manifest = await loadManifest(manifestPath);
+  const requestedPort =
+    options.port ?? readInt(resolvedEnv.WEBSTIR_BACKEND_TEST_PORT, DEFAULT_PORT);
+  const { child, env, port } = await startBackendTestProcess({
+    workspaceRoot,
+    entry,
+    requestedPort,
+    baseEnv: resolvedEnv,
+    overrides: options.env,
+    readyText,
+    readyTimeoutMs,
+  });
 
-    const baseUrl = new URL(env.API_BASE_URL ?? `http://127.0.0.1:${port}`);
-    const context: BackendTestContext = {
-        baseUrl: baseUrl.toString(),
-        url: baseUrl,
-        port,
-        manifest,
-        routes: Array.isArray(manifest?.routes) ? (manifest.routes as NonNullable<ModuleManifest['routes']>) : [],
-        env,
-        request: async (pathOrUrl = '/', init) => {
-            const target = toUrl(baseUrl, pathOrUrl);
-            return await fetch(target, init);
-        }
-    };
+  const baseUrl = new URL(env.API_BASE_URL ?? `http://127.0.0.1:${port}`);
+  const context: BackendTestContext = {
+    baseUrl: baseUrl.toString(),
+    url: baseUrl,
+    port,
+    manifest,
+    routes: Array.isArray(manifest?.routes)
+      ? (manifest.routes as NonNullable<ModuleManifest['routes']>)
+      : [],
+    env,
+    request: async (pathOrUrl = '/', init) => {
+      const target = toUrl(baseUrl, pathOrUrl);
+      return await fetch(target, init);
+    },
+  };
 
-    return {
-        context,
-        async stop() {
-            await stopProcess(child);
-        }
-    };
+  return {
+    context,
+    async stop() {
+      await stopProcess(child);
+    },
+  };
 }
 
 export function backendTest(name: string, callback: BackendTestCallback): void {
-    const globalTest = (globalThis as { test?: (id: string, fn: () => Promise<void> | void) => void }).test;
-    if (typeof globalTest !== 'function') {
-        throw new Error('backendTest() requires the @webstir-io/webstir-testing runtime.');
-    }
+  const globalTest = (globalThis as { test?: (id: string, fn: () => Promise<void> | void) => void })
+    .test;
+  if (typeof globalTest !== 'function') {
+    throw new Error('backendTest() requires the @webstir-io/webstir-testing runtime.');
+  }
 
-    globalTest(name, async () => {
-        const context = getBackendTestContext();
-        if (!context) {
-            throw new Error(
-                'Backend test context not available. Ensure backend tests run via the Webstir CLI (`webstir test`).'
-            );
-        }
-        await callback(context);
-    });
+  globalTest(name, async () => {
+    const context = getBackendTestContext();
+    if (!context) {
+      throw new Error(
+        'Backend test context not available. Ensure backend tests run via the Webstir CLI (`webstir test`).',
+      );
+    }
+    await callback(context);
+  });
 }
 
 function toUrl(base: URL, pathOrUrl: string | URL): string {
-    if (pathOrUrl instanceof URL) {
-        return pathOrUrl.toString();
-    }
+  if (pathOrUrl instanceof URL) {
+    return pathOrUrl.toString();
+  }
 
-    if (/^https?:/i.test(pathOrUrl)) {
-        return pathOrUrl;
-    }
+  if (/^https?:/i.test(pathOrUrl)) {
+    return pathOrUrl;
+  }
 
-    return new URL(pathOrUrl, base).toString();
+  return new URL(pathOrUrl, base).toString();
 }
 
 function readInt(value: string | undefined, fallback: number): number {
-    if (!value) return fallback;
-    const parsed = Number.parseInt(value, 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
-async function findOpenPort(start: number, attempts = 10): Promise<number> {
-    let candidate = start;
-    for (let index = 0; index < attempts; index += 1) {
-        // eslint-disable-next-line no-await-in-loop
-        if (await isPortAvailable(candidate)) {
-            return candidate;
-        }
-        candidate += 1;
-    }
-    throw new Error(`Unable to find an open port for backend tests (tried starting at ${start}).`);
+interface RuntimeEnvOptions {
+  workspaceRoot: string;
+  port: number;
+  baseEnv: Record<string, string | undefined>;
+  overrides?: Record<string, string | undefined>;
 }
 
-function isPortAvailable(port: number): Promise<boolean> {
-    return new Promise((resolve) => {
-        const server = net.createServer();
-        server.once('error', () => {
-            server.close(() => resolve(false));
-        });
-        server.once('listening', () => {
-            server.close(() => resolve(true));
-        });
-        server.listen(port, '127.0.0.1');
-    });
+interface StartBackendTestProcessOptions {
+  workspaceRoot: string;
+  entry: string;
+  requestedPort: number;
+  baseEnv: Record<string, string | undefined>;
+  overrides?: Record<string, string | undefined>;
+  readyText: string;
+  readyTimeoutMs: number;
 }
 
-interface RuntimeEnvOptions {
-    workspaceRoot: string;
-    port: number;
-    overrides?: Record<string, string | undefined>;
+async function startBackendTestProcess(
+  options: StartBackendTestProcessOptions,
+): Promise<{ child: ChildProcess; env: Record<string, string>; port: number }> {
+  let candidate = options.requestedPort;
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const env = createRuntimeEnv({
+      workspaceRoot: options.workspaceRoot,
+      port: candidate,
+      baseEnv: options.baseEnv,
+      overrides: options.overrides,
+    });
+    const child = spawn(process.execPath, [options.entry], {
+      cwd: options.workspaceRoot,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const output = captureChildOutput(child);
+
+    try {
+      await waitForReady(child, options.readyText, options.readyTimeoutMs);
+      output.stop();
+      return { child, env, port: candidate };
+    } catch (error) {
+      const captured = output.read();
+      output.stop();
+      await stopProcess(child);
+      const message = error instanceof Error ? error.message : String(error);
+      const failure = new Error(
+        `Backend test server did not become ready on port ${candidate}.\nstdout:\n${captured.stdout}\nstderr:\n${captured.stderr}\nerror:\n${message}`,
+      );
+
+      if (attempt < 9 && indicatesPortInUse(captured.stdout, captured.stderr, message)) {
+        lastError = failure;
+        candidate += 1;
+        continue;
+      }
+
+      throw failure;
+    }
+  }
+
+  throw lastError ?? new Error('Backend test server did not become ready.');
 }
 
 function createRuntimeEnv(options: RuntimeEnvOptions): Record<string, string> {
-    const overrides: Record<string, string> = {};
-    for (const [key, value] of Object.entries(options.overrides ?? {})) {
-        if (value !== undefined) {
-            overrides[key] = value;
-        }
+  const overrides: Record<string, string> = {};
+  for (const [key, value] of Object.entries(options.overrides ?? {})) {
+    if (value !== undefined) {
+      overrides[key] = value;
     }
+  }
 
-    const baseUrl = overrides.API_BASE_URL ?? process.env.API_BASE_URL ?? `http://127.0.0.1:${options.port}`;
-    return {
-        ...process.env,
-        ...overrides,
-        PORT: String(options.port),
-        API_BASE_URL: baseUrl,
-        NODE_ENV: overrides.NODE_ENV ?? process.env.NODE_ENV ?? 'test',
-        WORKSPACE_ROOT: options.workspaceRoot,
-        WEBSTIR_BACKEND_TEST_RUN: '1'
-    };
+  const baseUrl =
+    overrides.API_BASE_URL ?? options.baseEnv.API_BASE_URL ?? `http://127.0.0.1:${options.port}`;
+  return {
+    ...options.baseEnv,
+    ...overrides,
+    PORT: String(options.port),
+    API_BASE_URL: baseUrl,
+    NODE_ENV: overrides.NODE_ENV ?? options.baseEnv.NODE_ENV ?? 'test',
+    WORKSPACE_ROOT: options.workspaceRoot,
+    WEBSTIR_BACKEND_TEST_RUN: '1',
+  };
+}
+
+function captureChildOutput(child: ChildProcess): {
+  stop(): void;
+  read(): { stdout: string; stderr: string };
+} {
+  let stdout = '';
+  let stderr = '';
+
+  const onStdout = (chunk: Buffer | string) => {
+    stdout += chunk.toString();
+  };
+  const onStderr = (chunk: Buffer | string) => {
+    stderr += chunk.toString();
+  };
+
+  child.stdout?.on('data', onStdout);
+  child.stderr?.on('data', onStderr);
+
+  return {
+    stop() {
+      child.stdout?.off('data', onStdout);
+      child.stderr?.off('data', onStderr);
+    },
+    read() {
+      return { stdout, stderr };
+    },
+  };
+}
+
+function indicatesPortInUse(stdout: string, stderr: string, message: string): boolean {
+  return [stdout, stderr, message].some(
+    (value) =>
+      value.includes('EADDRINUSE') ||
+      value.includes('address already in use') ||
+      value.includes('Failed to listen at 127.0.0.1'),
+  );
+}
+
+function resolveWorkspacePath(workspaceRoot: string, value: string): string {
+  return path.isAbsolute(value) ? path.resolve(value) : path.resolve(workspaceRoot, value);
 }
 
 async function loadManifest(manifestPath: string): Promise<ModuleManifest | null> {
-    try {
-        const raw = await readFile(manifestPath, 'utf8');
-        return JSON.parse(raw) as ModuleManifest;
-    } catch {
-        return null;
-    }
+  try {
+    const raw = await readFile(manifestPath, 'utf8');
+    return JSON.parse(raw) as ModuleManifest;
+  } catch {
+    return null;
+  }
 }
 
 function emitModuleEvent(level: 'info' | 'warn' | 'error', message: string): void {
-    const payload = JSON.stringify({ type: level, message });
-    process.stdout.write(`WEBSTIR_MODULE_EVENT ${payload}\n`);
+  const payload = JSON.stringify({ type: level, message });
+  process.stdout.write(`WEBSTIR_MODULE_EVENT ${payload}\n`);
 }
 
-async function waitForReady(child: ChildProcess, readyText: string, timeoutMs: number): Promise<void> {
-    const normalized = readyText
-        .split('|')
-        .map((token) => token.trim())
-        .filter(Boolean);
-    const readinessMatches = (line: string) => (normalized.length === 0 ? line.length > 0 : normalized.some((token) => line.includes(token)));
-
-    await new Promise<void>((resolve, reject) => {
-        const cleanup = () => {
-            child.stdout?.off('data', onStdout);
-            child.stderr?.off('data', onStderr);
-            child.off('exit', onExit);
-            clearTimeout(timer);
-        };
-
-        const onStdout = (chunk: Buffer | string) => {
-            const text = chunk.toString();
-            for (const line of text.split(/\r?\n/)) {
-                if (!line) continue;
-                emitModuleEvent('info', line);
-                if (readinessMatches(line)) {
-                    cleanup();
-                    resolve();
-                }
-            }
-        };
-
-        const onStderr = (chunk: Buffer | string) => {
-            const text = chunk.toString();
-            for (const line of text.split(/\r?\n/)) {
-                if (!line) continue;
-                emitModuleEvent('error', line);
-                if (readinessMatches(line)) {
-                    cleanup();
-                    resolve();
-                }
-            }
-        };
-
-        const onExit = (code: number | null) => {
-            cleanup();
-            reject(new Error(`Backend test server exited before it became ready (code ${code ?? 'null'}).`));
-        };
-
-        const timer = setTimeout(() => {
-            cleanup();
-            emitModuleEvent('error', 'Backend test server readiness timed out.');
-            reject(new Error(`Backend test server did not become ready within ${timeoutMs}ms. Check server logs for details.`));
-        }, timeoutMs);
-
-        child.stdout?.on('data', onStdout);
-        child.stderr?.on('data', onStderr);
-        child.once('exit', onExit);
-    });
+async function waitForReady(
+  child: ChildProcess,
+  readyText: string,
+  timeoutMs: number,
+): Promise<void> {
+  const normalized = readyText
+    .split('|')
+    .map((token) => token.trim())
+    .filter(Boolean);
+  const readinessMatches = (line: string) =>
+    normalized.length === 0 ? line.length > 0 : normalized.some((token) => line.includes(token));
+
+  await new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      child.stdout?.off('data', onStdout);
+      child.stderr?.off('data', onStderr);
+      child.off('exit', onExit);
+      clearTimeout(timer);
+    };
+
+    const onStdout = (chunk: Buffer | string) => {
+      const text = chunk.toString();
+      for (const line of text.split(/\r?\n/)) {
+        if (!line) continue;
+        emitModuleEvent('info', line);
+        if (readinessMatches(line)) {
+          cleanup();
+          resolve();
+        }
+      }
+    };
+
+    const onStderr = (chunk: Buffer | string) => {
+      const text = chunk.toString();
+      for (const line of text.split(/\r?\n/)) {
+        if (!line) continue;
+        emitModuleEvent('error', line);
+        if (readinessMatches(line)) {
+          cleanup();
+          resolve();
+        }
+      }
+    };
+
+    const onExit = (code: number | null) => {
+      cleanup();
+      reject(
+        new Error(`Backend test server exited before it became ready (code ${code ?? 'null'}).`),
+      );
+    };
+
+    const timer = setTimeout(() => {
+      cleanup();
+      emitModuleEvent('error', 'Backend test server readiness timed out.');
+      reject(
+        new Error(
+          `Backend test server did not become ready within ${timeoutMs}ms. Check server logs for details.`,
+        ),
+      );
+    }, timeoutMs);
+
+    child.stdout?.on('data', onStdout);
+    child.stderr?.on('data', onStderr);
+    child.once('exit', onExit);
+  });
 }
 
 async function stopProcess(child: ChildProcess): Promise<void> {
-    if (!child || child.killed || child.exitCode !== null) {
-        return;
-    }
-    child.kill('SIGTERM');
-    try {
-        await once(child, 'exit');
-    } catch {
-        // ignore
-    }
+  if (!child || child.killed || child.exitCode !== null) {
+    return;
+  }
+  child.kill('SIGTERM');
+  try {
+    await once(child, 'exit');
+  } catch {
+    // ignore
+  }
 }

package/src/testing/types.d.ts

@@ -1,28 +1,27 @@
 import type { ModuleManifest } from '@webstir-io/module-contract';
 type ModuleRoute = NonNullable<ModuleManifest['routes']>[number];
 export interface BackendTestContext {
-    readonly baseUrl: string;
-    readonly url: URL;
-    readonly port: number;
-    readonly manifest: ModuleManifest | null;
-    readonly routes: readonly ModuleRoute[];
-    readonly env: Readonly<Record<string, string>>;
-    request(pathOrUrl?: string | URL, init?: RequestInit): Promise<Response>;
+  readonly baseUrl: string;
+  readonly url: URL;
+  readonly port: number;
+  readonly manifest: ModuleManifest | null;
+  readonly routes: readonly ModuleRoute[];
+  readonly env: Readonly<Record<string, string>>;
+  request(pathOrUrl?: string | URL, init?: RequestInit): Promise<Response>;
 }
 export interface BackendTestHarness {
-    readonly context: BackendTestContext;
-    stop(): Promise<void>;
+  readonly context: BackendTestContext;
+  stop(): Promise<void>;
 }
 export interface BackendTestHarnessOptions {
-    workspaceRoot?: string;
-    buildRoot?: string;
-    entry?: string;
-    manifestPath?: string;
-    env?: Record<string, string | undefined>;
-    port?: number;
-    readyText?: string;
-    readyTimeoutMs?: number;
-    reuseExistingServer?: boolean;
+  workspaceRoot?: string;
+  buildRoot?: string;
+  entry?: string;
+  manifestPath?: string;
+  env?: Record<string, string | undefined>;
+  port?: number;
+  readyText?: string;
+  readyTimeoutMs?: number;
+  reuseExistingServer?: boolean;
 }
 export type BackendTestCallback = (context: BackendTestContext) => Promise<void> | void;
-export {};

package/src/testing/types.ts

@@ -3,30 +3,30 @@ import type { ModuleManifest } from '@webstir-io/module-contract';
 type ModuleRoute = NonNullable<ModuleManifest['routes']>[number];
 
 export interface BackendTestContext {
-    readonly baseUrl: string;
-    readonly url: URL;
-    readonly port: number;
-    readonly manifest: ModuleManifest | null;
-    readonly routes: readonly ModuleRoute[];
-    readonly env: Readonly<Record<string, string>>;
-    request(pathOrUrl?: string | URL, init?: RequestInit): Promise<Response>;
+  readonly baseUrl: string;
+  readonly url: URL;
+  readonly port: number;
+  readonly manifest: ModuleManifest | null;
+  readonly routes: readonly ModuleRoute[];
+  readonly env: Readonly<Record<string, string>>;
+  request(pathOrUrl?: string | URL, init?: RequestInit): Promise<Response>;
 }
 
 export interface BackendTestHarness {
-    readonly context: BackendTestContext;
-    stop(): Promise<void>;
+  readonly context: BackendTestContext;
+  stop(): Promise<void>;
 }
 
 export interface BackendTestHarnessOptions {
-    workspaceRoot?: string;
-    buildRoot?: string;
-    entry?: string;
-    manifestPath?: string;
-    env?: Record<string, string | undefined>;
-    port?: number;
-    readyText?: string;
-    readyTimeoutMs?: number;
-    reuseExistingServer?: boolean;
+  workspaceRoot?: string;
+  buildRoot?: string;
+  entry?: string;
+  manifestPath?: string;
+  env?: Record<string, string | undefined>;
+  port?: number;
+  readyText?: string;
+  readyTimeoutMs?: number;
+  reuseExistingServer?: boolean;
 }
 
 export type BackendTestCallback = (context: BackendTestContext) => Promise<void> | void;