@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/tests/testing.test.js

@@ -0,0 +1,252 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createBackendTestHarness } from '../src/testing/index.js';
+
+async function createTempDir(prefix) {
+  return await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+async function writeHarnessFixture(
+  workspace,
+  {
+    entryPath = path.join(workspace, 'build', 'backend', 'index.js'),
+    manifestPath = path.join(workspace, '.webstir', 'backend-manifest.json'),
+    manifest = { name: '@demo/backend', version: '0.0.1', routes: [] },
+    entrySource = "console.log('API server running');\nsetInterval(() => {}, 1000);\n",
+  } = {},
+) {
+  await fs.mkdir(path.dirname(entryPath), { recursive: true });
+  await fs.writeFile(entryPath, entrySource, 'utf8');
+  await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+  await fs.writeFile(manifestPath, JSON.stringify(manifest), 'utf8');
+}
+
+async function canListenOnTcp() {
+  return await new Promise((resolve) => {
+    const server = net.createServer();
+    const settle = (value) => {
+      server.removeAllListeners();
+      server.close(() => resolve(value));
+    };
+    server.once('error', (error) => {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'EPERM') {
+        resolve(false);
+        return;
+      }
+      resolve(false);
+    });
+    server.listen(0, '127.0.0.1', () => settle(true));
+  });
+}
+
+async function getOpenPort() {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('Failed to allocate an open port.'));
+        return;
+      }
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+  });
+}
+
+test('createBackendTestHarness resolves WORKSPACE_ROOT when WEBSTIR_WORKSPACE_ROOT is unset', async (t) => {
+  if (!(await canListenOnTcp())) {
+    t.skip('TCP listen is not permitted in this environment.');
+    return;
+  }
+
+  const workspace = await createTempDir('webstir-backend-harness-workspace-');
+  const alternateCwd = await createTempDir('webstir-backend-harness-cwd-');
+  const port = await getOpenPort();
+  await writeHarnessFixture(workspace);
+
+  const previousWorkspaceRoot = process.env.WORKSPACE_ROOT;
+  const previousWebstirWorkspaceRoot = process.env.WEBSTIR_WORKSPACE_ROOT;
+  const previousCwd = process.cwd();
+  let harness;
+
+  try {
+    process.env.WORKSPACE_ROOT = workspace;
+    delete process.env.WEBSTIR_WORKSPACE_ROOT;
+    process.chdir(alternateCwd);
+
+    harness = await createBackendTestHarness({ port });
+
+    assert.equal(harness.context.env.WORKSPACE_ROOT, workspace);
+    assert.match(harness.context.baseUrl, /^http:\/\/127\.0\.0\.1:\d+\/?$/);
+  } finally {
+    await harness?.stop();
+    process.chdir(previousCwd);
+    if (previousWorkspaceRoot === undefined) {
+      delete process.env.WORKSPACE_ROOT;
+    } else {
+      process.env.WORKSPACE_ROOT = previousWorkspaceRoot;
+    }
+    if (previousWebstirWorkspaceRoot === undefined) {
+      delete process.env.WEBSTIR_WORKSPACE_ROOT;
+    } else {
+      process.env.WEBSTIR_WORKSPACE_ROOT = previousWebstirWorkspaceRoot;
+    }
+  }
+});
+
+test('createBackendTestHarness resolves WEBSTIR_WORKSPACE_ROOT from env overrides outside the workspace cwd', async (t) => {
+  if (!(await canListenOnTcp())) {
+    t.skip('TCP listen is not permitted in this environment.');
+    return;
+  }
+
+  const workspace = await createTempDir('webstir-backend-harness-env-workspace-');
+  const alternateCwd = await createTempDir('webstir-backend-harness-env-cwd-');
+  const port = await getOpenPort();
+  await writeHarnessFixture(workspace, {
+    entryPath: path.join(workspace, 'custom', 'backend', 'index.js'),
+    manifestPath: path.join(workspace, '.webstir', 'custom-backend-manifest.json'),
+    manifest: {
+      name: '@demo/env-harness',
+      version: '1.2.3',
+      routes: [{ path: '/env', method: 'GET' }],
+    },
+  });
+
+  const previousCwd = process.cwd();
+  let harness;
+
+  try {
+    process.chdir(alternateCwd);
+
+    harness = await createBackendTestHarness({
+      port,
+      env: {
+        WEBSTIR_WORKSPACE_ROOT: workspace,
+        WEBSTIR_BACKEND_BUILD_ROOT: 'custom/backend',
+        WEBSTIR_BACKEND_TEST_MANIFEST: '.webstir/custom-backend-manifest.json',
+      },
+    });
+
+    assert.equal(harness.context.env.WORKSPACE_ROOT, workspace);
+    assert.equal(harness.context.manifest?.name, '@demo/env-harness');
+    assert.equal(harness.context.routes[0]?.path, '/env');
+    assert.match(harness.context.baseUrl, /^http:\/\/127\.0\.0\.1:\d+\/?$/);
+  } finally {
+    await harness?.stop();
+    process.chdir(previousCwd);
+  }
+});
+
+test('createBackendTestHarness retries on EADDRINUSE and reports the bound port', async (t) => {
+  if (!(await canListenOnTcp())) {
+    t.skip('TCP listen is not permitted in this environment.');
+    return;
+  }
+
+  const workspace = await createTempDir('webstir-backend-harness-port-retry-');
+  const requestedPort = await getOpenPort();
+  const blocker = net.createServer();
+  await new Promise((resolve, reject) => {
+    blocker.once('error', reject);
+    blocker.listen(requestedPort, '127.0.0.1', () => resolve());
+  });
+
+  await writeHarnessFixture(workspace, {
+    entrySource: `
+import net from 'node:net';
+
+const server = net.createServer((socket) => socket.end());
+const port = Number(process.env.PORT ?? '0');
+
+server.listen(port, '127.0.0.1', () => {
+  console.log('API server running');
+});
+
+const shutdown = () => {
+  server.close(() => process.exit(0));
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+`,
+  });
+
+  let harness;
+  try {
+    harness = await createBackendTestHarness({
+      workspaceRoot: workspace,
+      port: requestedPort,
+    });
+
+    assert.notEqual(harness.context.port, requestedPort);
+    assert.equal(harness.context.env.PORT, String(harness.context.port));
+    assert.match(harness.context.baseUrl, new RegExp(`:${harness.context.port}/?$`));
+  } finally {
+    await harness?.stop();
+    await new Promise((resolve, reject) => {
+      blocker.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+});
+
+test('createBackendTestHarness resolves option-based relative entry and manifest paths outside the workspace cwd', async (t) => {
+  if (!(await canListenOnTcp())) {
+    t.skip('TCP listen is not permitted in this environment.');
+    return;
+  }
+
+  const workspace = await createTempDir('webstir-backend-harness-options-workspace-');
+  const alternateCwd = await createTempDir('webstir-backend-harness-options-cwd-');
+  const port = await getOpenPort();
+  await writeHarnessFixture(workspace, {
+    entryPath: path.join(workspace, 'artifacts', 'backend', 'server.js'),
+    manifestPath: path.join(workspace, 'artifacts', 'backend', 'manifest.json'),
+    manifest: {
+      name: '@demo/options-harness',
+      version: '4.5.6',
+      routes: [{ path: '/options', method: 'POST' }],
+    },
+  });
+
+  const previousCwd = process.cwd();
+  let harness;
+
+  try {
+    process.chdir(alternateCwd);
+
+    harness = await createBackendTestHarness({
+      workspaceRoot: workspace,
+      buildRoot: 'artifacts/backend',
+      entry: 'artifacts/backend/server.js',
+      manifestPath: 'artifacts/backend/manifest.json',
+      port,
+    });
+
+    assert.equal(harness.context.env.WORKSPACE_ROOT, workspace);
+    assert.equal(harness.context.manifest?.name, '@demo/options-harness');
+    assert.equal(harness.context.routes[0]?.path, '/options');
+    assert.match(harness.context.baseUrl, /^http:\/\/127\.0\.0\.1:\d+\/?$/);
+  } finally {
+    await harness?.stop();
+    process.chdir(previousCwd);
+  }
+});

package/tests/watch.test.js

@@ -31,6 +31,22 @@ async function seedBackendEntry(workspace) {
   }
 }
 
+async function seedBackendScaffold(workspace) {
+  const assets = await backendProvider.getScaffoldAssets();
+  for (const asset of assets) {
+    if (!asset.targetPath.startsWith(path.join('src', 'backend'))) continue;
+    const target = path.join(workspace, asset.targetPath);
+    await copyFile(asset.sourcePath, target);
+  }
+}
+
+async function linkWorkspacePackage(workspace) {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const scopeRoot = path.join(workspace, 'node_modules', '@webstir-io');
+  await fs.mkdir(scopeRoot, { recursive: true });
+  await fs.symlink(packageRoot, path.join(scopeRoot, 'webstir-backend'), 'dir');
+}
+
 function getLocalBinPath() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const pkgRoot = path.resolve(here, '..');
@@ -46,55 +62,199 @@ async function waitFor(checkFn, timeoutMs = 5000, pollMs = 100) {
   throw new Error('waitFor timed out');
 }
 
-test('startBackendWatch updates cache files after rebuild', async () => {
+test('startBackendWatch updates cache files after rebuild', { timeout: 15_000 }, async () => {
   const workspace = await createTempWorkspace();
   await seedBackendEntry(workspace);
 
   const env = {
     WEBSTIR_MODULE_MODE: 'build',
     WEBSTIR_BACKEND_TYPECHECK: 'skip',
-    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`,
   };
 
-  const handle = await startBackendWatch({ workspaceRoot: workspace, env });
   try {
+    const handle = await startBackendWatch({ workspaceRoot: workspace, env });
     const outputsPath = path.join(workspace, '.webstir', 'backend-outputs.json');
 
-    await waitFor(async () => {
-      try {
-        await fs.access(outputsPath);
-        return true;
-      } catch {
-        return false;
-      }
+    try {
+      await waitFor(async () => {
+        try {
+          await fs.access(outputsPath);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+
+      const before = JSON.parse(await fs.readFile(outputsPath, 'utf8'));
+      const indexPath = path.join(workspace, 'src', 'backend', 'index.ts');
+      await fs.appendFile(indexPath, '\nconsole.log("watch-test");\n', 'utf8');
+
+      await waitFor(async () => {
+        try {
+          const after = JSON.parse(await fs.readFile(outputsPath, 'utf8'));
+          const key = Object.keys(after)[0];
+          return before[key] !== after[key];
+        } catch {
+          return false;
+        }
+      });
+
+      const manifestDigestPath = path.join(workspace, '.webstir', 'backend-manifest-digest.json');
+      await waitFor(async () => {
+        try {
+          await fs.access(manifestDigestPath);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+
+      assert.ok(true, 'watch updated cache files after rebuild');
+    } finally {
+      await handle.stop();
+    }
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('startBackendWatch emits build outcome events for successful and failed rebuilds', {
+  timeout: 15_000,
+}, async () => {
+  const workspace = await createTempWorkspace('webstir-backend-watch-events-');
+  await seedBackendEntry(workspace);
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`,
+  };
+
+  const events = [];
+  try {
+    const handle = await startBackendWatch({
+      workspaceRoot: workspace,
+      env,
+      onEvent(event) {
+        events.push(event);
+      },
     });
 
-    const before = JSON.parse(await fs.readFile(outputsPath, 'utf8'));
-    const indexPath = path.join(workspace, 'src', 'backend', 'index.ts');
-    await fs.appendFile(indexPath, '\nconsole.log("watch-test");\n', 'utf8');
-
-    await waitFor(async () => {
-      try {
-        const after = JSON.parse(await fs.readFile(outputsPath, 'utf8'));
-        const key = Object.keys(after)[0];
-        return before[key] !== after[key];
-      } catch {
-        return false;
-      }
+    try {
+      await waitFor(async () =>
+        events.some((event) => event.type === 'build-complete' && event.succeeded === true),
+      );
+
+      const indexPath = path.join(workspace, 'src', 'backend', 'index.ts');
+      await fs.writeFile(indexPath, 'export default () => {\n', 'utf8');
+
+      await waitFor(async () =>
+        events.some((event) => event.type === 'build-complete' && event.succeeded === false),
+      );
+
+      assert.ok(events.some((event) => event.type === 'build-start'));
+      assert.ok(
+        events.some((event) => event.type === 'build-complete' && event.succeeded === true),
+      );
+      assert.ok(
+        events.some((event) => event.type === 'build-complete' && event.succeeded === false),
+      );
+    } finally {
+      await handle.stop();
+    }
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('startBackendWatch reports Bun benchmark timings when enabled', {
+  timeout: 15_000,
+}, async () => {
+  const workspace = await createTempWorkspace('webstir-backend-watch-benchmark-');
+  await seedBackendScaffold(workspace);
+  await linkWorkspacePackage(workspace);
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    WEBSTIR_BACKEND_WATCH_BUN_BENCHMARK: '1',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`,
+  };
+
+  const events = [];
+  try {
+    const handle = await startBackendWatch({
+      workspaceRoot: workspace,
+      env,
+      onEvent(event) {
+        events.push(event);
+      },
     });
 
-    const manifestDigestPath = path.join(workspace, '.webstir', 'backend-manifest-digest.json');
-    await waitFor(async () => {
-      try {
-        await fs.access(manifestDigestPath);
-        return true;
-      } catch {
-        return false;
-      }
+    try {
+      await waitFor(async () =>
+        events.some(
+          (event) =>
+            event.type === 'build-complete' &&
+            event.succeeded === true &&
+            typeof event.bunBenchmarkDurationMs === 'number' &&
+            event.bunBenchmarkDurationMs > 0,
+        ),
+      );
+
+      const completedEvent = events.find(
+        (event) =>
+          event.type === 'build-complete' &&
+          event.succeeded === true &&
+          typeof event.bunBenchmarkDurationMs === 'number',
+      );
+
+      assert.equal(completedEvent?.bunBenchmarkSucceeded, true);
+      assert.equal(completedEvent?.bunBenchmarkErrorCount, 0);
+      assert.ok((completedEvent?.bunBenchmarkDurationMs ?? 0) > 0);
+    } finally {
+      await handle.stop();
+    }
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('startBackendWatch resolves WEBSTIR_WORKSPACE_ROOT outside the workspace cwd when workspaceRoot is omitted', {
+  timeout: 15_000,
+}, async () => {
+  const workspace = await createTempWorkspace('webstir-backend-watch-root-');
+  const alternateCwd = await createTempWorkspace('webstir-backend-watch-cwd-');
+  const previousCwd = process.cwd();
+  await seedBackendEntry(workspace);
+
+  try {
+    process.chdir(alternateCwd);
+
+    const handle = await startBackendWatch({
+      env: {
+        WEBSTIR_MODULE_MODE: 'build',
+        WEBSTIR_BACKEND_TYPECHECK: 'skip',
+        WEBSTIR_WORKSPACE_ROOT: workspace,
+      },
     });
 
-    assert.ok(true, 'watch updated cache files after rebuild');
+    try {
+      await waitFor(async () => {
+        try {
+          await fs.access(path.join(workspace, '.webstir', 'backend-outputs.json'));
+          return true;
+        } catch {
+          return false;
+        }
+      });
+    } finally {
+      await handle.stop();
+    }
   } finally {
-    await handle.stop();
+    process.chdir(previousCwd);
+    await fs.rm(alternateCwd, { recursive: true, force: true });
+    await fs.rm(workspace, { recursive: true, force: true });
   }
 });

package/tsconfig.json

@@ -12,16 +12,9 @@
     "declaration": true,
     "declarationMap": false,
     "sourceMap": false,
-    "types": [
-      "node"
-    ],
+    "types": ["node"],
     "resolveJsonModule": true
   },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "dist",
-    "node_modules"
-  ]
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
 }