HarperFast / HarperFast/harper

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

Open
#1,215 0 comments 0 reactions 1 assignee Claimed by @kriszyp View on GitHub
claude-fix:test tests
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.