Skip to content
General Augment Docs

Local Testing

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

Section titled “Run The Mock”

From a General Augment repository checkout:

Terminal window
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:

Terminal window
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

Section titled “Responses Fixture”
Terminal window
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:

Terminal window
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

Section titled “Memory Fixtures”

Store a fact:

Terminal window
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:

Terminal window
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:

Terminal window
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

Section titled “Test Setup”

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

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.