Integration Testing Guide

What counts as an integration test here?

An integration test should:

• create a real index (filesystem or in-memory, depending on surface)
• drive Searchlite through a public interface (CLI args or HTTP requests)
• validate observable behavior (hits, counts, errors, lifecycle)

Avoid “testing internals through integration.” If you need to validate internals, write a unit test.

Core end-to-end flows to cover

HTTP flow (minimum happy path)

1. Start server on ephemeral port bound to localhost.
2. POST /init with schema JSON.
3. POST /add with NDJSON (or POST /bulk with JSON).
4. POST /commit.
5. POST /refresh (unless refresh-on-commit is enabled).
6. POST /search with return_stored: true.
7. GET /stats and GET /inspect sanity assertions.
8. POST /compact then re-check stats/inspect invariants.

Assertions that matter:

• status codes
• error payload shape: {"error":{"type":"...","reason":"..."}}
• stats documents/segments move in expected direction
• search returns _id and stored fields when requested
• highlight presence when requested

CLI flow (minimum happy path)

1. init <index> <schema>
2. add <index> <docs.ndjson>
3. commit <index>
4. search <index> ...
5. inspect <index>
6. compact <index>

Recommended harness:

• assert_cmd + temp directories
• parse JSON output and assert on structure not just string contains

Integration tests for “easy to break” features

Filters + fast fields

• Ensure filtering on keyword + numeric fields works only when fast: true.
• Include at least one negative case (filter on non-fast field returns an error or empty, depending on contract).

Aggregations

• Terms agg on a fast keyword field
• Percentiles/stats on a fast numeric field
• Composite pagination (assert after_key behavior if exposed)

Nested fields

• Nested filter that requires binding to the same nested object
• Deeper nested (nested inside nested) if supported

Debug flags (HTTP/JSON API)

• explain: true returns a score breakdown blob
• profile: true returns timing/stats fields
• assert flags are off by default (no extra fields unless requested)

Execution modes

• Same query under bm25, wand, bmw returns same top-k doc ids for deterministic fixtures
• (allow differences only if the contract explicitly permits)

Vector search (feature-gated)

• Guard with #[cfg(feature = "vectors")]
• Assert dimension mismatch errors
• Assert vector_score presence when vector path runs

Resource-limit and shutdown coverage (HTTP)

These are common production footguns; cover at least one:

• max body bytes (expect rejection when exceeded)
• request timeout (simulate with slow client / large payload)
• max concurrency (hammer with parallel requests; expect graceful rejection/backpressure)
• shutdown grace (if the test harness can trigger shutdown)

Determinism rules (don’t write flaky tests)

• Use fixed doc IDs and small, explicit corpora.
• Avoid time-based assertions.
• When testing sampling, fix seeds and assert “shape” (e.g., sampled: true) rather than exact counts unless contract guarantees exactness.
• Sort results before comparing unless stable ordering is guaranteed by request sort.

Running and maintaining the suite

• Integration tests must pass with cargo test --all --all-features.
• Keep runtime reasonable:

- prefer small fixtures - avoid huge corpora - use targeted assertions