@harperfast/integration-testing 0.1.0 → 0.3.0-0

package/dist/src/harperLifecycle.js

@@ -0,0 +1,315 @@
+import { spawn, ChildProcess } from 'node:child_process';
+import { createWriteStream, existsSync, rmSync } from 'node:fs';
+import { join, basename } 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;
+export const OPERATIONS_API_PORT = 9925;
+export const DEFAULT_ADMIN_USERNAME = 'admin';
+export const DEFAULT_ADMIN_PASSWORD = 'Abc1234!';
+export const DEFAULT_STARTUP_TIMEOUT_MS = process.env.HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS
+    ? parseInt(process.env.HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS, 10)
+    : 30000;
+const LOG_DIR = process.env.HARPER_INTEGRATION_TEST_LOG_DIR;
+/**
+ * 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
+ *
+ * @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
+    }
+    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`);
+}
+/**
+ * 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);
+}
+/**
+ * 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 {AssertionError} If the command exits with a non-zero status code
+ */
+function runHarperCommand({ args, env, completionMessage, logDir, harperBinPath, }) {
+    const harperScript = getHarperScript(harperBinPath);
+    const proc = spawn('node', ['--trace-warnings', '--force-node-api-uncaught-exceptions-policy=true', harperScript, ...args], {
+        env: { ...process.env, ...env },
+    });
+    let stdoutStream;
+    let stderrStream;
+    if (logDir) {
+        stdoutStream = createWriteStream(join(logDir, 'stdout.log'));
+        stderrStream = createWriteStream(join(logDir, 'stderr.log'));
+    }
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        let timer = setTimeout(() => {
+            let errorMessage = `Harper process timed out after ${DEFAULT_STARTUP_TIMEOUT_MS}ms`;
+            if (stdout) {
+                errorMessage += `\n\nstdout:\n${stdout}`;
+            }
+            if (stderr) {
+                errorMessage += `\n\nstderr:\n${stderr}`;
+            }
+            reject(errorMessage);
+            proc.kill();
+        }, DEFAULT_STARTUP_TIMEOUT_MS);
+        proc.stdout?.on('data', (data) => {
+            const dataString = data.toString();
+            stdoutStream?.write(data);
+            if (completionMessage && dataString.includes(completionMessage)) {
+                clearTimeout(timer);
+                resolve(proc);
+            }
+            stdout += dataString;
+        });
+        proc.stderr?.on('data', (data) => {
+            stderrStream?.write(data);
+            stderr += data.toString();
+        });
+        proc.on('error', (error) => {
+            reject(error);
+        });
+        proc.on('exit', (statusCode, signal) => {
+            clearTimeout(timer);
+            if (statusCode === 0) {
+                resolve(proc);
+            }
+            else {
+                let errorMessage = `Harper process failed with exit code/signal ${statusCode ?? signal}`;
+                stderrStream?.write(errorMessage);
+                if (stderr) {
+                    errorMessage += `\n\nstderr:\n${stderr}`;
+                }
+                reject(errorMessage);
+            }
+            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
+    let logDir;
+    if (LOG_DIR) {
+        const suiteName = sanitizeForFilesystem(ctx.name || 'unknown');
+        logDir = join(LOG_DIR, `${suiteName}-${sanitizeForFilesystem(loopbackAddress)}`);
+        await mkdir(logDir, { recursive: true });
+    }
+    // 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 };
+        // Clean up log directory on successful exit — only keep logs when tests fail
+        process.on('exit', (code) => {
+            if (code === 0) {
+                try {
+                    rmSync(logDir, { recursive: true, force: true });
+                }
+                catch { }
+            }
+        });
+    }
+    const args = [
+        `--ROOTPATH=${dataRootDir}`,
+        '--DEFAULTS_MODE=dev',
+        `--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}`,
+        '--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 harperProcess = await runHarperCommand({
+        args,
+        env: harperEnv,
+        completionMessage: 'successfully started',
+        logDir,
+        harperBinPath: options?.harperBinPath,
+    });
+    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: harperProcess,
+        logDir,
+    };
+    return ctx;
+}
+/**
+ * Kill harper process (can be used for teardown, or killing it before a restart)
+ * @param ctx
+ */
+export async function killHarper(ctx) {
+    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) {
+    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
+    await rm(ctx.harper.dataRootDir, { recursive: true, force: true, maxRetries: 4 });
+}
+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

