v2: Integration test suite with TestContainers

[oss-amikos]

Context

We need a comprehensive integration test suite that runs against real ChromaDB instances via TestContainers. Tests should verify the full v2 API against multiple Chroma versions.

Requirements

Test Infrastructure

• TestContainers with chromadb/chroma Docker image
• Parameterized tests across Chroma versions: latest (primary), 0.6.x (minimum v2 support)
• JUnit 5 with @Testcontainers extension
• Shared container per test class (start once, reset between tests)

Test Categories

Client lifecycle tests:

• Client creation with various builder configurations
• Heartbeat and version
• Reset
• Client close (AutoCloseable)

Tenant/Database tests:

• Create, get tenant
• Create, get, list, delete database

Collection CRUD tests:

• Create collection (with and without options)
• Get collection by name
• Get or create collection (create path and get path)
• List collections (with pagination)
• Count collections
• Delete collection
• Create collection with HNSW configuration
• Modify collection name and metadata

Record operation tests:

• Add records (ids + embeddings, ids + embeddings + documents + metadata)
• Get by IDs
• Get with Where filter
• Get with pagination (limit/offset)
• Query by embeddings
• Query by text (when embedding function available)
• Query with Where and WhereDocument filters
• Update records
• Upsert records (insert path and update path)
• Delete by IDs
• Delete by Where filter
• Count records

Where filter tests:

• eq, ne, gt, gte, lt, lte with string/int/float values
• in, nin
• and, or combinators
• Nested logical expressions
• WhereDocument contains/notContains

Error handling tests:

• Create duplicate collection → appropriate exception
• Get non-existent collection → ChromaNotFoundException
• Invalid query (no embeddings or texts) → IllegalArgumentException
• Server unreachable → ChromaConnectionException

CI Workflow

Single workflow file (not 4 like PR #80):

• Triggered on: push to main, PR to main
• Matrix: Chroma latest + Java 11, 17
• TestContainers handles Docker

Acceptance Criteria

• Test infrastructure with TestContainers
• Tests for all client operations
• Tests for all collection operations
• Tests for all record operations
• Tests for Where/WhereDocument filtering
• Tests for error conditions
• CI workflow running tests on push/PR
• All tests pass against Chroma latest

Depends On

• v2: Implement ChromaClient (Client interface) — collection CRUD, tenant/database ops #89 (ChromaClient implementation)
• v2: Implement Collection record operations — add, query, get, update, upsert, delete #90 (Record operations implementation)

[oss-amikos]

Implemented in #114 (merged): v2 integration test suite and CI integration flow are now in place.