@harperfast/integration-testing 0.1.0 → 0.2.0

package/dist/harperLifecycle.d.ts

@@ -0,0 +1,156 @@
+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;
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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/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/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>;

package/dist/run.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/targz.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Packs and compresses a directory into a base64-encoded tar.gz string.
+ *
+ * @param dirPath path to directory to pack and compress
+ */
+export declare function targz(dirPath: string): Promise<string>;

package/package.json

@@ -1,12 +1,14 @@
 {
 	"name": "@harperfast/integration-testing",
-	"version": "0.1.0",
+	"version": "0.2.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",
 	"exports": {
-		".": "./src/index.ts",
-		"./run": "./src/scripts/run.ts"
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
 	},
 	"bin": {
 		"harper-integration-test-run": "dist/run.js",