MockServer

https://www.mock-server.com/
Admin
MockServer is an HTTP/HTTPS mock and proxy that allows users to easily mock and verify requests,...
Tokens:832,072
Snippets:5,211
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start a demo MockServer

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Launches a pre-configured demo instance with example expectations.

```bash
java -jar mockserver-netty-no-dependencies-7.5.0.jar demo -p 1080
```

--------------------------------

### Start Node.js Server

Source: https://www.mock-server.com/mock_server/isolating_single_service.html

Commands to install dependencies and launch the Node.js process.

```bash
npm i
node server.js
```

--------------------------------

### Install Go MockServer Client

Source: https://www.mock-server.com/mock_server/mockserver_clients.html

Command to install the Go module.

```bash
go get github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7@latest
```

--------------------------------

### Install MockServer Client

Source: https://www.mock-server.com/mock_server/mockserver_clients.html

Install the library using pip.

```bash
pip install mockserver-client
```

--------------------------------

### Install PHP MockServer Client

Source: https://www.mock-server.com/mock_server/mockserver_clients.html

Install the client library via Composer.

```bash
composer require mock-server/mockserver-client
```

--------------------------------

### Start the Mock Server

Source: https://www.mock-server.com/mock_server/getting_started.html

Run this command to start the server and begin serving your mock endpoints.

```bash
npx mock-server start
```

--------------------------------

### Example: Enable Metrics and Cost Budget

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Example configuration enabling both general metrics and LLM-specific metrics with a $10 budget.

```bash
-Dmockserver.metricsEnabled="true" -Dmockserver.llmMetricsEnabled="true" -Dmockserver.llmCostBudgetUsd="10.0"
```

--------------------------------

### Example System Property Configuration

Source: https://www.mock-server.com/mock_server/initializing_expectations.html

A concrete example of setting the system property to a specific value.

```bash
-Dmockserver.maximumNumberOfRequestToReturnInVerificationFailure="20"
```

--------------------------------

### Manual Proxy Configuration for OpenCode

Source: https://www.mock-server.com/mock_server/ai_optimisation.html

Step-by-step manual setup for starting a proxy with a unique CA and routing OpenCode traffic through it.

```bash
# 1. Start MockServer as an HTTPS proxy with a unique, machine-local CA
#    (the default CA private key is public — never trust it for real traffic).
docker run -d --rm --name mockserver-proxy -p 1080:1080 mockserver/mockserver \
  -serverPort 1080 \
  -Dmockserver.dynamicallyCreateCertificateAuthorityCertificate=true \
  -Dmockserver.directoryToSaveDynamicSSLCertificate=/dynamic-certs

# 2. Trigger CA generation, then copy the CA out of the container
curl -sk https://localhost:1080/ >/dev/null
docker exec mockserver-proxy cat /dynamic-certs/CertificateAuthorityCertificate.pem > mockserver-ca.pem

# 3. Route OpenCode through the proxy and trust the CA
export HTTPS_PROXY=http://localhost:1080
export NODE_EXTRA_CA_CERTS=$PWD/mockserver-ca.pem   # OpenCode is a Node.js tool
export SSL_CERT_FILE=$PWD/mockserver-ca.pem          # any Python helpers

# 4. Point OpenCode at a REAL provider with YOUR OWN API key, then run it headless
export OPENAI_API_KEY=sk-...            # or ANTHROPIC_API_KEY=sk-ant-...
opencode run "summarise the README and suggest one improvement"
```

--------------------------------

### Example OpenAI Configuration

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Example of setting OpenAI provider and API key via system properties.

```bash
-Dmockserver.llmProvider="OPENAI" -Dmockserver.llmApiKey="sk-..."
```

--------------------------------

### Run MockServer with S3 Backend

Source: https://www.mock-server.com/mock_server/centralized_deployment.html

Example command to start a MockServer container configured to use an S3 bucket for storage.

```bash
docker run --rm -p 1080:1080 \
  -e MOCKSERVER_BLOB_STORE_TYPE=s3 \
  -e MOCKSERVER_BLOB_STORE_BUCKET=my-mockserver-fixtures \
  -e MOCKSERVER_BLOB_STORE_REGION=eu-west-1 \
  -e MOCKSERVER_BLOB_STORE_KEY_PREFIX=ci-shared/ \
  mockserver/mockserver:7.5.0
```

--------------------------------

### Example OTLP Collector Configuration

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Example showing how to enable both metrics and traces while specifying a collector endpoint.

