@harperfast/integration-testing 0.3.1 → 0.5.0

package/README.md

@@ -68,16 +68,22 @@ The Harper binary is resolved in the following order:
 
 ```ts
 interface StartHarperOptions {
-  startupTimeoutMs?: number;   // Default: 30000 or HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS
+  startupTimeoutMs?: number;   // Idle timeout: max gap between startup output chunks. Default: 60000 or HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS
+  startupMaxMs?: number;       // Absolute startup ceiling regardless of output. Default: 120000 (300000 under CI) or HARPER_INTEGRATION_TEST_STARTUP_MAX_MS
   config?: object;             // Harper config overrides (passed via HARPER_SET_CONFIG)
   env?: object;                // Additional environment variables for the Harper process
   harperBinPath?: string;      // Explicit path to dist/bin/harper.js
 }
 ```
 
+Startup readiness is detected by Harper printing `successfully started`. Rather than a single wall-clock deadline (which makes a slow-but-healthy boot indistinguishable from a hang), the watchdog uses an **idle timeout** that resets on every chunk of output — so the limit is time-since-last-progress — plus a generous absolute ceiling as a backstop. This is why a slow CI boot that keeps logging no longer trips the timeout.
+
+> **Behavior change:** `startupTimeoutMs` (and `HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS`) previously meant an absolute startup deadline. It now means the **idle / no-output window**. If you relied on it as a hard ceiling to fail slow boots quickly, set `startupMaxMs` (or `HARPER_INTEGRATION_TEST_STARTUP_MAX_MS`) instead.
+
 **Environment Variables:**
 
-- `HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS` - Default startup timeout
+- `HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS` - Idle startup timeout: max time between chunks of startup output before Harper is treated as hung (resets on output). Default `60000`.
+- `HARPER_INTEGRATION_TEST_STARTUP_MAX_MS` - Absolute ceiling on total startup time, regardless of ongoing output. Default `120000` (`300000` under CI).
 - `HARPER_INTEGRATION_TEST_INSTALL_PARENT_DIR` - Parent directory for temp Harper install dirs (default: OS tmpdir)
 - `HARPER_INTEGRATION_TEST_INSTALL_SCRIPT` - Path to Harper CLI script
 
