feat: enhance startApp to wait for a URL and add waitForUrl utility

Author: Kan-A-Pesh

src/core/start-app.ts

@@ -1,12 +1,14 @@
 import type { Config } from "./types.js";
 import { executeCommand, type RunningProcess } from "./utils/execute-command.js";
+import { waitForUrl } from "./utils/wait-for-url.js";
 
 /**
  * Start the application using lifecycle.start commands
  * @param config The validated configuration object
+ * @param url Optional URL to wait for after starting commands with keepAlive
  * @returns Cleanup function that stops all running processes
  */
-export async function startApp(config: Config): Promise<() => Promise<void>> {
+export async function startApp(config: Config, url?: string): Promise<() => Promise<void>> {
   const runningProcesses: RunningProcess[] = [];
 
   try {
@@ -17,6 +19,14 @@ export async function startApp(config: Config): Promise<() => Promise<void>> {
       }
     }
 
+    // Wait for URL to become available if:
+    // 1. A URL was provided AND
+    // 2. At least one command has keepAlive: true
+    const hasKeepAliveCommand = config.lifecycle.start.some((cmd) => cmd.keepAlive);
+    if (url && hasKeepAliveCommand) {
+      await waitForUrl(url);
+    }
+
     // Return cleanup function
     return async () => {
       for (const { process, command } of runningProcesses) {

src/core/utils/wait-for-url.ts

@@ -0,0 +1,32 @@
+/**
+ * Wait for a URL to become available by polling with fetch
+ * @param url The URL to check (e.g., "http://localhost:3000")
+ * @param timeout Maximum time to wait in milliseconds (default: 30000)
+ * @throws Error if URL doesn't become available within timeout
+ */
+export async function waitForUrl(url: string, timeout: number = 30000): Promise<void> {
+  const startTime = Date.now();
+  const interval = 1000; // Poll every 1 second
+
+  while (Date.now() - startTime < timeout) {
+    try {
+      // Use AbortSignal.timeout for per-request timeout (2 seconds)
+      const response = await fetch(url, { signal: AbortSignal.timeout(2000) });
+
+      // Consider 2xx-4xx as "available" - only 5xx errors mean server isn't ready
+      // This handles cases where the app redirects or returns 404 before fully loading
+      if (response.ok || response.status < 500) {
+        return;
+      }
+    } catch (_error) {
+      // Suppress errors during polling - connection errors are expected while server starts
+      // Errors include: connection refused, timeout, DNS errors, etc.
+    }
+
+    // Wait before next poll attempt
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+
+  // Timeout reached without successful connection
+  throw new Error(`Timeout: ${url} did not become available within ${timeout}ms`);
+}

src/recorder/index.ts

@@ -21,7 +21,7 @@ export async function startRecording(storyId: string): Promise<void> {
   try {
     config = await loadConfig();
     const story = await loadStory(storyId);
-    cleanup = await startApp(config);
+    cleanup = await startApp(config, story.start.url);
     browserInstance = await launchBrowser(story);
     const { browser, page } = browserInstance;
 

src/runner/index.ts

@@ -204,7 +204,7 @@ export async function runStory(
     const story = await loadStory(storyId);
 
     // 3. Start application
-    cleanup = await startApp(config);
+    cleanup = await startApp(config, story.start.url);
 
     // 4. Launch browser
     browserInstance = await launchBrowser(story);