```bash
-Dmockserver.otelMetricsEnabled="true" -Dmockserver.otelTracesEnabled="true" -Dmockserver.otelEndpoint="http://otel-collector:4318"
```

--------------------------------

### Install Ruby MockServer Client

Source: https://www.mock-server.com/mock_server/mockserver_clients.html

Command to install the Ruby gem.

```bash
gem install mockserver-client
```

--------------------------------

### Example: Enable Per-Expectation Metrics

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Example configuration for enabling general metrics and per-expectation match tracking.

```bash
-Dmockserver.metricsEnabled="true" -Dmockserver.perExpectationMetricsEnabled="true"
```

--------------------------------

### Example Load Generation Configuration

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Example of enabling load generation with specific concurrency and rate limits.

```bash
-Dmockserver.loadGenerationEnabled="true" -Dmockserver.loadGenerationMaxVirtualUsers="20" -Dmockserver.loadGenerationMaxRequestsPerSecond="200"
```

--------------------------------

### Start MockServer from the command line

Source: https://www.mock-server.com/where/homebrew.html

Execute the mockserver command to start the server with specific port and logging configurations.

```bash
mockserver -serverPort 1080 -logLevel INFO
```

--------------------------------

### Install Mock Server

Source: https://www.mock-server.com/mock_server/getting_started.html

Use npm to install the mock server package as a development dependency.

```bash
npm install --save-dev mock-server
```

--------------------------------

### Start MockServer via Homebrew

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Execute the mockserver command to start the server on a specific port.

```bash
mockserver run -p 1080
```

--------------------------------

### Configure Proxy Setup Startup Logging

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Controls whether the proxy setup information block is printed to the logs at startup.

```bash
-Dmockserver.proxySetupLogging=...
```

```bash
MOCKSERVER_PROXY_SETUP_LOGGING=...
```

```properties
mockserver.proxySetupLogging=...
```

```bash
-Dmockserver.proxySetupLogging="true"
```

--------------------------------

### Install and use Ruby MockServer client

Source: https://www.mock-server.com/llms-full.txt

Install via gem and use the Client class to define expectations with a fluent API.

```bash
gem install mockserver-client
```

```ruby
require 'mockserver-client'
    include MockServer

    client = Client.new('localhost', 1080)

    # Create expectation using fluent API
    client.when(
      HttpRequest.request(method: 'GET', path: '/api/users')
    ).respond(
      HttpResponse.response(
        status_code: 200,
        headers: { 'Content-Type' => ['application/json'] },
        body: '[{"id": 1, "name": "Alice"}]'
      )
    )
```

--------------------------------

### Install MockServer via Homebrew

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Use the Homebrew package manager to install MockServer binaries and scripts.

```bash
brew install mockserver
```

--------------------------------

### Example SLO Configuration

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Example system property configuration for enabling SLO tracking with a 5-minute window and 10,000 sample limit.

```text
-Dmockserver.sloTrackingEnabled="true" -Dmockserver.sloWindowRetentionMillis="300000" -Dmockserver.sloWindowMaxSamples="10000"
```

--------------------------------

### Generate and Start Load Scenarios

Source: https://www.mock-server.com/mock_server/load_injection.html

Examples of generating a load scenario from recorded traffic and starting it across different languages and the REST API.

```Go
client := mockserver.New("localhost", 1080)

// GenerateLoadScenarioFromRecording takes a raw request document.
client.GenerateLoadScenarioFromRecording(map[string]any{
    "name":          "replay-prod-traffic",
    "mode":          "TEMPLATIZED",
    "requestFilter": map[string]any{"path": "/api/.*"},
    "maxSteps":      50,
    "target":        map[string]any{"host": "staging.svc", "port": 8080, "scheme": "http"},
}) // generate + register (LOADED), no traffic
client.StartLoadScenarios("replay-prod-traffic") // start (requires loadGenerationEnabled=true)
```

```.NET
using MockServer.Client;
using MockServer.Client.Models;

using var client = new MockServerClient("localhost", 1080);

// Parameter order is (name, mode, requestFilter, target, maxSteps).
await client.GenerateLoadScenarioFromRecordingAsync(
    "replay-prod-traffic",
    LoadRecordingMode.TEMPLATIZED,
    HttpRequest.Request().WithPath("/api/.*"),
    new LoadGenerateTarget { Host = "staging.svc", Port = 8080, Scheme = LoadTargetScheme.http },
    maxSteps: 50);                                           // generate + register (LOADED), no traffic
await client.StartLoadScenariosAsync("replay-prod-traffic"); // start (requires loadGenerationEnabled=true)
```

