HarperFast / HarperFast/harper
Refactor new integration tests: use fixture directories + setupHarperWithFixture, reorganize to docs-mirrored structure
- Dominant language
- JavaScript
- Stars
- 89
- Forks
- 10
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 200
Description
## 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//` 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):
- #1209 `components/mqtt.test.ts` → `mqtt/mqtt.test.ts` + fixture dir
- #1210 `apiTests/ttl.test.ts` → `database/ttl.test.ts` + fixture dir
- #1211 `apiTests/custom-resources.test.ts` → `resources/custom-resources.test.ts` + fixture dir
- #1208 `server/caching.test.ts` — already in a reasonable location; migrate to fixture dir
## References
- Ethan Arrowood comment: https://github.com/HarperFast/harper/pull/1211#pullrequestreview-4459578943
- 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.
Contributor guide
Assessment
This issue has not been assessed yet.