@@ -85,13 +91,22 @@ interface StartHarperOptions {
 
 Like `startHarper()`, but copies a component directory into the Harper install before starting, so it's available on first boot without a deploy.
 
-### `killHarper(ctx)`
+### `killHarper(ctx, options?)`
 
-Sends SIGTERM to the Harper process and waits for it to exit. Does not release the loopback address or clean up the install directory. Useful for restart scenarios where the test will call `startHarper` again.
+Terminates Harper's whole process tree and waits for it to exit. It sends SIGTERM first, giving Harper a grace period to shut down cleanly (flush RocksDB, release ports, reap workers) before escalating to SIGKILL, then waits briefly for the actual exit. Because Harper is spawned as its own process group (`detached` on POSIX), the signal targets the group — parent and any child processes — rather than only the direct child; on Windows it uses `taskkill /T`. A dead process releases its listening sockets, so once `killHarper` returns the fixed ports are free. Does not release the loopback address or clean up the install directory. Useful for restart scenarios where the test will call `startHarper` again.
+
+`options.graceMs` overrides the SIGTERM→SIGKILL grace period (default `5000`, or `HARPER_INTEGRATION_TEST_TEARDOWN_GRACE_MS`).
 
 ### `teardownHarper(ctx)`
 
-Kills Harper, releases the loopback address back to the pool, and removes the install directory. Call in a teardown/`after()` hook.
+Kills Harper's process tree, releases the loopback address back to the pool, and removes the install directory. Call in a teardown/`after()` hook.
+
+Since `killHarper` waits for the process tree to exit, its fixed ports (Operations API, HTTP/S, MQTT/S) are already released by the time the address is recycled. As a safety assertion, teardown still verifies those ports are free before recycling — the pool only guarantees the *address* is bindable, not that these specific ports are free — and logs a warning if any are somehow still held (a sign a Harper child process escaped the kill). The address is recycled regardless.
+
+**Environment Variables:**
+
+- `HARPER_INTEGRATION_TEST_TEARDOWN_GRACE_MS` - Grace period after SIGTERM before escalating to SIGKILL. Default `5000`.
+- `HARPER_INTEGRATION_TEST_PORT_RELEASE_TIMEOUT_MS` - Max time teardown's safety assertion waits for Harper's ports to be free before recycling the loopback address (normally instant, since the process tree is already dead). Default `5000`.
 
 ### `sendOperation(context, operation)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/integration-testing",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"type": "module",
 	"description": "Integration testing utilities for Harper-based projects. Provides Harper instance lifecycle management, loopback address pooling, and a test runner script.",
 	"license": "Apache-2.0",
@@ -22,7 +22,8 @@
 	],
 	"scripts": {
 		"check": "tsc",
-		"build": "tsc -p tsconfig.build.json"
+		"build": "tsc -p tsconfig.build.json",
+		"test": "node --test \"test/**/*.test.ts\""
 	},
 	"engines": {
 		"node": ">=20"
@@ -30,7 +31,7 @@
 	"devEngines": {
 		"runtime": {
 			"name": "node",
-			"version": ">=22",
+			"version": ">=22.18.0",
 			"onFail": "error"
 		},
 		"packageManager": {

package/scripts/setup-loopback.sh

@@ -3,22 +3,39 @@
 # Prompt for password upfront
 sudo -v
 
+# The pool starts at 127.0.0.2 by default (127.0.0.1 is left for other services on localhost).
+# Override via the HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START environment variable.
+START=${HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START:-2}
+
+# Validate START is a number between 1 and 255
+if ! [[ "$START" =~ ^[0-9]+$ ]]; then
+  echo "Error: HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START must be a number (got: $START)"
+  exit 1
+fi
+
+if [ "$START" -lt 1 ] || [ "$START" -gt 255 ]; then
+  echo "Error: HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START must be between 1 and 255 (got: $START)"
+  exit 1
+fi
+
 # Use environment variable or default to 32
 COUNT=${HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT:-32}
+MAX=$((256 - START))
 
-# Validate COUNT is a number between 1 and 255
+# Validate COUNT is a number between 1 and MAX
 if ! [[ "$COUNT" =~ ^[0-9]+$ ]]; then
   echo "Error: HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT must be a number (got: $COUNT)"
   exit 1
 fi
 
-if [ "$COUNT" -lt 1 ] || [ "$COUNT" -gt 255 ]; then
-  echo "Error: HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT must be between 1 and 255 (got: $COUNT)"
+if [ "$COUNT" -lt 1 ] || [ "$COUNT" -gt "$MAX" ]; then
+  echo "Error: HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT must be between 1 and $MAX (got: $COUNT)"
   exit 1
 fi
 
-for i in $(seq 1 $COUNT); do
+END=$((START + COUNT - 1))
+for i in $(seq $START $END); do
   sudo ifconfig lo0 alias 127.0.0.$i up
 done
 
-echo "✓ Configured $COUNT loopback addresses (127.0.0.1-127.0.0.$COUNT)"
+echo "✓ Configured $COUNT loopback addresses (127.0.0.$START-127.0.0.$END)"

package/dist/harperLifecycle.d.ts

@@ -1,182 +0,0 @@
-import { ChildProcess } from 'node:child_process';
-import { type SuiteContext, type TestContext } from 'node:test';
-/**
- * Minimal context interface required by startHarper/teardownHarper.
- *
- * This is intentionally loose so it can be satisfied by:
- * - node:test SuiteContext/TestContext objects (via ContextWithHarper)
- * - Plain objects (e.g. Playwright worker fixtures: `createHarperContext()`)
- */
-export interface HarperTestContext {
-    /** Optional name used for log directory naming (e.g. suite name or Playwright worker index). */
-    name?: string;
-    /** Populated by startHarper(). May be pre-seeded with dataRootDir/hostname to reuse across restarts. */
-    harper?: Partial<HarperContext>;
-}
-/**
- * A started context — harper is fully populated after startHarper() resolves.
- */
-export interface StartedHarperTestContext extends HarperTestContext {
-    harper: HarperContext;
-}
-/**
- * Creates a plain object satisfying HarperTestContext, for use outside node:test
- * (e.g. as a Playwright worker fixture).
- *
- * @param name Optional name for log directory naming (e.g. Playwright worker index).
- */
-export declare function createHarperContext(name?: string): HarperTestContext;
-export declare const OPERATIONS_API_PORT = 9925;
-export declare const DEFAULT_ADMIN_USERNAME = "admin";
-export declare const DEFAULT_ADMIN_PASSWORD = "Abc1234!";
-export declare const DEFAULT_STARTUP_TIMEOUT_MS: number;
-/**
- * The runtime to use for running Harper during tests.
- * Set via the HARPER_RUNTIME environment variable ('node' or 'bun').
- * Defaults to 'node'.
- */
-export declare const HARPER_RUNTIME: 'node' | 'bun';
-/**
- * Marker emitted on stdout by startHarper() so the test runner (run.ts) can map
- * a Harper instance's log directory to the currently executing test file via
- * the node:test `test:stdout` event.
- */
-export declare const LOG_DIR_MARKER_PREFIX = "[Harper] Logs for this instance will be stored in:";
-/**
- * Options for setting up a Harper instance.
- */
-export interface StartHarperOptions {
-    /**
-     * Timeout in milliseconds to wait for Harper to start.
-     * @default 30000
-     */
-    startupTimeoutMs?: number;
-    /**
-     * Additional configuration options to pass to the Harper CLI.
-     */
-    config?: any;
-    /**
-     * Environment variables to set when running Harper.
-     */
-    env?: any;
-    /**
-     * Explicit path to the Harper CLI script (dist/bin/harper.js).
-     * If not provided, resolution order is:
-     *   1. This option
-     *   2. HARPER_INTEGRATION_TEST_INSTALL_SCRIPT environment variable
-     *   3. Auto-resolved from 'harper' package in node_modules
-     */
-    harperBinPath?: string;
-}
-export interface HarperContext {
-    /** Absolute path to the Harper installation directory */
-    dataRootDir: string;
-    /** Admin credentials for the Harper instance */
-    admin: {
-        /** Admin username (default: 'admin') */
-        username: string;
-        /** Admin password (default: 'Abc1234!') */
-        password: string;
-    };
-    /** HTTP URL for the Harper instance (e.g., 'http://127.0.0.2:9926') */
-    httpURL: string;
-    /** Operations API URL (e.g., 'http://127.0.0.2:9925') */
-    operationsAPIURL: string;
-    /** Assigned loopback IP address (e.g., '127.0.0.2') */
-    hostname: string;
-    /** Child process for the Harper instance */
-    process: ChildProcess;
-    /** Absolute path to the log directory for this suite (only set when HARPER_INTEGRATION_TEST_LOG_DIR is configured) */
-    logDir?: string;
-    /** Captured stdout/stderr from Harper startup, up to the point it reported ready. */
-    startupOutput?: {
-        stdout: string;
-        stderr: string;
-    };
-}
-/**
- * Test context interface with Harper instance details, for use with node:test.
- *
- * This interface is populated by `startHarper()` and contains
- * all necessary information to interact with the test Harper instance.
- *
- * For use outside node:test (e.g. Playwright), use `createHarperContext()` to
- * create a plain object satisfying `HarperTestContext` instead.
- */
-export interface ContextWithHarper extends SuiteContext, TestContext {
-    harper: HarperContext;
-}
-/**
- * Error thrown when a Harper process fails to start or times out.
- * Includes captured stdout and stderr for diagnostics.
- */
-export declare class HarperStartupError extends Error {
-    stdout: string;
-    stderr: string;
-    constructor(message: string, stdout: string, stderr: string);
-}
-/**
- * Sets up a Harper instance with a component pre-installed from a local directory.
- *
- * Copies `fixturePath` into `{dataRootDir}/components/{name}` before Harper starts,
- * so the component is available on the first request without a post-startup deploy.
- * Use this when tests need a known route available at startup (e.g. mTLS cert tests).
- *
- * @param ctx - The test context to populate with Harper instance details
- * @param fixturePath - Absolute path to the component directory to pre-install
- * @param options - Optional configuration for the setup process
- */
-export declare function setupHarperWithFixture(ctx: HarperTestContext, fixturePath: string, options?: StartHarperOptions): Promise<StartedHarperTestContext>;
-/**
- * Sets up and starts a Harper instance for testing.
- *
- * @param ctx - The test context to populate with Harper instance details
- * @param options - Optional configuration for the setup process
- * @returns The context with the `harper` property populated
- *
- * @example
- * ```ts
- * suite('My tests', (ctx: ContextWithHarper) => {
- *   before(async () => {
- *     await startHarper(ctx);
- *   });
- *
- *   after(async () => {
- *     await teardownHarper(ctx);
- *   });
- *
- *   test('can connect', async () => {
- *     const response = await fetch(ctx.harper.httpURL);
- *     // ...
- *   });
- * });
- * ```
- */
-export declare function startHarper(ctx: HarperTestContext, options?: StartHarperOptions): Promise<StartedHarperTestContext>;
-/**
- * Kill harper process (can be used for teardown, or killing it before a restart)
- * @param ctx
- */
-export declare function killHarper(ctx: StartedHarperTestContext): Promise<void>;
-/**
- * Tears down a Harper instance and cleans up all resources.
- *
- * This function stops the Harper instance, releases the loopback address,
- * and removes the installation directory.
- * @param ctx - The test context with Harper instance details
- *
- * @example
- * ```ts
- * suite('My tests', (ctx: ContextWithHarper) => {
- *   before(async () => {
- *     await startHarper(ctx);
- *   });
- *
- *   after(async () => {
- *     await teardownHarper(ctx);
- *   });
- * });
- * ```
- */
-export declare function teardownHarper(ctx: StartedHarperTestContext): Promise<void>;
-export declare function sendOperation(context: HarperContext, operation: any): Promise<any>;

package/dist/harperLifecycle.js

@@ -1,374 +0,0 @@
-import { spawn, ChildProcess } from 'node:child_process';
-import { createWriteStream, existsSync } from 'node:fs';
-import { join, basename, dirname } from 'node:path';
-import { tmpdir } from 'node:os';
-import { mkdtemp, mkdir, rm, cp } from 'node:fs/promises';
-import {} from 'node:test';
-import { getNextAvailableLoopbackAddress, releaseLoopbackAddress } from "./loopbackAddressPool.js";
-import { ok, equal } from 'node:assert';
-import { createRequire } from 'node:module';
-/**
- * Creates a plain object satisfying HarperTestContext, for use outside node:test
- * (e.g. as a Playwright worker fixture).
- *
- * @param name Optional name for log directory naming (e.g. Playwright worker index).
- */
-export function createHarperContext(name) {
-    return { name };
-}
-// Constants
-const HTTP_PORT = 9926;
-const HTTPS_PORT = 9927;
-const MQTT_PORT = 1883;
-const MQTTS_PORT = 8883;
-export const OPERATIONS_API_PORT = 9925;
-export const DEFAULT_ADMIN_USERNAME = 'admin';
-export const DEFAULT_ADMIN_PASSWORD = 'Abc1234!';
-export const DEFAULT_STARTUP_TIMEOUT_MS = parseInt(process.env.HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS || '', 10) || 60000;
-/**
- * The runtime to use for running Harper during tests.
- * Set via the HARPER_RUNTIME environment variable ('node' or 'bun').
- * Defaults to 'node'.
- */
-export const HARPER_RUNTIME = process.env.HARPER_RUNTIME || 'node';
-/**
- * Marker emitted on stdout by startHarper() so the test runner (run.ts) can map
- * a Harper instance's log directory to the currently executing test file via
- * the node:test `test:stdout` event.
- */
-export const LOG_DIR_MARKER_PREFIX = '[Harper] Logs for this instance will be stored in:';
-/**
- * Gets the path to the Harper CLI script.
- *
- * Resolution order:
- * 1. `harperBinPath` argument
- * 2. `HARPER_INTEGRATION_TEST_INSTALL_SCRIPT` environment variable
- * 3. Auto-resolved from 'harper' package in node_modules
- * 4. Auto-resolved from current directory or ancestors ('dist/bin/harper.js')
- *
- * @returns The absolute path to the Harper CLI entry script
- * @throws {AssertionError} If the script cannot be found
- */
-function getHarperScript(harperBinPath) {
-    // 1. Explicit option
-    if (harperBinPath) {
-        ok(existsSync(harperBinPath), `Harper script not found at provided harperBinPath: ${harperBinPath}`);
-        return harperBinPath;
-    }
-    // 2. Environment variable
-    const envPath = process.env.HARPER_INTEGRATION_TEST_INSTALL_SCRIPT;
-    if (envPath) {
-        ok(existsSync(envPath), `Harper script not found at HARPER_INTEGRATION_TEST_INSTALL_SCRIPT path: ${envPath}`);
-        return envPath;
-    }
-    // 3. Auto-resolve from node_modules
-    try {
-        const require = createRequire(import.meta.url);
-        const resolved = require.resolve('harper/dist/bin/harper.js');
-        if (existsSync(resolved)) {
-            return resolved;
-        }
-    }
-    catch {
-        // harper package not found in node_modules
-    }
-    // 4. Auto-resolve from current directory or ancestors
-    let currentDir = process.cwd();
-    while (true) {
-        const potentialPath = join(currentDir, 'dist/bin/harper.js');
-        if (existsSync(potentialPath)) {
-            return potentialPath;
-        }
-        const parentDir = dirname(currentDir);
-        if (parentDir === currentDir) {
-            break;
-        }
-        currentDir = parentDir;
-    }
-    throw new Error(`Harper CLI script not found. Provide the path via:\n` +
-        `  - harperBinPath option: startHarper(ctx, { harperBinPath: '/path/to/dist/bin/harper.js' })\n` +
-        `  - HARPER_INTEGRATION_TEST_INSTALL_SCRIPT environment variable\n` +
-        `  - Install 'harper' as a dependency in your project\n` +
-        `  - Run tests within a directory containing 'dist/bin/harper.js'`);
-}
-/**
- * Strips ANSI escape sequences (colors, bold, underline, cursor movement, etc.) from a string.
- */
-// eslint-disable-next-line no-control-regex
-const ANSI_REGEX = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nq-uy=><~]/g;
-function stripAnsi(str) {
-    return str.replace(ANSI_REGEX, '');
-}
-/**
- * Sanitizes a string for use as a filesystem directory name.
- */
-function sanitizeForFilesystem(name) {
-    return name
-        .replace(/[^a-zA-Z0-9_-]/g, '_')
-        .replace(/_+/g, '_')
-        .substring(0, 100);
-}
-/**
- * Error thrown when a Harper process fails to start or times out.
- * Includes captured stdout and stderr for diagnostics.
- */
-export class HarperStartupError extends Error {
-    stdout;
-    stderr;
-    constructor(message, stdout, stderr) {
-        let fullMessage = message;
-        if (stdout) {
-            fullMessage += `\n\nstdout:\n${stdout}`;
-        }
-        if (stderr) {
-            fullMessage += `\n\nstderr:\n${stderr}`;
-        }
-        super(fullMessage);
-        this.name = 'HarperStartupError';
-        this.stdout = stdout;
-        this.stderr = stderr;
-    }
-}
-/**
- * Runs a Harper CLI command and captures output.
- *
- * When `logDir` is provided, stdout and stderr are also written to files
- * (`stdout.log` and `stderr.log`) in that directory.
- *
- * @throws {HarperStartupError} If the command times out or exits with a non-zero status code
- */
-function runHarperCommand({ args, env, completionMessage, logDir, harperBinPath, timeoutMs, }) {
-    const harperScript = getHarperScript(harperBinPath);
-    const runtime = HARPER_RUNTIME;
-    const runtimeArgs = runtime === 'bun'
-        ? [harperScript, ...args]
-        : ['--trace-warnings', '--force-node-api-uncaught-exceptions-policy=true', harperScript, ...args];
-    const proc = spawn(runtime, runtimeArgs, {
-        env: { ...process.env, ...env },
-    });
-    let stdoutStream;
-    let stderrStream;
-    if (logDir) {
-        stdoutStream = createWriteStream(join(logDir, 'stdout.log'));
-        stderrStream = createWriteStream(join(logDir, 'stderr.log'));
-    }
-    const effectiveTimeout = timeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
-    return new Promise((resolve, reject) => {
-        let stdout = '';
-        let stderr = '';
-        let timer = setTimeout(() => {
-            reject(new HarperStartupError(`Harper process timed out after ${effectiveTimeout}ms`, stdout, stderr));
-            proc.kill();
-        }, effectiveTimeout);
-        proc.stdout?.on('data', (data) => {
-            const dataString = stripAnsi(data.toString());
-            stdoutStream?.write(dataString);
-            if (completionMessage && dataString.includes(completionMessage)) {
-                clearTimeout(timer);
-                resolve({ process: proc, stdout, stderr });
-            }
-            stdout += dataString;
-        });
-        proc.stderr?.on('data', (data) => {
-            const dataString = stripAnsi(data.toString());
-            stderrStream?.write(dataString);
-            stderr += dataString;
-        });
-        proc.on('error', (error) => {
-            reject(error);
-        });
-        proc.on('exit', (statusCode, signal) => {
-            clearTimeout(timer);
-            if (statusCode === 0) {
-                resolve({ process: proc, stdout, stderr });
-            }
-            else {
-                const errorMessage = `Harper process failed with exit code/signal ${statusCode ?? signal}`;
-                stderrStream?.write(errorMessage);
-                reject(new HarperStartupError(errorMessage, stdout, stderr));
-            }
-            stdoutStream?.end();
-            stderrStream?.end();
-        });
-    });
-}
-/**
- * Sets up a Harper instance with a component pre-installed from a local directory.
- *
- * Copies `fixturePath` into `{dataRootDir}/components/{name}` before Harper starts,
- * so the component is available on the first request without a post-startup deploy.
- * Use this when tests need a known route available at startup (e.g. mTLS cert tests).
- *
- * @param ctx - The test context to populate with Harper instance details
- * @param fixturePath - Absolute path to the component directory to pre-install
- * @param options - Optional configuration for the setup process
- */
-export async function setupHarperWithFixture(ctx, fixturePath, options) {
-    const dataRootDirPrefix = join(process.env.HARPER_INTEGRATION_TEST_INSTALL_PARENT_DIR || tmpdir(), 'harper-integration-test-');
-    const dataRootDir = await mkdtemp(dataRootDirPrefix);
-    await cp(fixturePath, join(dataRootDir, 'components', basename(fixturePath)), { recursive: true });
-    ctx.harper = { dataRootDir };
-    return startHarper(ctx, options);
-}
-/**
- * Sets up and starts a Harper instance for testing.
- *
- * @param ctx - The test context to populate with Harper instance details
- * @param options - Optional configuration for the setup process
- * @returns The context with the `harper` property populated
- *
- * @example
- * ```ts
- * suite('My tests', (ctx: ContextWithHarper) => {
- *   before(async () => {
- *     await startHarper(ctx);
- *   });
- *
- *   after(async () => {
- *     await teardownHarper(ctx);
- *   });
- *
- *   test('can connect', async () => {
- *     const response = await fetch(ctx.harper.httpURL);
- *     // ...
- *   });
- * });
- * ```
- */
-export async function startHarper(ctx, options) {
-    const dataRootDirPrefix = join(process.env.HARPER_INTEGRATION_TEST_INSTALL_PARENT_DIR || tmpdir(), `harper-integration-test-`);
-    const dataRootDir = ctx.harper?.dataRootDir ?? (await mkdtemp(dataRootDirPrefix));
-    const loopbackAddress = ctx.harper?.hostname ?? (await getNextAvailableLoopbackAddress());
-    // Set up per-suite log directory when HARPER_INTEGRATION_TEST_LOG_DIR is configured
-    const logDirEnv = process.env.HARPER_INTEGRATION_TEST_LOG_DIR;
-    let logDir;
-    if (logDirEnv) {
-        const suiteName = sanitizeForFilesystem(ctx.name || 'unknown');
-        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-        logDir = join(logDirEnv, `${suiteName}-${sanitizeForFilesystem(loopbackAddress)}-${timestamp}`);
-        await mkdir(logDir, { recursive: true });
-        // Output for the test runner (e.g. run.ts) to map this log dir to the current test file
-        process.stdout.write(`${LOG_DIR_MARKER_PREFIX} ${logDir}\n`);
-    }
-    // Point Harper's log directory to the suite log dir so hdb.log is preserved for upload
-    const config = { ...options?.config };
-    if (logDir) {
-        config.logging = { ...config.logging, root: logDir };
-    }
-    const args = [
-        `--ROOTPATH=${dataRootDir}`,
-        `--AUTHENTICATION_AUTHORIZELOCAL=true`,
-        `--HDB_ADMIN_USERNAME=${DEFAULT_ADMIN_USERNAME}`,
-        `--HDB_ADMIN_PASSWORD=${DEFAULT_ADMIN_PASSWORD}`,
-        '--THREADS_COUNT=1',
-        '--THREADS_DEBUG=false',
-        `--NODE_HOSTNAME=${loopbackAddress}`,
-        `--HTTP_PORT=${loopbackAddress}:${HTTP_PORT}`,
-        `--OPERATIONSAPI_NETWORK_PORT=${loopbackAddress}:${OPERATIONS_API_PORT}`,
-        `--MQTT_NETWORK_PORT=${loopbackAddress}:${MQTT_PORT}`,
-        `--MQTT_NETWORK_SECUREPORT=${loopbackAddress}:${MQTTS_PORT}`,
-        '--LOGGING_LEVEL=debug',
-        '--LOGGING_STDSTREAMS=false',
-    ];
-    // Bind secure port if HTTPS is needed (mTLS or other TLS config present)
-    if (options?.config?.http?.mtls !== undefined || options?.config?.tls !== undefined) {
-        args.push(`--HTTP_SECUREPORT=${loopbackAddress}:${HTTPS_PORT}`);
-    }
-    // HARPER_SET_CONFIG must be passed as an environment variable, not a CLI arg,
-    // because applyRuntimeEnvVarConfig reads from process.env.HARPER_SET_CONFIG
-    const harperEnv = {
-        HARPER_SET_CONFIG: JSON.stringify(config),
-        ...options?.env,
-    };
-    const result = await runHarperCommand({
-        args,
-        env: harperEnv,
-        completionMessage: 'successfully started',
-        logDir,
-        harperBinPath: options?.harperBinPath,
-        timeoutMs: options?.startupTimeoutMs,
-    });
-    ctx.harper = {
-        dataRootDir,
-        admin: {
-            username: DEFAULT_ADMIN_USERNAME,
-            password: DEFAULT_ADMIN_PASSWORD,
-        },
-        httpURL: `http://${loopbackAddress}:${HTTP_PORT}`,
-        operationsAPIURL: `http://${loopbackAddress}:${OPERATIONS_API_PORT}`,
-        hostname: loopbackAddress,
-        process: result.process,
-        logDir,
-        startupOutput: { stdout: result.stdout, stderr: result.stderr },
-    };
-    return ctx;
-}
-/**
- * Kill harper process (can be used for teardown, or killing it before a restart)
- * @param ctx
- */
-export async function killHarper(ctx) {
-    if (!ctx.harper?.process)
-        return;
-    await new Promise((resolve) => {
-        let timer;
-        ctx.harper.process.on('exit', () => {
-            resolve();
-            clearTimeout(timer);
-        });
-        ctx.harper.process.kill();
-        timer = setTimeout(() => {
-            try {
-                ctx.harper.process.kill('SIGKILL');
-            }
-            catch {
-                // possible that the process terminated but the exit event hasn't fired yet
-            }
-            resolve();
-        }, 200);
-    });
-}
-/**
- * Tears down a Harper instance and cleans up all resources.
- *
- * This function stops the Harper instance, releases the loopback address,
- * and removes the installation directory.
- * @param ctx - The test context with Harper instance details
- *
- * @example
- * ```ts
- * suite('My tests', (ctx: ContextWithHarper) => {
- *   before(async () => {
- *     await startHarper(ctx);
- *   });
- *
- *   after(async () => {
- *     await teardownHarper(ctx);
- *   });
- * });
- * ```
- */
-export async function teardownHarper(ctx) {
-    if (!ctx.harper)
-        return;
-    await killHarper(ctx);
-    await releaseLoopbackAddress(ctx.harper.hostname);
-    // a few retries are typically necessary, might take a sec for a process to finish, especially since rocksdb may be flushing
-    try {
-        await rm(ctx.harper.dataRootDir, { recursive: true, force: true, maxRetries: 10 });
-    }
-    catch (error) {
-        console.error('Error removing directory', error);
-    }
-}
-export async function sendOperation(context, operation) {
-    const response = await fetch(context.operationsAPIURL, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(operation),
-    });
-    const responseData = await response.json();
-    equal(response.status, 200, JSON.stringify(responseData));
-    return responseData;
-}
-//# sourceMappingURL=harperLifecycle.js.map