# Local Testing

Source: https://docs.generalaugment.com/guides/local-testing/
Description: Run a local General Augment mock server for offline app contract tests.

General Augment includes a small local HTTP mock for app backend tests. It lets your
tests call General Augment-like endpoints without live model calls, billing, Redis,
database access, or provider credentials.

Use it for contract tests, fixtures, retry/idempotency checks, and memory flows. It is
not the live managed runtime, not a model-quality test, not billing or rate-limit enforcement, and not
production provider, security, or compliance validation.

## Run The Mock

From a General Augment repository checkout:

```bash
uv run --project packages/cli genaug mock --host 127.0.0.1 --port 8787 --quiet
```

If the CLI is already installed, use
`genaug mock --host 127.0.0.1 --port 8787 --quiet`.

Point your app tests at it:

```bash
export GENAUG_API_BASE_URL="http://127.0.0.1:8787"
export GENAUG_API_KEY="local-test"
```

The mock accepts any `Authorization` or `X-Admin-Key` value. Keep the same server-side
API key path your production integration uses so tests exercise the real client code.

## Responses Fixture

```bash
curl -sS "$GENAUG_API_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: req_test_123" \
  -H "X-Idempotency-Key: checkout-summary-1" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d '{
    "model": "balanced",
    "user": "app-user-123",
    "input": "Reply exactly with: local-mock-ok",
    "metadata": {"feature": "checkout-test"}
  }'
```

Responses return a completed object with a stable `resp_mock_...` id, deterministic
output text, token counts, zero cost, caller metadata, General Augment correlation
fields, `X-Request-ID`, W3C `traceparent`, and idempotency replay behavior.

Streaming fixtures are available with `stream=true`:

```bash
curl -N "$GENAUG_API_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"balanced","user":"app-user-123","input":"Hello","stream":true}'
```

The local fixture emits semantic Responses SSE events. Hosted Hermes-backed calls can
also emit live `response.output_text.delta` events plus General Augment extension events
for redacted reasoning, thinking, status, step, interim assistant, clarification, tool
generation, and tool lifecycle metadata. Clarification stream events are notifications;
the current Responses stream does not pause for a synchronous user reply.

## Memory Fixtures

Store a fact:

```bash
curl -sS "$GENAUG_API_BASE_URL/api/v1/agent/memory/store" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "app-user-123",
    "fact": "User prefers window seats",
    "fact_type": "preference",
    "importance_score": 0.9,
    "source": "booking",
    "metadata": {"surface": "checkout"},
    "user_profile": {"timezone": "America/Toronto"},
    "idempotency_key": "memory-window-seat-1"
  }'
```

Search memory:

```bash
curl -sS "$GENAUG_API_BASE_URL/api/v1/agent/memory/search" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "app-user-123",
    "query": "window seats",
    "limit": 5,
    "fact_type": "preference",
    "min_importance": 0.8,
    "source": "booking"
  }'
```

Read the profile:

```bash
curl -sS "$GENAUG_API_BASE_URL/api/v1/agent/memory/profile/app-user-123" \
  -H "Authorization: Bearer $GENAUG_API_KEY"
```

The mock also supports:

- `GET /v1/health`
- `GET /health/ready`
- `DELETE /api/v1/agent/memory/{memory_id}?user_id={user_id}`
- `DELETE /api/v1/agent/memory/user/{user_id}`

Memory is in process only. Restarting the mock clears facts and idempotency replays.

## Test Setup

In app tests, read the base URL from the same environment variable you use in staging:

```ts
const baseUrl = process.env.GENAUG_API_BASE_URL ?? "http://127.0.0.1:8787";

export async function callGeneralAugment(input: string) {
  const response = await fetch(`${baseUrl}/v1/responses`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENAUG_API_KEY ?? "local-test"}`,
      "Content-Type": "application/json",
      "X-Idempotency-Key": "unit-test-turn-1",
    },
    body: JSON.stringify({
      model: "balanced",
      user: "test-user",
      input,
      metadata: { feature: "unit-test" },
    }),
  });

  if (!response.ok) {
    throw new Error(`General Augment mock returned ${response.status}`);
  }

  return response.json();
}
```

Use hosted `/health/ready`, `genaug smoke`, `genaug verify`, dashboard evidence, and
production traces for live readiness. Treat hosted `/v1/health` as a compatibility path
that must pass status smoke before production callers rely on it. The local mock keeps
app CI fast before those environments are involved.