SDK quick start

Mockarty ships first-class SDKs for Go, Python, and Java so
your tests live next to your application code rather than in a separate
DSL. The SDKs let you:

• Drive Mockarty from a unit / integration test (create mocks, run perf
  scripts, assert results).
• Emit conformant Allure 2 reports without
  going through the CLI runner.
• Use Mockarty as a Pact-style contract
  verifier inside your existing test framework.
• Run a CI step against a Mockarty test container
  that the SDK starts and tears down — no standing admin node needed.

If you’d rather author tests in JavaScript / TypeScript, the perf runner
already accepts k6-compatible scripts (see
Performance testing). The SDKs are for
teams that want statically-typed test code in the same language as the
service under test.

Why use an SDK

• Native test framework integration. go test, pytest, JUnit 5
  run your Mockarty assertions like any other test.
• No DSL learning curve. Use your IDE’s autocomplete, your usual
  refactor tools.
• Programmatic mock setup. Build complex fixtures (matrix of
  combinations) in code instead of YAML.
• CI without a standing server. The SDK can start a Mockarty
  test container for the test run and tear it down
  after — no permanently-running admin node required.

Compatibility

Every SDK release tracks a Mockarty admin-node version. The SDK works
against equal-or-newer servers; older servers may not implement newer
endpoints. Check the SDK changelog for the supported version range.

Go SDK

Install

go get github.com/mockarty/mockarty-go@latest

Hello world

The SDK is a typed REST client. Point it at a running Mockarty (local
admin node, or a test container you start in CI)
and create/fetch mocks programmatically:

package mock_test

import (
    "context"
    "testing"

    mockarty "github.com/mockarty/mockarty-go"
)

func TestCheckoutStub(t *testing.T) {
    ctx := context.Background()

    // 1. Connect to a running Mockarty (default localhost:5770).
    client := mockarty.NewClient("http://localhost:5770",
        mockarty.WithAPIKey("your-api-key"),
        mockarty.WithNamespace("sandbox"),
    )

    // 2. Build a mock with the fluent builder.
    mock := mockarty.NewMockBuilder().
        ID("charge-ok").
        HTTP(func(h *mockarty.HTTPBuilder) {
            h.Route("/v1/charge").Method("POST")
        }).
        Response(func(r *mockarty.ResponseBuilder) {
            r.Status(200).JSONBody(map[string]any{"id": "ch_123", "status": "succeeded"})
        }).
        Build()

    // 3. Create it on the server, then point your code under test at the stub URL.
    if _, err := client.Mocks().Create(ctx, mock); err != nil {
        t.Fatal(err)
    }
    // your code calls http://localhost:5770/stubs/sandbox/v1/charge ...
}

Full guide and reference: see SDK guide. For a server in
CI without a standing admin node, use the test container.

Python SDK

Install

pip install mockarty

Hello world

from mockarty import MockartyClient, MockBuilder

def test_checkout_stub():
    # Connect to a running Mockarty (default localhost:5770).
    with MockartyClient(base_url="http://localhost:5770", api_key="your-api-key") as client:
        mock = (
            MockBuilder.http("/v1/charge", "POST")
            .id("charge-ok")
            .respond(200, body={"id": "ch_123", "status": "succeeded"})
            .build()
        )
        client.mocks.create(mock)
        # your code calls http://localhost:5770/stubs/sandbox/v1/charge ...
        client.mocks.delete("charge-ok")

The Python SDK plays nicely with pytest fixtures — wrap the
MockartyClient in a fixture and share it across the suite. For a server in
CI, start a test container.
Full reference: see SDK guide.

Java SDK

Install (Maven)

<dependency>
  <groupId>ru.mockarty</groupId>
  <artifactId>mockarty-junit5</artifactId>
  <version>0.3.0</version>
  <scope>test</scope>
</dependency>

Install (Gradle)

testImplementation 'ru.mockarty:mockarty-junit5:0.3.0'

mockarty-junit5 brings the core client (mockarty-java) in transitively —
one dependency covers the whole example below. If you don’t use JUnit 5,
depend on ru.mockarty:mockarty-java directly instead.

Hello world

import ru.mockarty.MockartyClient;
import ru.mockarty.builder.MockBuilder;
import ru.mockarty.junit5.MockartyTest;
import org.junit.jupiter.api.Test;

// @MockartyTest connects to a running Mockarty (MOCKARTY_BASE_URL / MOCKARTY_API_KEY
// or annotation params) and injects a ready client; cleanupAfterEach removes mocks.
@MockartyTest(namespace = "sandbox", cleanupAfterEach = true)
class CheckoutTest {

    @Test
    void chargeStub(MockartyClient client) {
        client.mocks().create(
            MockBuilder.http("/v1/charge", "POST")
                .id("charge-ok")
                .respond(200, "{\"id\":\"ch_123\",\"status\":\"succeeded\"}")
                .build());
        // your code calls <server>/stubs/sandbox/v1/charge ...
    }
}

The Java SDK integrates with JUnit 5 via the @MockartyTest annotation,
which connects to (or, with the test-container extension, starts) a Mockarty
server and injects a MockartyClient. Full reference: see
SDK guide.

Which SDK fits which workflow

What’s NOT in the SDK

By design, the SDKs cover CI / scripting / end-user-test surface
only. They do not expose:

• Admin operations (user management, licence management, audit-log
  export, cluster operations) — these stay in the Web UI / REST API.
• Workspace settings.
• Token issuance / revocation (only via Web UI or admin REST API).
• Webhook / channel configuration.

If you have a use case for a missing SDK method, please open an issue
on the corresponding SDK repository. SDK scope grows on demand, not
mechanically with the REST surface.

SDK source code

Each repository contains an examples/ directory with runnable
scenarios. The examples track the SDK’s main branch and are
versioned alongside the SDK release.

Where to next

• SDK guide — full per-language API reference.
• Allure annotations — rich report metadata.
• CLI command reference — what’s available
  outside the SDK.
• Quick start — create and test your first mock.