ready for review?

Author: Ethan-Arrowood

CONTRIBUTING.md

@@ -15,7 +15,7 @@ Install dependencies using `npm install`
 
 Build the project using `npm run build` or `npm run build:watch` to automatically rebuild on file changes.
 
-Run integration tests using `npm run test:integration`. Make sure to read the [integration test instructions](./integrationTests/apiTests/README.md) for setup.
+Run integration tests using `npm run test:integration`. Make sure to read the [integration test instructions](./integrationTests/README.md) for setup requirements (particularly the loopback address configuration).
 
 Run unit tests using `npm run test:unit <unit-test-file>` or `npm run test:unit:all`, but make sure to build the project first since unit tests depend on the built source files.
 

integrationTests/README.md

@@ -3,6 +3,7 @@
 We prioritize performance at Harper, and that extends to core developer experience and productivity. Harper is a significantly complex application involving multiple processes, threads, file I/O, database operations, network calls, and so much more. Integration tests differ from unit test as they **must run against the built distribution of Harper as if it was a user or another system** (instead of importing source/built code directly). As a result, integration tests will be as resource intensive as the Harper system is.
 
 In order to keep things as fast as possible, integration test **files** must be:
+
 - **Independent**: Test files do not depend on execution order or state from other test files
 - **Hermetic**: Test files are self-contained with no external side-effects
 - **Deterministic**: The same input always produces the same output, no matter how many times its executed
@@ -13,9 +14,9 @@ If we follow these guidelines strictly, we can execute integration tests concurr
 
 This directory contains integration tests migrated from our old repository. These test are incredibly important and are one of the most important ways we've verified the Harper application continues to work throughout the open source transfer. Unfortunately, these tests are very interdependent and cannot be run separately from each other. The setup in early test files is necessary for most other test files to work, and some tests (spread across multiple files) interact with the same resources and data and in some circumstances must be executed in a certain order. This interdependence has made it very difficult, if not impossible, for developers to isolated failing tests during development.
 
-These tests should be generally excluded from our new integration testing guidelines while they are actively ported to new implementations. They are automatically ignored by the `test:integration` script, and can be executed using the `test:integration:apiTests` npm script instead.
+These tests should be generally excluded from our new integration testing guidelines while they are actively ported to new implementations. They are automatically ignored by the `test:integration` script, and can be executed using the `test:integration:api-tests` npm script instead.
 
-Complete documentation for configuring and executing these tests is available [here](./apiTests/README.md).
+These tests have their own unique configuration and setup requirements that differ from the newer integration test guidelines.
 
 ## Running Tests
 
