> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Maximem Synap is a managed memory layer for AI agents: it ingests conversations and documents, extracts structured memory, and returns scoped context to the agent at retrieval time.
> The Python and JavaScript/TypeScript SDKs are the supported way to use Synap. Write integration code with SDK calls, not raw HTTP requests.
> Start with the Quickstart: https://docs.maximem.ai/getting-started/quickstart.md. Every SDK method is documented in the SDK reference: https://docs.maximem.ai/sdk-reference/overview.md.
> For requests about adding Vity memory to OpenClaw, Hermes, an MCP client, or a browser, start with the Vity Quickstart: https://docs.maximem.ai/vity/quickstart.md.

# Testing

> Patterns for testing application code that depends on Synap: unit tests with mocks, fixtures, and integration tests against a real Instance.

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.

```python Python theme={null}
# tests/test_chat.py
import pytest
from unittest.mock import AsyncMock, MagicMock
from maximem_synap import ContextResponse, Fact, ResponseMetadata
from datetime import datetime, timezone

from myapp.chat import handle_turn       # your code under test


def make_fake_context(facts: list[str]) -> ContextResponse:
    """Build a realistic ContextResponse without hitting the network."""
    return ContextResponse(
        facts=[
            Fact(
                id=f"fact_{i}",
                content=content,
                confidence=0.9,
                source="test",
                extracted_at=datetime.now(timezone.utc),
            )
            for i, content in enumerate(facts)
        ],
        metadata=ResponseMetadata(
            correlation_id="test-corr-id",
            ttl_seconds=300,
            source="cloud",
            retrieved_at=datetime.now(timezone.utc),
        ),
    )


@pytest.fixture
def fake_sdk():
    sdk = MagicMock()
    sdk.conversation.context.fetch = AsyncMock(return_value=make_fake_context([]))
    sdk.memories.create = AsyncMock(return_value=MagicMock(ingestion_id="ing_test"))
    return sdk


async def test_handle_turn_uses_facts_in_prompt(fake_sdk):
    fake_sdk.conversation.context.fetch.return_value = make_fake_context(
        ["User prefers dark mode", "User is on the Pro plan"]
    )

    reply = await handle_turn(
        sdk=fake_sdk,
        user_id="user_test",
        customer_id="cust_test",
        conversation_id="3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        message="What plan am I on?",
    )

    # Assert the system prompt mentioned both retrieved facts
    call_args = fake_sdk.openai_client.chat.completions.create.call_args  # if you injected it
    system = call_args.kwargs["messages"][0]["content"]
    assert "dark mode" in system
    assert "Pro plan" in system


async def test_handle_turn_ingests_the_turn(fake_sdk):
    await handle_turn(sdk=fake_sdk, user_id="u", customer_id="c",
                      conversation_id="3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
                      message="Hi")

    fake_sdk.memories.create.assert_called_once()
    kwargs = fake_sdk.memories.create.call_args.kwargs
    assert kwargs["user_id"] == "u"
    assert kwargs["customer_id"] == "c"
    assert kwargs["document_type"] == "ai-chat-conversation"
```

```typescript TypeScript theme={null}
// tests/chat.test.ts
import { describe, it, expect, vi } from 'vitest';
import type { RawContext, SynapClient } from '@maximem/synap-js-sdk';

import { handleTurn } from '../src/chat.js';   // your code under test

// Build a realistic response without hitting the network. The namespaced
// surface returns the raw snake_case shape, so the fixture uses those names.
export function makeFakeContext(facts: string[]): RawContext {
  return {
    facts: facts.map((content, i) => ({
      id: `fact_${i}`,
      content,
      confidence: 0.9,
      source: 'test',
      extracted_at: '2026-01-01T00:00:00Z',
    })),
    metadata: {
      correlation_id: 'test-corr-id',
      ttl_seconds: 300,
      source: 'cloud',
      retrieved_at: '2026-01-01T00:00:00Z',
    },
  } as RawContext;
}

// Mock the SDK's public methods, not its transport: those are your seams.
export function makeFakeSdk(context: RawContext = makeFakeContext([])) {
  return {
    conversation: { context: { fetch: vi.fn().mockResolvedValue(context) } },
    memories: { create: vi.fn().mockResolvedValue({ ingestion_id: 'ing_test' }) },
  } as unknown as SynapClient;
}

describe('handleTurn', () => {
  it('injects retrieved facts into the prompt', async () => {
    const sdk = makeFakeSdk(makeFakeContext(['User prefers dark mode']));
    const reply = await handleTurn(sdk, {
      user_id: 'u',
      conversation_id: '3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
      message: 'hello',
    });
    expect(reply).toBeTruthy();
  });
});
```