```Rust
use mockserver_client::ClientBuilder;
use serde_json::json;

let client = ClientBuilder::new("localhost", 1080).build().unwrap();

// generate_load_scenario_from_recording takes a raw request document.
client.generate_load_scenario_from_recording(&json!({
    "name": "replay-prod-traffic",
    "mode": "TEMPLATIZED",
    "requestFilter": { "path": "/api/.*" },
    "maxSteps": 50,
    "target": { "host": "staging.svc", "port": 8080, "scheme": "http" }
})).unwrap();                                                   // generate + register (LOADED), no traffic
client.start_load_scenarios(&["replay-prod-traffic"]).unwrap(); // start (requires loadGenerationEnabled=true)
```

```PHP
use MockServer\HttpRequest;
use MockServer\MockServerClient;

$client = new MockServerClient('localhost', 1080);

$client->generateLoadScenarioFromRecording(
    'replay-prod-traffic',
    mode: 'TEMPLATIZED',
    requestFilter: HttpRequest::request()->path('/api/.*'),
    target: ['host' => 'staging.svc', 'port' => 8080, 'scheme' => 'http'],
    maxSteps: 50,
);                                                  // generate + register (LOADED), no traffic
$client->startLoadScenarios('replay-prod-traffic'); // start (requires loadGenerationEnabled=true)
```

```REST API
# First, record real traffic through the MockServer proxy...
# (see Proxy Configuration for setup)

# Then generate a load scenario from the recorded traffic
curl -s -X PUT http://localhost:1080/mockserver/loadScenario/generateFromRecording \
  -H "Content-Type: application/json" \
  -d '{
    "name": "replay-prod-traffic",
    "mode": "TEMPLATIZED",
    "requestFilter": { "path": "/api/.*" },
    "maxSteps": 50,
    "target": { "host": "staging.svc", "port": 8080, "scheme": "http" }
  }'

# Then trigger it
curl -s -X PUT http://localhost:1080/mockserver/loadScenario/start \
  -d '{ "name": "replay-prod-traffic" }'
```

--------------------------------

### Quick Start with MockServer Client

Source: https://www.mock-server.com/where/go.html

Demonstrates initializing the client, creating an expectation, verifying requests, and resetting the server state.

```go
package main

import (
    "log"

    mockserver "github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7"
)

func main() {
    client := mockserver.New("localhost", 1080)

    // Create an expectation
    _, err := client.When(
        mockserver.Request().Method("GET").Path("/hello"),
    ).Respond(
        mockserver.Response().StatusCode(200).Body("world"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Verify the request was received at least once
    if err := client.Verify(
        mockserver.Request().Path("/hello"),
        mockserver.AtLeast(1),
    ); err != nil {
        log.Fatal(err)
    }

    // Reset
    client.Reset()
}
```

--------------------------------

### Generate and start load scenarios

Source: https://www.mock-server.com/mock_server/load_injection.html

Examples of defining a load scenario from an OpenAPI spec and starting it across different programming languages and the REST API.

```Go
package main

import (
    mockserver "github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7"
)

func main() {
    client := mockserver.New("localhost", 1080)

    // GenerateLoadScenarioFromOpenAPI takes a raw request document.
    client.GenerateLoadScenarioFromOpenAPI(map[string]any{
        "name":             "petstore-load",
        "specUrlOrPayload": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
        "target":           map[string]any{"host": "petstore.svc", "port": 8080, "scheme": "http"},
        "profile": map[string]any{
            "stages": []map[string]any{
                {"type": "VU", "vus": 10, "durationMillis": 60000},
            },
        },
    }) // generate + register (LOADED), no traffic
    client.StartLoadScenarios("petstore-load") // start (requires loadGenerationEnabled=true)
}
```

```.NET
using MockServer.Client;
using MockServer.Client.Models;

using var client = new MockServerClient("localhost", 1080);

await client.GenerateLoadScenarioFromOpenAPIAsync(
    "petstore-load",
    "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
    new LoadGenerateTarget { Host = "petstore.svc", Port = 8080, Scheme = LoadTargetScheme.http },
    new LoadProfile { Stages = new List<LoadStage> { LoadStage.ConstantVus(10, 60000) } }); // generate + register (LOADED)
await client.StartLoadScenariosAsync("petstore-load");                  // start (requires loadGenerationEnabled=true)
```

