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

# Ruby Client

> Control MockServer from Ruby using the community-maintained mockserver-client gem.

The `mockserver-client` gem is a community-maintained Ruby client for MockServer. It provides a DSL for creating expectations, verifying requests, and managing server state.

<Note>
  The Ruby client is a community-maintained project, not an official
  MockServer artifact. The canonical source and latest release information are
  available on [RubyGems](https://rubygems.org/gems/mockserver-client).
</Note>

## Installation

<Tabs>
  <Tab title="Gemfile">
    ```ruby theme={null}
    gem 'mockserver-client'
    ```

    Then run:

    ```bash theme={null}
    bundle install
    ```
  </Tab>

  <Tab title="Direct install">
    ```bash theme={null}
    gem install mockserver-client
    ```
  </Tab>
</Tabs>

## Usage

The gem exposes two clients:

* `MockServer::MockServerClient` — for interacting with MockServer (mocking)
* `MockServer::ProxyClient` — for interacting with MockServer acting as a proxy

```ruby theme={null}
require 'mockserver-client'

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

## JSON-based API

The Ruby client mirrors the MockServer REST API. If the Ruby DSL does not cover a particular feature, you can submit raw expectation JSON directly via the REST API using any HTTP library:

```ruby theme={null}
require 'net/http'
require 'json'

uri = URI('http://localhost:1080/mockserver/expectation')
http = Net::HTTP.new(uri.host, uri.port)

request = Net::HTTP::Put.new(uri)
request['Content-Type'] = 'application/json'
request.body = JSON.dump({
  "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"
  }
})

response = http.request(request)
puts response.code
```

To verify a request was received:

```ruby theme={null}
uri = URI('http://localhost:1080/mockserver/verify')
http = Net::HTTP.new(uri.host, uri.port)

request = Net::HTTP::Put.new(uri)
request['Content-Type'] = 'application/json'
request.body = JSON.dump({
  "httpRequest" => {
    "path" => "/view/cart"
  },
  "times" => {
    "atLeast" => 1
  }
})

response = http.request(request)
# A 202 response means verification passed.
# A 406 response means verification failed — the body contains the failure message.
puts response.code
```

To reset all state:

```ruby theme={null}
uri = URI('http://localhost:1080/mockserver/reset')
Net::HTTP.new(uri.host, uri.port).request(Net::HTTP::Put.new(uri))
```

## REST API reference

All MockServer operations are available over HTTP. The full schema is documented in the [REST API overview](/api/overview). The endpoints relevant to this guide are:

| Operation                  | Method | Endpoint                             |
| -------------------------- | ------ | ------------------------------------ |
| Create expectation         | `PUT`  | `/mockserver/expectation`            |
| Verify request             | `PUT`  | `/mockserver/verify`                 |
| Verify sequence            | `PUT`  | `/mockserver/verifySequence`         |
| Retrieve recorded requests | `PUT`  | `/mockserver/retrieve?type=REQUESTS` |
| Clear by matcher           | `PUT`  | `/mockserver/clear`                  |
| Reset all state            | `PUT`  | `/mockserver/reset`                  |

<Tip>
  If you need features not yet available in the Ruby gem — such as OpenAPI
  request matching, response templates, or callback actions — use the REST API
  directly as shown above. Every feature MockServer supports is accessible via
  HTTP.
</Tip>