Integration test overhaul

[Ethan-Arrowood]

Integration Test Overhaul

This PR introduces a comprehensive overhaul of Harper's integration testing infrastructure, enabling concurrent test execution for faster feedback cycles and improved developer productivity.

Overview of Changes

New Integration Test Framework:

• Created a new integration test framework based on Node.js Test Runner with full support for concurrent test execution
• Implemented loopback address pooling to enable true test isolation - each test file gets its own Harper instance on a unique network address
• Added comprehensive utilities for Harper lifecycle management (setupHarper, teardownHarper) with automatic resource cleanup
• Introduced new test structure requirements: test files must be independent, hermetic, and deterministic

Documentation:

• Added extensive documentation in integrationTests/README.md covering test writing guidelines, execution strategies, and best practices
• Created detailed utility documentation in integrationTests/utils/README.md
• Updated CONTRIBUTING.md with new integration test setup requirements

CI/CD Improvements:

• Replaced single integration test workflow with new parallelized workflow supporting test sharding across multiple runners
• Build artifacts are now cached and reused across test jobs for faster execution
• Added support for selective Node.js version testing and test sharding (1/4, 2/4, 3/4, 4/4)
• Separated legacy API tests from new integration tests with dedicated workflows

New Test Infrastructure:

• Implemented loopback address pool manager for concurrent test execution without port conflicts
• Created reusable Harper lifecycle utilities with configurable installation directories and network settings
• Added helper utilities for tar.gz compression, required for application deployment tests
• Included setup script for configuring loopback addresses on macOS and Linux

Example Tests:

• Added deployment tests demonstrating the new testing patterns:
  • deploy-from-source.test.mts - Deploy application from compressed source
  • deploy-from-github.test.mts - Deploy application from GitHub repository

Additional Changes:

• Updated ESLint config to allow floating promises in test files for async test functions
• Fixed minor issues in logging and user utilities for better compatibility

How to Review

1. Start with the documentation - Read integrationTests/README.md to understand the new testing philosophy, requirements, and execution strategies. This provides critical context for all other changes.

2. Review the utilities - Check integrationTests/utils/README.md and the utility implementations in integrationTests/utils/ to understand the building blocks available for writing tests.

3. Examine the test examples - Look at the deploy tests (deploy-from-source.test.mts and deploy-from-github.test.mts) as reference implementations showing how to use the new framework and utilities.

4. Review CI/CD changes - Check .github/workflows/integration-tests.yml to understand how tests are parallelized across runners and how sharding works.

5. Check supporting changes - Review smaller changes to source files (installer, logging, etc.) that support better test isolation and execution.

Testing

The new integration tests require loopback address configuration. Run the setup script if needed:

bash integrationTests/utils/scripts/setup-loopback.sh

Then execute tests:

npm run test:integration

[Ethan-Arrowood]

I need to cherry-pick the recent application lock fix to this repo and then I can uncomment this assertion.

[kriszyp]

This looks like it will be awesome, excited to see more tests brought in!

[heskew]

Generally this is pretty awesome and most of the feedback I've thought of would be non-blocking edge case handling and 'nice to haves' (e.g. loopback cleanup - i.e. leave no trace).

This (test utils especially) might be nice for others to use in their own Harper apps and components/plugins. Have you thought about publishing as a separate package?

[cb1kenobi]

This all looks really awesome! Great job!

[cb1kenobi]

You could use a regex instead of splitting.

Suggested change

	const parts = address.split('.');
	if (parts.length !== 4 || parts[0] !== '127' || parts[1] !== '0' || parts[2] !== '0') {
	throw new InvalidLoopbackAddressError(address);
	}
	const index = parseInt(parts[3], 10) - 1;
	const m = address.match(/^127\.0\.0\.(\d{1,3})$/);
	if (!m?.[1]) {
	throw new InvalidLoopbackAddressError(address);
	}
	const index = Number.parseInt(m[1], 10) - 1;

[Ethan-Arrowood]

Personally, I'm not a huge fan of using regex due to its readability. I understand it can be better performance but since this is just a util script I don't think I'm going to make this change.

[cb1kenobi]

Heh, I was thinking the regex was so simple that it would be more readable than the split version.

[Ethan-Arrowood]

#51 will fix the failing format check

[kriszyp]

Great work, let's start using it!