```Rust
use mockserver_client::ClientBuilder;
use serde_json::json;

let client = ClientBuilder::new("localhost", 1080).build().unwrap();

// generate_load_scenario_from_openapi takes a raw request document.
client.generate_load_scenario_from_openapi(&json!({
    "name": "petstore-load",
    "specUrlOrPayload": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
    "target": { "host": "petstore.svc", "port": 8080, "scheme": "http" },
    "profile": { "stages": [ { "type": "VU", "vus": 10, "durationMillis": 60000 } ] }
})).unwrap();                                              // generate + register (LOADED), no traffic
client.start_load_scenarios(&["petstore-load"]).unwrap(); // start (requires loadGenerationEnabled=true)
```

```PHP
require_once 'vendor/autoload.php';

use MockServer\LoadProfile;
use MockServer\LoadStage;
use MockServer\MockServerClient;

$client = new MockServerClient('localhost', 1080);

$client->generateLoadScenarioFromOpenAPI(
    'petstore-load',
    'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml',
    ['host' => 'petstore.svc', 'port' => 8080, 'scheme' => 'http'],
    LoadProfile::of(LoadStage::vuHold(10, 60000)),
);                                            // generate + register (LOADED), no traffic
$client->startLoadScenarios('petstore-load'); // start (requires loadGenerationEnabled=true)
```

```REST API
# Generate a load scenario from a public OpenAPI spec
curl -s -X PUT http://localhost:1080/mockserver/loadScenario/generateFromOpenAPI \
  -H "Content-Type: application/json" \
  -d '{
    "name": "petstore-load",
    "specUrlOrPayload": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
    "target": { "host": "petstore.svc", "port": 8080, "scheme": "http" },
    "profile": { "stages": [ { "type": "VU", "vus": 10, "durationMillis": 60000 } ] }
  }'

# Then trigger it (requires loadGenerationEnabled=true)
curl -s -X PUT http://localhost:1080/mockserver/loadScenario/start \
  -d '{ "name": "petstore-load" }'
```

--------------------------------

### Quick Start with MockServer Client

Source: https://www.mock-server.com/where/packagist.html

Demonstrates connecting to the server, creating an expectation, verifying requests, and resetting the server state.

```php
<?php

use MockServer\MockServerClient;
use MockServer\HttpRequest;
use MockServer\HttpResponse;
use MockServer\VerificationTimes;

// Connect to MockServer
$client = new MockServerClient('localhost', 1080);

// Create an expectation
$client->when(
    HttpRequest::request()->method('GET')->path('/hello')
)->respond(
    HttpResponse::response()
        ->statusCode(200)
        ->header('Content-Type', 'application/json')
        ->body('{"message":"world"}')
);

// Verify the request was received
$client->verify(
    HttpRequest::request()->path('/hello'),
    VerificationTimes::atLeast(1)
);

// Reset
$client->reset();
```

--------------------------------

### Asynchronous MockServer Usage

Source: https://www.mock-server.com/mock_server/mockserver_testcontainers.html

Example of starting a MockServer container using the Tokio async test runner.

```rust
use testcontainers::runners::AsyncRunner;
use testcontainers_mockserver::MockServer;

#[tokio::test]
async fn test_with_mockserver_async() {
    let container = MockServer::default().start().await.unwrap();
    let base_url = testcontainers_mockserver::async_base_url(&container).await;
    // ... use base_url with an async HTTP client
}
```

--------------------------------

### Synchronous MockServer Usage

Source: https://www.mock-server.com/mock_server/mockserver_testcontainers.html

Example of starting a MockServer container and setting an expectation using a synchronous test runner.

```rust
use testcontainers::runners::SyncRunner;
use testcontainers_mockserver::MockServer;

#[test]
fn test_with_mockserver() {
    let container = MockServer::default().start().unwrap();
    let base_url = testcontainers_mockserver::base_url(&container);

    // Create an expectation
    let client = reqwest::blocking::Client::new();
    client.put(format!("{base_url}/mockserver/expectation"))
        .header("Content-Type", "application/json")
        .body(r#"[{
            "httpRequest": { "method": "GET", "path": "/hello" },
            "httpResponse": { "statusCode": 200, "body": "world" }
        }]"#)
        .send()
        .unwrap();

    // Call the mocked endpoint
    let resp = client.get(format!("{base_url}/hello")).send().unwrap();
    assert_eq!(resp.status(), 200);
    assert_eq!(resp.text().unwrap(), "world");
}
```

