Skip to main content
Testing code that calls the Synap SDK falls into three patterns. Pick by how realistic you need the test to be.

1. Unit tests with mocks

Use this for testing your business logic that happens around Synap calls: prompt assembly, decision logic, response handling. Mock the SDK so the test is fast and deterministic and doesn’t need network.
Why use the real Pydantic models when mocking Constructing a real ContextResponse instead of MagicMock catches field-name typos at test-write time. If you later upgrade the SDK and a field is removed, the test fails loudly instead of silently passing on a mock that “accepts everything.”

2. FastAPI integration tests with dependency overrides

If you wired the SDK via Depends(get_sdk) (the recommended pattern in Setup → Integration), FastAPI’s app.dependency_overrides swaps it out per test.

3. End-to-end against a real test Instance

For the highest-fidelity tests (pre-release smoke tests, contract tests against new SDK versions) run against a dedicated test Instance in Synap Cloud.
Use _force_new=True in tests to bypass the SDK singleton The SDK keeps one live instance per API key. In tests where you want a fresh instance per test, opt out of that:
An SDK built this way is never registered as the singleton for its key, so tests can create and discard them freely: shutting one down won’t disturb an SDK your application already holds for the same key. For the same reason, nothing else will ever close it for you — await sdk.shutdown() in your fixture teardown, or each test leaks its own transports, streaming channel and cache handles for the rest of the run. Don’t reach for it in application code. You don’t need it to run several tenants in one process, because different API keys already give you separate SDKs (see Initialization). Every extra SDK pays for its own connections, streaming channel and cache handles. Use unique IDs per test Synap memories persist. Two tests that both ingest user_id="alice" will see each other’s data, and your assertions will be flaky. Always derive user_id, customer_id, conversation_id from uuid.uuid4() inside each test.

4. Snapshot testing of prompts

If your application generates LLM system prompts that incorporate Synap context, snapshot-test the rendered prompt to catch unintended drift.
Re-snapshot intentionally when you change prompt format; fail loudly when you change it by accident.

What to skip in tests

  • Don’t mock the SDK’s internal transport; mock its public methods. Mock the SDK methods (memories.create, context.fetch); those are your seams. Mocking the transport couples your tests to internal SDK structure that will change.
  • Don’t snapshot ContextResponse objects directly. They include timestamps and correlation IDs that change every run. Snapshot the prompt string you assemble from them.
  • Don’t share user_ids across tests. Synap memories are real and persist; cross-test pollution will bite.