package/dist/src/harperLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harperLifecycle.js","sourceRoot":"","sources":["../../src/harperLifecycle.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { startHarper, setupHarperWithFixture, killHarper, teardownHarper, sendOperation, createHarperContext, OPERATIONS_API_PORT, DEFAULT_ADMIN_USERNAME, DEFAULT_ADMIN_PASSWORD, DEFAULT_STARTUP_TIMEOUT_MS, type StartHarperOptions, type HarperContext, type HarperTestContext, type StartedHarperTestContext, type ContextWithHarper, } from './harperLifecycle.ts';
+export { validateLoopbackAddressPool, getNextAvailableLoopbackAddress, releaseLoopbackAddress, releaseAllLoopbackAddressesForCurrentProcess, } from './loopbackAddressPool.ts';
+export { targz } from './targz.ts';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { startHarper, setupHarperWithFixture, killHarper, teardownHarper, sendOperation, createHarperContext, OPERATIONS_API_PORT, DEFAULT_ADMIN_USERNAME, DEFAULT_ADMIN_PASSWORD, DEFAULT_STARTUP_TIMEOUT_MS, } from "./harperLifecycle.js";
+export { validateLoopbackAddressPool, getNextAvailableLoopbackAddress, releaseLoopbackAddress, releaseAllLoopbackAddressesForCurrentProcess, } from "./loopbackAddressPool.js";
+export { targz } from "./targz.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,GAM1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACN,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,4CAA4C,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/loopbackAddressPool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * This method attempts to validate all loopback addresses in the pool by trying to
+ * bind to each one. It returns an object containing arrays of successfully bound
+ * loopback addresses and those that failed along with their errors.
+ *
+ * It will check all loopback addresses from 127.0.0.1 to 127.0.0.32 (by default).
+ *
+ * Use the HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT environment variable to
+ * adjust the number of loopback addresses to validate (up to 255).
+ */
+export declare function validateLoopbackAddressPool(): Promise<{
+    successful: string[];
+    failed: {
+        loopbackAddress: string;
+        error: Error;
+    }[];
+}>;
+/**
+ * Retrieves the next available loopback address from the pool using a file-based
+ * locking mechanism to safely allocate addresses across concurrent test processes.
+ *
+ * **How it works:**
+ * 1. Acquires a file-based lock to prevent race conditions with other processes
+ * 2. Reads the pool state (a JSON array of process IDs, with null for available slots)
+ * 3. Finds the first available (null) slot and assigns the current process PID to it
+ * 4. Writes the updated pool back to disk and releases the lock
+ * 5. Validates that the allocated address can actually be bound to
+ * 6. Returns the loopback address (e.g., "127.0.0.2")
+ *
+ * If no addresses are available, waits and retries until one becomes available.
+ *
+ * **Pool file location:** `${tmpdir()}/harper-integration-test-loopback-pool.json`
+ * **Lock file location:** `${tmpdir()}/harper-integration-test-loopback-pool.lock`
+ *
+ * @returns A promise that resolves with an allocated loopback address
+ * @throws {LoopbackAddressValidationError} If the allocated address cannot be bound to
+ */
+export declare function getNextAvailableLoopbackAddress(): Promise<string>;
+/**
+ * Releases a loopback address back to the pool, making it available for other processes.
+ *
+ * @param address The loopback address to release (e.g., "127.0.0.1")
+ * @throws InvalidLoopbackAddressError if the address format is invalid
+ */
+export declare function releaseLoopbackAddress(address: string): Promise<void>;
+/**
+ * Releases all loopback addresses assigned to the current process.
+ * Useful for cleanup during graceful shutdown.
+ */
+export declare function releaseAllLoopbackAddressesForCurrentProcess(): Promise<void>;