--------------------------------

### Start MockServer with Unique CA

Source: https://www.mock-server.com/mock_server/ai_traffic_inspection.html

Generate a unique, local CA for secure, team-facing setups to prevent impersonation risks.

```bash
java -jar mockserver-netty-no-dependencies-7.5.0.jar -serverPort 1080 --proxy-setup
```

```bash
docker run -d --rm -p 1080:1080 mockserver/mockserver --proxy-setup
```

--------------------------------

### Match Request by Cookie and Query Parameter

Source: https://www.mock-server.com/mock_server/creating_expectations.html

Examples of setting up an expectation to match a GET request with specific query parameters and cookies.

```Java
new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );
```

```JavaScript
var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).mockAnyResponse({
    "httpRequest": {
        "method": "GET",
        "path": "/view/cart",
        "queryStringParameters": {
            "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
        },
        "cookies": {
            "session": "4930456C-C718-476F-971F-CB8E047AB349"
        }
    },
    "httpResponse": {
        "body": "some_response_body"
    }
}).then(
    function () {
        console.log("expectation created");
    },
    function (error) {
        console.log(error);
    }
);
```

```Python
from mockserver.client import MockServerClient
from mockserver.models import HttpRequest, HttpResponse

client = MockServerClient("localhost", 1080)
client.when(
    HttpRequest.request("/view/cart")
        .with_method("GET")
        .with_query_param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
        .with_cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
).respond(
    HttpResponse.response(body="some_response_body")
)
```

```Ruby
require 'mockserver-client'

client = MockServer::Client.new('localhost', 1080)
client.when(
    MockServer::HttpRequest.new(path: '/view/cart', method: 'GET')
).respond(
    MockServer::HttpResponse.new(body: 'some_response_body')
)
```

```Go
import mockserver "github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7"

client := mockserver.New("localhost", 1080)
client.When(
    mockserver.Request().Path("/view/cart").Method("GET").QueryStringParameter("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092").Cookie("session", "4930456C-C718-476F-971F-CB8E047AB349"),
).Respond(
    mockserver.Response().Body("some_response_body"),
)
```

```.NET
using MockServer.Client;
using MockServer.Client.Models;

using var client = new MockServerClient("localhost", 1080);
client.When(
    HttpRequest.Request().WithPath("/view/cart").WithMethod("GET").WithQueryStringParameter("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
).Respond(
    HttpResponse.Response().WithBody("some_response_body")
);
```

```Rust
use mockserver_client::{ClientBuilder, HttpRequest, HttpResponse};

let client = ClientBuilder::new("localhost", 1080).build().unwrap();
client.when(HttpRequest::new().method("GET").path("/view/cart").query_param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092"))
    .respond(HttpResponse::new().body("some_response_body"))
    .unwrap();
```

```PHP
use MockServer\MockServerClient;
use MockServer\HttpRequest;
use MockServer\HttpResponse;

$client = new MockServerClient('localhost', 1080);
$client->when(
    HttpRequest::request()
        ->method('GET')
        ->path('/view/cart')
        ->queryStringParameter('cartId', '055CA455-1DF7-45BB-8535-4F83E7266092')
        ->cookie('session', '4930456C-C718-476F-971F-CB8E047AB349')
)->respond(
    HttpResponse::response()
        ->body('some_response_body')
);
```

```REST API
curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
  "httpRequest" : {
    "method" : "GET",
    "path" : "/view/cart",
    "queryStringParameters" : {
      "cartId" : [ "055CA455-1DF7-45BB-8535-4F83E7266092" ]
    },
    "cookies" : {
      "session" : "4930456C-C718-476F-971F-CB8E047AB349"
    }
  },
  "httpResponse" : {
    "body" : "some_response_body"
  }
}'
```

--------------------------------

### Register Load Scenario with Mock Server

Source: https://www.mock-server.com/mock_server/load_injection.html

Examples of defining and registering a load scenario using various client libraries. Note that these methods register the scenario but do not start execution.

