Mocking APIs

The local mock server reads endpoint-level MockConfig declarations from an Acore contract. It is implemented in Rust and intended for development and contract tests.

Declare an endpoint response

endpoints {
  ["ListTasks"] = EndpointDef {
    name = "list_tasks"
    method = "GET"
    path = "/tasks"
    mock = MockConfig {
      fallback = MockResponse {
        status = 200
        headers = { ["content-type"] = "application/json" }
        data = StaticData { body = { tasks = [] } }
      }
    }
  }
}

Start the server with the contract as a positional argument:

axiom serve axiom.acore --port 8080 --debug

Conditional selection

MockConfig.selectionStrategy supports first_match, random, sequential, and weighted. Conditions can inspect headers, query/path values, body paths, or mock state and can be combined with all/any/not conditions.

responses = [
  MockResponse {
    label = "missing"
    conditions = [
      PathCondition { key = "id" op = "eq" value = "404" }
    ]
    status = 404
  }
]

Stateful behavior

state = MockStateConfig {
  initial = { tasks = [] }
  onReceive = [
    StoreMutation { type = "append" key = "tasks" value = { id = "1" } }
  ]
}

State changes run in declaration order. The more detailed changes form can match a selected response, mutate state, and append activity events. Restart or explicit reset behavior should be part of the test setup when isolation matters.

Fault injection

fault = FaultConfig {
  errorRate = 0.1
  errorResponse = MockResponse { status = 503 }
  networkFault = NetworkFault {
    type = "slow_response"
    probability = 0.1
    delayMs = 500
  }
}

Probabilities must be between 0 and 1. Fault injection demonstrates consumer handling; it does not estimate a production service's reliability.

Validation checklist

• inspect the evaluated contract before starting the server;
• test response selection and fallback explicitly;
• reset state between tests that require isolation;
• avoid real credentials in headers or templates; and
• run the same client suite against the real backend before release.