Test Helpers

This page documents the shared helper module behind the live integration suite.

It is the best place to look when you need to answer questions like:

  • which environment variables are required or optional for live coverage

  • how reusable versus temporary GoodMem resources are chosen

  • where cleanup happens

  • how the tests wait for eventually consistent retrieval results

  • how compatible embedders are reused or provisioned for live bootstrap and embeddings coverage

One subtle but important rule lives here: GOODMEM_VERIFY is interpreted only by the live-test helpers, not by GoodMemConnection.from_env().

Live integration-test helpers and environment contract.

This module centralizes the resource lifecycle and environment policy for the repository’s live GoodMem tests.

Required base environment:

  • GOODMEM_API_KEY

  • GOODMEM_BASE_URL

Optional reuse controls:

  • GOODMEM_SPACE_ID to reuse an existing space for existing-space coverage

  • GOODMEM_EMBEDDER_ID to reuse an existing compatible embedder

Optional auto-provisioning inputs for embeddings coverage:

  • GOODMEM_EMBEDDINGS_API_KEY

  • GOODMEM_EMBEDDINGS_BASE_URL

  • GOODMEM_EMBEDDINGS_MODEL_IDENTIFIER

  • GOODMEM_EMBEDDINGS_DIMENSIONS

  • GOODMEM_EMBEDDINGS_PROVIDER_TYPE

Resource lifecycle:

  • existing resources referenced through environment variables are reused and not deleted

  • temporary spaces and embedders created by the tests are cleaned up at the end of the run

  • cleanup failures fail the test run so resource leaks stay visible

Additional behavior:

  • GOODMEM_VERIFY is parsed only here, not by GoodMemConnection.from_env

  • semantic retrieval is eventually consistent, so tests poll until the expected chunk becomes visible or the timeout is reached