```javascript
var mockServerClient = require('mockserver-client').mockServerClient;
var client = mockServerClient("localhost", 1080);

var scenario = {
    name: 'user-browse',
    templateType: 'MUSTACHE',
    feeder: {
        strategy: 'CIRCULAR',
        rows: [
            { userId: 'alice', accountId: 'A1' },
            { userId: 'bob', accountId: 'A2' },
            { userId: 'carol', accountId: 'A3' }
        ]
    },
    profile: { stages: [ { type: 'VU', vus: 5, durationMillis: 60000 } ] },
    steps: [
        { request: { method: 'GET', path: '/accounts/{{iteration.data.accountId}}',
                     headers: { 'X-User': ['{{iteration.data.userId}}'], 'Host': ['api.svc:8080'] },
                     socketAddress: { host: 'api.svc', port: 8080, scheme: 'HTTP' } } }
    ]
};

(async function () {
    await client.loadScenario(scenario);   // register (does NOT start it yet)
})();
```

```python
from mockserver import (HttpRequest, KeyToMultiValue, LoadFeeder, LoadProfile,
                        LoadScenario, LoadStage, LoadStep, MockServerClient, SocketAddress)

scenario = LoadScenario(
    name="user-browse",
    template_type="MUSTACHE",
    feeder=LoadFeeder(
        rows=[
            {"userId": "alice", "accountId": "A1"},
            {"userId": "bob", "accountId": "A2"},
            {"userId": "carol", "accountId": "A3"},
        ],
        strategy="CIRCULAR",
    ),
    profile=LoadProfile(stages=[
        LoadStage.vu_stage(60000, vus=5),
    ]),
    steps=[
        LoadStep(request=HttpRequest(
            method="GET",
            path="/accounts/{{iteration.data.accountId}}",
            headers=[
                KeyToMultiValue(name="X-User", values=["{{iteration.data.userId}}"]),
                KeyToMultiValue(name="Host", values=["api.svc:8080"]),
            ],
            socket_address=SocketAddress(host="api.svc", port=8080, scheme="HTTP"))),
    ],
)

with MockServerClient("localhost", 1080) as client:
    client.load_scenario(scenario)   # register (does NOT start it yet)
```

```ruby
require 'mockserver-client'
include MockServer

client = Client.new('localhost', 1080)

scenario = LoadScenario.new(
  name: 'user-browse',
  template_type: 'MUSTACHE',
  feeder: LoadFeeder.new(
    strategy: 'CIRCULAR',
    rows: [
      { 'userId' => 'alice', 'accountId' => 'A1' },
      { 'userId' => 'bob',   'accountId' => 'A2' },
      { 'userId' => 'carol', 'accountId' => 'A3' }
    ]
  ),
  profile: LoadProfile.new(stages: [
    LoadStage.vu(60_000, vus: 5)
  ]),
  steps: [
    LoadStep.new(request: HttpRequest.new(
      method: 'GET',
      path: '/accounts/{{iteration.data.accountId}}',
      headers: [
        KeyToMultiValue.new(name: 'X-User', values: ['{{iteration.data.userId}}']),
        KeyToMultiValue.new(name: 'Host', values: ['api.svc:8080'])
      ],
      socket_address: SocketAddress.new(host: 'api.svc', port: 8080, scheme: 'HTTP')))
  ]
)

client.load_scenario(scenario)   # register (does NOT start it yet)
client.close
```

```go
package main

import (
    mockserver "github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7"
)

func main() {
    client := mockserver.New("localhost", 1080)

    browse := mockserver.Request().Method("GET").Path("/accounts/{{iteration.data.accountId}}").
        Header("X-User", "{{iteration.data.userId}}").
        Header("Host", "api.svc:8080").Build()
    browse.SocketAddress = &mockserver.SocketAddress{Host: "api.svc", Port: 8080, Scheme: "HTTP"}

    scenario := mockserver.LoadScenario{
        Name:         "user-browse",
        TemplateType: "MUSTACHE",
        Feeder: &mockserver.LoadFeeder{
            Strategy: mockserver.LoadFeederCircular,
            Rows: []map[string]string{
                {"userId": "alice", "accountId": "A1"},
                {"userId": "bob", "accountId": "A2"},
                {"userId": "carol", "accountId": "A3"},
            },
        },
        Profile: &mockserver.LoadProfile{
            Stages: []mockserver.LoadStage{
                mockserver.ConstantVusStage(5, 60000),
            },
        },
        Steps: []mockserver.LoadStep{
            {Request: &browse},
        },
    }

    client.LoadScenario(scenario)   // register (does NOT start it yet)
}
```

--------------------------------

### Define Login Flow State Machine

Source: https://www.mock-server.com/mock_server/stateful_scenarios.html

Configures a sequence of expectations where a POST /login request transitions the scenario from 'Started' to 'LoggedIn', affecting subsequent GET /profile responses.