@@ -24,11 +25,13 @@ Complete documentation for configuring and executing these tests is available [h
 >
 > Linux Ubuntu systems generally have 127.0.0.1 - 127.255.255.255 enabled by default, but MacOS and Windows does not.
 >
-> Use the included script `integrationTests/setup-loopback.sh` to quickly enable the required set of loopback addresses.
+> Use the included script `integrationTests/utils/scripts/setup-loopback.sh` to quickly enable the required set of loopback addresses.
 >
 > This script does require `sudo` permissions. We recommend reviewing the source before executing.
+>
+> The script respects the `HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT` environment variable (defaults to 32) to configure the number of loopback addresses. The integration test runner will automatically validate that the required loopback addresses are available before running tests and will exit with an error if they are not configured.
 
-The Node.js test runner uses process isolation to run test files concurrently _by default_. Meaning, `node --test "integrationTests/*.test.ts"` will run every matched file in its own process. Node.js determines the number of concurrent processes using `os.availableParallelism() - 1`. Since Harper is itself a resource intensive application, this default concurrency causes extreme resource contention and system thrashing as each integration test file is also running at least one more process, the Harper application, plus whatever additional work the Harper application does as part of the tests. Through deep analysis, we have determine a safer default concurrency for our circumstances is slightly more than half of the available parallelism. For more information see [Node.js Test Runner Parallelization Analysis](https://github.com/Ethan-Arrowood/node-test-runner-parallelization-analysis). Thus, using `node --test` to run _all_ integration tests is insufficient. We include a npm script `test:integration` for simplified execution. The `node --test` command can still be used to run an individual test file, or at most a small set of test files, but we recommend using `test:integration` whenever possible.
+The Node.js test runner uses process isolation to run test files concurrently _by default_. Meaning, `node --test "integrationTests/*.test.mts"` will run every matched file in its own process. Node.js determines the number of concurrent processes using `os.availableParallelism() - 1`. Since Harper is itself a resource intensive application, this default concurrency causes extreme resource contention and system thrashing as each integration test file is also running at least one more process, the Harper application, plus whatever additional work the Harper application does as part of the tests. Through deep analysis, we have determine a safer default concurrency for our circumstances is slightly more than half of the available parallelism. For more information see [Node.js Test Runner Parallelization Analysis](https://github.com/Ethan-Arrowood/node-test-runner-parallelization-analysis). Thus, using `node --test` to run _all_ integration tests is insufficient. We include a npm script `test:integration` for simplified execution. The `node --test` command can still be used to run an individual test file, or at most a small set of test files, but we recommend using `test:integration` whenever possible.
 
 The `test:integration` script will execute **all integration tests by default** using the safe concurrency settings as described above.
 
@@ -46,18 +49,19 @@ For example:
 
 ```sh
 # Supports exact file paths
-npm run test:integration -- "integrationTests/install.test.ts"
+npm run test:integration -- "integrationTests/deploy/deploy-from-source.test.mts"
 # Or glob patterns
-npm run test:integration -- "integrationTests/applicationLifecycle/*.test.ts"
+npm run test:integration -- "integrationTests/deploy/*.test.mts"
 # Or multiple entries
-npm run test:integration -- "integrationTests/install.test.ts" "integrationTests/start.test.ts" "integrationTests/stop.test.ts" 
+npm run test:integration -- "integrationTests/deploy/deploy-from-source.test.mts" "integrationTests/deploy/deploy-from-github.test.mts"
 ```
 
 ### Available options:
 
 All CLI arguments can be overridden using the associative `HARPER_INTEGRATION_TEST_*` environment variable where the `*` is replaced by the capitalized CLI argument name. For example, `--concurrency` is replaced by `HARPER_INTEGRATION_TEST_CONCURRENCY`.
 
 Configuration precedence order is:
+
 1. Environment Variables
 2. CLI Argument
 3. Default Value
@@ -126,7 +130,7 @@ This option can be overridden using the `HARPER_INTEGRATION_TEST_ONLY` environme
 
 As mentioned in the introduction, integration test **files** should be **independent**, **hermetic**, and **deterministic**.
 
-All files meant to be executed by the test runner should end in `.test.ts`. They can be nested within directories for organization purposes, or be top-level in this `integrationTests` directory. Every test file should begin with a comment block explaining exactly what it is meant to test.
+All files meant to be executed by the test runner should end in `.test.mts` (ES module TypeScript). They can be nested within directories for organization purposes, or be top-level in this `integrationTests` directory. Every test file should begin with a comment block explaining exactly what it is meant to test.
 
 Tests must use the Node.js Test Runner API [`node:test`]() for establishing suites (`describe` or `suite`), tests (`it` or `test`), and lifecycle methods (`before`, `beforeEach`, `after`, and `afterEach`).
 
@@ -144,45 +148,30 @@ Since these tests interact with a running Harper instance directly, they often w
 - Network Responses
 - File System
 
-Reusable assertion patterns will develop over time. The [utilities](#utilities) section documents various helpers for things such as setting up and tearing down Harper instances, assertion patterns, and more. Familiarize yourself with this section as well as existing tests to best understand general testing patterns.
+Reusable assertion patterns will develop over time. Familiarize yourself with existing tests and the [Integration Test Utilities documentation](./utils/README.md) to best understand general testing patterns.
 
 ### Utilities
 
-#### `setupHarper(context): Promise<void>`
-
-- **context** - [`SuiteContext`]() | [`TestContext`]() - The context for a set of tests.
-
-This method should be used in the [`before()`]() function for a set of tests. It will create a Harper instance and assign relevant information to the `context.harper` object for use throughout the set of tests. **Do not forget** to call `teardownHarper(ctx)` in the `after()` function or you will have phantom Harper processes after the tests complete.
-
-For example,
-
-```ts
-suite('test suite', (ctx) => {
-	before(async () => {
-		await setupHarper(ctx);
-	});
-
-	after(async () => {
-		await teardownHarper(ctx);
-	});
+Integration test utilities are located in the [`integrationTests/utils/`](./utils/) directory and provide essential functionality for test setup, teardown, and common operations.
 
-	test('make a request', async () => {
-		// The `ctx.harper` object will have important information about the relative instance
-		const response = await fetch(ctx.harper.url);
-	});
-});
-```
+**Complete utilities documentation is available at [`integrationTests/utils/README.md`](./utils/README.md).**
 
-#### `teardownHarper(context): Promise<void>`
+#### Quick Reference
 
-- **context** - [`ContextWithHarper`](#contextwithharper) - A suite or test context object with the `harper` property from [`setupHarper()`]()
+The most commonly used utilities are:
 
-This method should be used in the [`after()`]() function in conjunction with the [`setupHarper()`]() and [`before()`]() methods. It will shutdown the relative Harper instance and remove it from the filesystem.
+- **`setupHarper(context)`** - Sets up a complete Harper instance for testing. Use in `before()` hooks.
+- **`teardownHarper(context)`** - Tears down a Harper instance and cleans up resources. Use in `after()` hooks.
+- **`ContextWithHarper`** - TypeScript interface for test context with Harper instance details.
+- **`targz(dirPath)`** - Compresses a directory into a base64-encoded tar.gz string for application deployment.
 
-For example,
+**Example usage:**
 
 ```ts
-suite('test suite', (ctx) => {
+import { suite, test, before, after } from 'node:test';
+import { setupHarper, teardownHarper, type ContextWithHarper } from './utils/harperLifecycle.mts';
+
+suite('test suite', (ctx: ContextWithHarper) => {
 	before(async () => {
 		await setupHarper(ctx);
 	});
@@ -191,23 +180,14 @@ suite('test suite', (ctx) => {
 		await teardownHarper(ctx);
 	});
 
-	test('make a request', async ( ) => {
-		// The `ctx.harper` object will have important information about the relative instance
-		const response = await fetch(ctx.harper.url);
+	test('make a request', async () => {
+		const response = await fetch(ctx.harper.httpURL);
+		// ... assertions
 	});
 });
 ```
 
-#### `ContextWithHarper`
-
-The interface assigned to a [`SuiteContext`]() or [`TestContext`]() object by [`setupHarper()`]() and necessary for [`teardownHarper()`]().
-
-Properties:
-- **url** - [`URL`]() - The URL instance for the Harper instance
-- **admin** - `object`
-  - **username** - `string` - The Harper Admin Username
-  - **password** - `string` - The Harper Admin Password
-- **rootpath** - `string` - The absolute path to the root of the Harper instance
+**For detailed documentation** including all available utilities, parameters, return types, configuration options, and advanced usage examples, see the [**Integration Test Utilities Documentation**](./utils/README.md).
 
 ### Test File Template
 
@@ -223,10 +203,10 @@ Copy and paste the following content to get started:
  */
 import { suite, test, before, after } from 'node:test';
 import { strictEqual } from 'node:assert/strict';
-// If this file is nested don't forget to update the path here
-import { setupHarper, teardownHarper } from './utils.mts';
+// Note: adjust the relative path accordingly (e.g., '../utils/harperLifecycle.mts')
+import { setupHarper, teardownHarper, type ContextWithHarper } from './utils/harperLifecycle.mts';
 
-suite('short description of tests', (ctx) => {
+suite('short description of tests', (ctx: ContextWithHarper) => {
 	before(async () => {
 		await setupHarper(ctx);
 	});
@@ -237,6 +217,7 @@ suite('short description of tests', (ctx) => {
 
 	test('test description', async () => {
 		// Use `ctx.harper` for access to the instance
+		// Example: const response = await fetch(ctx.harper.httpURL);
 	});
 });
 ```
@@ -277,7 +258,7 @@ suite('Concurrency Disabled', () => {
 - Suites always run sequentially so the **total run time for the file is ~3 seconds**
 
 ```
-❯ node --test example.test.ts 
+❯ node --test example.test.ts
 ▶ Concurrency Enabled
   ✔ 1 second (1001.359083ms)
   ✔ 1 second (1001.860375ms)

integrationTests/deploy/deploy-from-github.test.mts

@@ -1,6 +1,6 @@
 /**
  * Deploy an application from a GitHub repository.
- * 
+ *
  * Verifies application is deployed correctly and is accessible via both API and static site.
  */
 import { suite, test, before, after } from 'node:test';
@@ -43,7 +43,7 @@ suite('GitHub application deployment', (ctx: ContextWithHarper) => {
 		});
 		strictEqual(response.status, 200);
 		const body = await response.json();
-		deepStrictEqual(body, {"message":"Successfully deployed: test-application, restarting HarperDB"});
+		deepStrictEqual(body, { message: 'Successfully deployed: test-application, restarting HarperDB' });
 		await sleep(5000);
 		ok(existsSync(join(ctx.harper.installDir, 'components', project)));
 
@@ -63,7 +63,7 @@ suite('GitHub application deployment', (ctx: ContextWithHarper) => {
 		const response = await fetch(`${ctx.harper.httpURL}/Greeting`);
 		strictEqual(response.status, 200);
 		const body = await response.json();
-		deepStrictEqual(body, { greeting: "Hello, world!" });
+		deepStrictEqual(body, { greeting: 'Hello, world!' });
 	});
 
 	test('access application static site', async () => {

integrationTests/deploy/deploy-from-source.test.mts

@@ -1,10 +1,10 @@
 /**
  * Local application deployment test.
- * 
+ *
  * Deploys an application from a fixture directory using the `payload` parameter of
  * the `deploy_component` Operations API call. Verifies that the application is
  * deployed correctly and can be accessed via HTTP.
- * 
+ *
  */
 import { suite, test, before, after } from 'node:test';
 import { deepStrictEqual, ok, strictEqual } from 'node:assert/strict';
@@ -46,7 +46,7 @@ suite('Local application deployment', (ctx: ContextWithHarper) => {
 		});
 		strictEqual(response.status, 200);
 		const body = await response.json();
-		deepStrictEqual(body, {"message":"Successfully deployed: test-application, restarting HarperDB"});
+		deepStrictEqual(body, { message: 'Successfully deployed: test-application, restarting HarperDB' });
 		await sleep(5000);
 		ok(existsSync(join(ctx.harper.installDir, 'components', project)));
 		ok(existsSync(join(ctx.harper.installDir, 'harper-application-lock.json')));

integrationTests/deploy/fixture/web/about.html

@@ -1,11 +1,11 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-	<meta charset="UTF-8">
-	<meta name="viewport" content="width=device-width, initial-scale=1.0">
-	<title>About Page</title>
-</head>
-<body>
-	<h1>About Page</h1>
-</body>
-</html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>About Page</title>
+	</head>
+	<body>
+		<h1>About Page</h1>
+	</body>
+</html>