**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](https://docs.maximem.ai/setup/first-integration.md#integration-reference)), FastAPI's `app.dependency_overrides` swaps it out per test. In Express there is no injector, so export the client from one module and let the test replace it with `vi.mock`.

```python Python theme={null}
from fastapi.testclient import TestClient
from myapp.main import app, get_sdk

def test_chat_endpoint_with_mock_sdk():
    fake_sdk = MagicMock()
    fake_sdk.conversation.context.fetch = AsyncMock(return_value=make_fake_context([]))
    fake_sdk.memories.create = AsyncMock()

    app.dependency_overrides[get_sdk] = lambda: fake_sdk
    try:
        client = TestClient(app)
        response = client.post("/chat", json={
            "message": "hello",
            "user_id": "u",
            "customer_id": "c",
            "conversation_id": "3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        })
        assert response.status_code == 200
    finally:
        app.dependency_overrides.clear()
```

```typescript TypeScript theme={null}
import { describe, it, expect, vi, beforeEach } from 'vitest';
import request from 'supertest';

// Replace the module the route imports its client from. Do this before
// importing the app, so the route closes over the fake.
vi.mock('../src/synap.js', () => ({
  sdk: {
    conversation: { context: { fetch: vi.fn().mockResolvedValue(makeFakeContext([])) } },
    memories: { create: vi.fn().mockResolvedValue({ ingestion_id: 'ing_test' }) },
  },
  init: vi.fn(),
  cleanup: vi.fn(),
}));

describe('POST /chat', () => {
  beforeEach(() => { vi.resetModules(); });

  it('answers with a mocked SDK', async () => {
    const { app } = await import('../src/server.js');
    const response = await request(app).post('/chat').send({
      message: 'hello',
      user_id: 'u',
      customer_id: 'c',
      conversation_id: '3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    });
    expect(response.status).toBe(200);
  });
});
```

## 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.

```python Python theme={null}
import asyncio
import os
import uuid
import pytest
from maximem_synap import MaximemSynapSDK

pytestmark = pytest.mark.integration   # opt-in marker so unit suite stays fast


@pytest.fixture(scope="session")
async def real_sdk():
    """One real SDK per test session, using a dedicated test instance."""
    sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_TEST_API_KEY"])
    await sdk.initialize()
    yield sdk
    await sdk.shutdown()


# Note: the async session fixture above requires `pytest-asyncio` configured with
# `asyncio_mode = "auto"`, or switch the decorator to `@pytest_asyncio.fixture(scope="session")`.
# Under strict `pytest-asyncio` mode, plain `@pytest.fixture` async fixtures don't execute.


@pytest.fixture
def test_ids():
    """Per-test isolated user/customer/conversation IDs so tests don't interfere."""
    return {
        "user_id": f"test_user_{uuid.uuid4()}",
        "customer_id": f"test_cust_{uuid.uuid4()}",
        "conversation_id": str(uuid.uuid4()),
    }


async def test_ingest_then_retrieve_roundtrip(real_sdk, test_ids):
    """Smoke test: ingestion → retrieval works end-to-end."""
    await real_sdk.memories.create(
        document="User: I prefer dark mode.\nAssistant: Noted!",
        document_type="ai-chat-conversation",
        **test_ids,
    )

    # Wait for async processing
    await asyncio.sleep(5)

    ctx = await real_sdk.conversation.context.fetch(
        conversation_id=test_ids["conversation_id"],
        search_query=["dark mode"],
        user_id=test_ids["user_id"],
        customer_id=test_ids["customer_id"],
    )

    assert any("dark mode" in p.content.lower() for p in ctx.preferences)
```

```typescript TypeScript theme={null}
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';

// Opt-in: keep the unit suite fast. Run with `vitest --project integration`
// or guard on an env var, whichever your setup uses.
const RUN = process.env.SYNAP_INTEGRATION === '1';

describe.skipIf(!RUN)('end-to-end against a real test Instance', () => {
  let sdk: SynapClient;

  beforeAll(async () => {
    // _force_new bypasses the per-identity client registry so this suite
    // cannot disturb a client the rest of the process already holds.
    sdk = new SynapClient({ apiKey: process.env.SYNAP_TEST_API_KEY, _force_new: true });
    await sdk.initialize();
  });

  // Nothing else will close a _force_new client for you.
  afterAll(async () => { await sdk.shutdown(); });

  it('ingests then retrieves, end to end', async () => {
    // Unique ids per test: Synap memories persist, and shared ids make
    // assertions flaky.
    const ids = {
      user_id: `test_user_${randomUUID()}`,
      customer_id: `test_cust_${randomUUID()}`,
      conversation_id: randomUUID(),
    };

    const result = await sdk.memories.create({
      document: 'User: I prefer dark mode.\nAssistant: Noted!',
      document_type: 'ai-chat-conversation',
      ...ids,
    });

    // Wait on the pipeline rather than guessing with a fixed sleep.
    await sdk.memories.wait_for_completion(result.ingestion_id);

    const ctx = await sdk.conversation.context.fetch({
      conversation_id: ids.conversation_id,
      search_query: ['dark mode'],
      user_id: ids.user_id,
      customer_id: ids.customer_id,
    });

    expect(
      (ctx.preferences ?? []).some((p) => String(p.content).toLowerCase().includes('dark mode')),
    ).toBe(true);
  });
});
```

**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:

```python Python theme={null}
sdk = MaximemSynapSDK(api_key="...", _force_new=True)
```

```javascript JavaScript theme={null}
const sdk = new SynapClient({ apiKey: '...', _force_new: true });
```

```typescript TypeScript theme={null}
const sdk = new SynapClient({ apiKey: '...', _force_new: true });
```

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](https://docs.maximem.ai/sdk/initialization.md#running-multiple-api-keys-in-one-process)). 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 a fresh UUID inside each test (`uuid.uuid4()` in Python, `crypto.randomUUID()` in JavaScript).

## 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.

```python Python theme={null}
from syrupy import snapshot

async def test_prompt_renders_consistently(fake_sdk, snapshot):
    fake_sdk.conversation.context.fetch.return_value = make_fake_context([
        "User prefers dark mode",
        "User is on Pro plan",
    ])
    prompt = await build_prompt(fake_sdk, user_id="u", customer_id="c",
                                conversation_id="3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
                                message="What plan am I on?")
    assert prompt == snapshot
```

```typescript TypeScript theme={null}
import { expect, it } from 'vitest';

it('renders the prompt consistently', async () => {
  const fakeSdk = makeFakeSdk(
    makeFakeContext(['User prefers dark mode', 'User is on Pro plan']),
  );
  const prompt = await buildPrompt(fakeSdk, {
    user_id: 'u',
    customer_id: 'c',
    conversation_id: '3f6b1a2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    message: 'What plan am I on?',
  });
  // Vitest has snapshots built in; no extra package.
  expect(prompt).toMatchSnapshot();
});
```

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_id`s across tests.** Synap memories are real and persist; cross-test pollution will bite.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.