```java
import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;
import static org.mockserver.model.JsonBody.json;
import org.mockserver.matchers.Times;

mockServerClient
    .when(request().withMethod("POST").withPath("/login"), Times.exactly(1))
    .withScenarioName("LoginFlow")
    .withScenarioState("Started")
    .withNewScenarioState("LoggedIn")
    .respond(response().withStatusCode(200).withBody(json("{\"token\":\"abc123\"}")));

mockServerClient
    .when(request().withMethod("GET").withPath("/profile"))
    .withScenarioName("LoginFlow")
    .withScenarioState("LoggedIn")
    .respond(response().withStatusCode(200).withBody(json("{\"name\":\"Alice\"}")));

mockServerClient
    .when(request().withMethod("GET").withPath("/profile"))
    .withScenarioName("LoginFlow")
    .withScenarioState("Started")
    .respond(response().withStatusCode(401).withBody(json("{\"error\":\"Not authenticated\"}")));
```

```javascript
var mockServerClient = require('mockserver-client').mockServerClient;
var client = mockServerClient('localhost', 1080);

await client.mockAnyResponse([
    {
        httpRequest: { method: 'POST', path: '/login' },
        httpResponse: { statusCode: 200, body: JSON.stringify({ token: 'abc123' }) },
        scenarioName: 'LoginFlow',
        scenarioState: 'Started',
        newScenarioState: 'LoggedIn',
        times: { remainingTimes: 1, unlimited: false }
    },
    {
        httpRequest: { method: 'GET', path: '/profile' },
        httpResponse: { statusCode: 200, body: JSON.stringify({ name: 'Alice' }) },
        scenarioName: 'LoginFlow',
        scenarioState: 'LoggedIn'
    },
    {
        httpRequest: { method: 'GET', path: '/profile' },
        httpResponse: { statusCode: 401, body: JSON.stringify({ error: 'Not authenticated' }) },
        scenarioName: 'LoginFlow',
        scenarioState: 'Started'
    }
]);
```

--------------------------------

### Launch MockServer via Go

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Start the server or ensure the binary is present using the mockserver package.

```go
mockserver.StartServer(1080, "", nil)
```

```go
mockserver.EnsureBinary(version, nil)
```

--------------------------------

### Quick start with MockServerClient

Source: https://www.mock-server.com/where/nuget.html

Initialize the client, define an expectation, verify a request, and reset the server state.

```csharp
using MockServer.Client;
using MockServer.Client.Models;

using var client = new MockServerClient("localhost", 1080);

// Create an expectation
client.When(
    HttpRequest.Request()
        .WithMethod("GET")
        .WithPath("/hello")
).Respond(
    HttpResponse.Response()
        .WithStatusCode(200)
        .WithBody("world")
);

// Verify the request was received
client.Verify(
    HttpRequest.Request().WithPath("/hello"),
    VerificationTimes.AtLeastTimes(1)
);

// Reset
client.Reset();
```

--------------------------------

### Liveness HTTP GET Path Configuration

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Defines the path for HTTP GET liveness probes. If set, GET requests to this path return a 200 OK status.

```java
ConfigurationProperties.livenessHttpGetPath(String livenessPath)
```

```bash
-Dmockserver.livenessHttpGetPath=...
```

```bash
MOCKSERVER_LIVENESS_HTTP_GET_PATH=...
```

```properties
mockserver.livenessHttpGetPath=...
```

```bash
-Dmockserver.livenessHttpGetPath="/liveness/probe"
```

--------------------------------

### Quick start with MockServer client

Source: https://www.mock-server.com/where/crates.html

Demonstrates creating an expectation, verifying a request, and resetting the server state using the blocking client.

```rust
use mockserver_client::{ClientBuilder, HttpRequest, HttpResponse, VerificationTimes};

fn main() -> mockserver_client::Result<()> {
    let client = ClientBuilder::new("localhost", 1080).build()?;

    // Create an expectation
    client.when(HttpRequest::new().method("GET").path("/hello"))
        .respond(HttpResponse::new().status_code(200).body("world"))?;

    // Verify the request was received
    client.verify(
        HttpRequest::new().path("/hello"),
        VerificationTimes::at_least(1),
    )?;

    // Reset
    client.reset()?;
    Ok(())
}
```

--------------------------------

### GET /mockserver/scenario/{name}

Source: https://www.mock-server.com/llms-full.txt

Get the current state of a specific scenario.

