Refactor new integration tests: use fixture directories + setupHarperWithFixture, reorganize to docs-mirrored structure

[kriszyp]

Background

PR #1211 review (Ethan Arrowood) identified two cross-cutting issues with the integration tests added in PRs #1207–#1211:

Issue 1: Inline component definitions should be fixture directories

Tests in #1208 (#1189), #1209 (#1188), #1210 (#1191), #1211 (#1190) all define component code (schema.graphql, resources.js, config.yaml) as inline string literals inside the test file.

Why this is a problem (Ethan): "If I need to debug something, I want to be able to run Harper directly on the fixture to manually validate what's going on. Storing fixture sources in-line is incompatible with that."

Fix: Move each inline component definition to integrationTests/fixtures/<name>/ as real files.

Issue 2: Using old installAppComponent helper instead of setupHarperWithFixture

The new tests use installAppComponent from integrationTests/apiTests/utils/components.mjs (the old/migrated pattern). The integration-testing framework now provides setupHarperWithFixture(ctx, fixturePath, options) which is the recommended API.

Fix: Migrate all new tests to use setupHarperWithFixture from @harperfast/integration-testing.

Reference: https://github.com/harperfast/integration-testing#setupharperwithfixturectx-fixturepath-options

Issue 3: Directory reorganization

integrationTests/apiTests/ is becoming a catch-all bucket. The v5 docs (docs.harperdb.io/reference/v5) suggest a cleaner structure:

integrationTests/
  database/       ← schema types, TTL, blob, scale  (from apiTests/)
  resources/      ← custom resources, REST API       (from apiTests/)
  mqtt/           ← MQTT broker tests                (from components/)
  security/       ← auth, JWT, certs                 (from apiTests/ + security/)
  operations-api/ ← operations, CLI                  (from apiTests/)
  server/         ← caching, thread management       (already exists)
  components/     ← component deployment             (already exists)
  upgrade/        ← v4→v5 upgrade tests              (already exists)
  replication/    ← cluster / replication tests      (harper-pro)

Fix: Move the files added in #1207–#1211 to the new structure. Existing apiTests/ files can be migrated gradually in follow-up PRs.

Scope

PRs to refactor (after they merge):

• test(integration): MQTT suite for %u substitution, anonymousSubscriber, SYS_CON, RS256 #1209 components/mqtt.test.ts → mqtt/mqtt.test.ts + fixture dir
• test: TTL edge-case integration tests #1210 apiTests/ttl.test.ts → database/ttl.test.ts + fixture dir
• test(integration): custom jsResource patterns (#1190) #1211 apiTests/custom-resources.test.ts → resources/custom-resources.test.ts + fixture dir
• test: integration tests for sourcedFrom and allowStaleWhileRevalidate #1208 server/caching.test.ts — already in a reasonable location; migrate to fixture dir

References

• Ethan Arrowood comment: test(integration): custom jsResource patterns (#1190) #1211 (review)
• integration-testing framework docs: https://github.com/harperfast/integration-testing#setupharperwithfixturectx-fixturepath-options
• v5 reference docs: https://docs.harperdb.io/reference/v5

Note: setupHarperWithFixture readiness probe pattern

When migrating from installAppComponent to setupHarperWithFixture, add a readiness poll after setup. setupHarperWithFixture pre-copies the fixture before Harper starts, so Harper emits successfully started while HTTP worker route registration is still completing async. installAppComponent handled this implicitly via restart_service http_workers + poll.

Use restartHttpWorkers(client, '/YourFirstTable/') immediately after setupHarperWithFixture to bridge the gap before making test assertions.