```APIDOC
## GET /mockserver/scenario/{name}

### Description
Get the current state of one scenario.

### Method
GET

### Endpoint
/mockserver/scenario/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the scenario

### Response
#### Success Response (200)
- **scenarioName** (string) - Name of the scenario
- **currentState** (string) - Current state of the scenario
```

--------------------------------

### Get Clock Status

Source: https://www.mock-server.com/llms-full.txt

Response format for the GET /mockserver/clock endpoint.

```json
{"currentInstant": "2025-01-15T09:30:00Z", "currentEpochMillis": 1736933400000, "frozen": true}
```

--------------------------------

### Launch MockServer via Node.js

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Use the npx command or the binary launcher API to start the server.

```bash
npx -p mockserver-node mockserver run -p 1080
```

```javascript
ensureBinary(version)
```

```javascript
runBinary(version, args)
```

--------------------------------

### GraphQL response example

Source: https://www.mock-server.com/mock_server/creating_expectations.html

Example of a schema-valid response for a GraphQL query.

```JSON
{ "data": { "user": { "name": "string", "email": "string" } } }
```

--------------------------------

### Deploy via Package File

Source: https://www.mock-server.com/where/kubernetes.html

Install the chart directly from a specific URL.

```bash
helm upgrade --install --namespace mockserver mockserver http://www.mock-server.com/mockserver-7.5.0.tgz
```

--------------------------------

### String Matcher Examples

Source: https://www.mock-server.com/llms-full.txt

Examples of exact and regex string matching.

```json
"path": "/api/users"
```

```json
"path": "/api/users/[0-9]+"
```

--------------------------------

### Launch MockServer via Python

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Start the server or ensure the binary is available using the client library.

```python
start(port=1080)
```

```python
ensure_binary()
```

--------------------------------

### Install Node.js Module

Source: https://www.mock-server.com/mock_server/mockserver_clients.html

Install the MockServer client as a development dependency via npm.

```bash
npm install mockserver-client --save-dev
```

--------------------------------

### Deploy via Local Source

Source: https://www.mock-server.com/where/kubernetes.html

Install the chart from a local directory containing the source files.

```bash
helm upgrade --install --namespace mockserver mockserver helm/mockserver
```

--------------------------------

### Start and Stop MockServer in Node.js

Source: https://www.mock-server.com/mock_server/running_mock_server.html

Functions to programmatically start and stop the MockServer instance.

```javascript
var mockserver = require('mockserver-node');
mockserver.start_mockserver({
                serverPort: 1080,
                verbose: true,
                trace: true
            });

// do something

mockserver.stop_mockserver({
                serverPort: 1080
            });
```

--------------------------------

### start_mockserver(options)

Source: https://www.mock-server.com/where/npm.html

Starts a MockServer instance with the specified configuration options.

```APIDOC
## start_mockserver(options)

### Description
Starts the MockServer process. This function accepts an options object to configure the server port, JVM arguments, and logging behavior.

### Parameters
- **serverPort** (number) - Optional - The port on which the MockServer will listen.
- **verbose** (boolean) - Optional - Enables verbose logging.
- **trace** (boolean) - Optional - Enables trace logging.
- **jvmOptions** (array) - Optional - A list of strings representing JVM arguments for the MockServer process.
- **mockServerVersion** (string) - Optional - Specifies the version of the MockServer to run.
```

--------------------------------

### Configure Realistic Example Generation

Source: https://www.mock-server.com/mock_server/configuration_properties.html

Enables generation of realistic fake data for OpenAPI examples.

```java
new Configuration().generateRealisticExampleValues(true)
```

```text
-Dmockserver.generateRealisticExampleValues=...
```

```text
MOCKSERVER_GENERATE_REALISTIC_EXAMPLE_VALUES=...
```

```text
mockserver.generateRealisticExampleValues=...
```

```text
-Dmockserver.generateRealisticExampleValues="true"
```

--------------------------------

### Quick start with MockServer client

Source: https://www.mock-server.com/where/rubygems.html

Basic usage for creating expectations, verifying requests, and resetting the client.

```ruby
require 'mockserver-client'

client = MockServer::Client.new('localhost', 1080)

# Create an expectation
client.when(
  MockServer::HttpRequest.request(path: '/hello').with_method('GET')
).respond(
  MockServer::HttpResponse.response(body: 'world', status_code: 200)
)

# Verify the request was received
client.verify(
  MockServer::HttpRequest.request(path: '/hello'),
  times: MockServer::VerificationTimes.at_least(1)
)

# Reset
client.reset
client.close
```
Tokens:
Raw