Automate Mockarty in CI/CD

Use these examples when a pipeline needs to prepare mocks or run checks. Replace sample server addresses, target URLs, and token values with your own. For endpoint details, see the API Reference.

These CI examples use an API token with permission for the workspace you are testing. Set it in MOCKARTY_API_KEY before running the cURL commands; they also use jq to read JSON responses. For SDK client setup, see the SDK Guide.

Examples

Running API Tests from CI

cURL

TOKEN="${MOCKARTY_API_KEY:?Set MOCKARTY_API_KEY first}"
BASE="${MOCKARTY_URL:-http://127.0.0.1:5770}/api/v1"

# 1. Create a collection
COLLECTION_ID=$(curl -s -X POST "$BASE/api-tester/collections" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Tests", "description": "Automated test suite"}' | jq -r '.id')

# 2. Add a request with test script
curl -X POST "$BASE/api-tester/collections/$COLLECTION_ID/requests" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Get Users",
    "requestData": {"method": "GET", "url": "http://127.0.0.1:5770/stubs/sandbox/api/users"},
    "testScript": "mk.test(\"Status is 200\", function() { mk.response.to.have.status(200); });"
  }'

# 3. Execute the collection (runs all requests + test scripts)
RUN_ID=$(curl -s -X POST "$BASE/api-tester/collections/$COLLECTION_ID/execute" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r '.testRunId')

# 4. Poll for results
curl -s "$BASE/api-tester/test-runs/$RUN_ID" \
  -H "X-API-Key: $TOKEN" | jq '.status, .summary'

CLI

# Run a collection stored in Mockarty, by name
mockarty-cli run collection "CI Tests"

# Or a collection file, exporting a JUnit report for CI
mockarty-cli run -f ci-tests.json --reporter junit:results.xml

Go

// Create a collection and execute it
col, err := client.Collections().Create(context.Background(), &mockarty.Collection{
    Name:        "CI Tests",
    Description: "Automated test suite",
})

// Execute the collection
run, err := client.Collections().Execute(context.Background(), col.ID)
fmt.Printf("Run ID: %s, Status: %s\n", run.ID, run.Status)

Python

# Create a collection and execute it
col = client.collections.create({
    "name": "CI Tests",
    "description": "Automated test suite",
})

# Execute the collection
run = client.collections.execute(col.id)
print(f"Run ID: {run.id}, Status: {run.status}")

Java

// Create a collection and execute it
Map<String, Object> col = client.collections().create(Map.of(
    "name", "CI Tests",
    "description", "Automated test suite"
));

String collectionId = (String) col.get("id");
Map<String, Object> run = client.collections().execute(collectionId);
System.out.println("Run ID: " + run.get("testRunId"));

Running Performance Tests from CI

The cURL and SDK examples submit a test to Mockarty, so connect a runner first. The CLI examples run locally unless you select server execution. Replace the script’s stub URL if your Mockarty server is not local.

cURL

TOKEN="${MOCKARTY_API_KEY:?Set MOCKARTY_API_KEY first}"
BASE="${MOCKARTY_URL:-http://127.0.0.1:5770}/api/v1"

# Run a performance test with an inline script
curl -X POST "$BASE/perf/run" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "import http from \"k6/http\"; export default function() { http.get(\"http://localhost:5770/stubs/sandbox/api/users\"); }",
    "options": {"vus": 10, "duration": "30s"}
  }'

# Check results
curl -s "$BASE/perf-results" -H "X-API-Key: $TOKEN" | jq '.[0]'

CLI

# Run a performance test from a saved perf-config file
mockarty-cli perf run --from-config load-test.json

# Run a script with inline load options
mockarty-cli perf run ./load-test.js --vus 10 --duration 30s

Go

// Run a performance test
task, err := client.Perf().Run(context.Background(), &mockarty.PerfConfig{
    Script:  `import http from "k6/http"; export default function() { http.get("http://localhost:5770/stubs/sandbox/api/users"); }`,
    Options: &mockarty.PerfOptions{VUs: 10, Duration: "30s"},
})
fmt.Println("Task ID:", task.ID)

// List results
results, err := client.Perf().ListResults(context.Background())

Python

# Run a performance test
result = client.perf.run({
    "script": 'import http from "k6/http"; export default function() { http.get("http://localhost:5770/stubs/sandbox/api/users"); }',
    "options": {"vus": 10, "duration": "30s"},
})

# List results
results = client.perf.list_results()

Java

// Run a performance test
Map<String, Object> result = client.perf().run(Map.of(
    "script", "import http from \"k6/http\"; export default function() { http.get(\"http://localhost:5770/stubs/sandbox/api/users\"); }",
    "options", Map.of("vus", 10, "duration", "30s")
));

Running Fuzzing from CI

Replace https://api.example.com with an API you are allowed to test. The cURL and SDK examples need a connected runner; the CLI example runs locally.

cURL

TOKEN="${MOCKARTY_API_KEY:?Set MOCKARTY_API_KEY first}"
BASE="${MOCKARTY_URL:-http://127.0.0.1:5770}/api/v1"

# 1. Create fuzz config
CONFIG_ID=$(curl -s -X POST "$BASE/fuzzing/configs" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Fuzz",
    "targetBaseUrl": "https://api.example.com",
    "sourceType": "manual",
    "strategy": "security",
    "seedRequests": [{"id": "seed-1", "method": "POST", "url": "/api/users"}],
    "payloadCategories": ["sqli", "xss"],
    "options": {"maxRequests": 100, "concurrency": 2}
  }' | jq -r '.id')

# 2. Start fuzz run
RUN_ID=$(curl -s -X POST "$BASE/fuzzing/run" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"configId": "'$CONFIG_ID'"}' | jq -r '.resultId')

# 3. Check findings for this run
curl -s "$BASE/fuzzing/findings?runId=$RUN_ID" \
  -H "X-API-Key: $TOKEN" | jq '.findings'

CLI

# Fuzz an API described by an OpenAPI spec
mockarty-cli fuzz --target http://target:8080 \
  --spec openapi.yaml \
  --categories sqli,xss \
  --duration 1m

Go

// Create a fuzz config and run it
config, err := client.Fuzzing().CreateConfig(context.Background(), &mockarty.FuzzingConfig{
    Name:              "API Fuzz",
    TargetBaseURL:     "https://api.example.com",
    SourceType:        "manual",
    Strategy:          "security",
    SeedRequests:      []map[string]any{{"id": "seed-1", "method": "POST", "url": "/api/users"}},
    PayloadCategories: []string{"sqli", "xss"},
    Options:           map[string]any{"maxRequests": 100, "concurrency": 2},
})

run, err := client.Fuzzing().StartFromConfig(context.Background(), config.ID)

// Check findings
findings, err := client.Fuzzing().ListFindings(context.Background())
for _, finding := range findings {
    if finding.RunID == run.ID { fmt.Println(finding.Title) }
}

Python

# Create a fuzz config and run it
config = client.fuzzing.create_config({
    "name": "API Fuzz",
    "targetBaseUrl": "https://api.example.com",
    "sourceType": "manual",
    "strategy": "security",
    "seedRequests": [{"id": "seed-1", "method": "POST", "url": "/api/users"}],
    "payloadCategories": ["sqli", "xss"],
    "options": {"maxRequests": 100, "concurrency": 2},
})

run = client.fuzzing.start_from_config(config.id)

# Check findings
findings = [f for f in client.fuzzing.list_findings() if f.get("runId") == run.id]

Java

// Create the config with the cURL example above, then use its returned ID.
String configId = "<config-id>";
FuzzingRun run = client.fuzzing().startFromConfig(configId);
List<FuzzingFinding> findings = client.fuzzing().listFindings().stream()
    .filter(f -> run.getId().equals(f.getRunId()))
    .toList();

Importing OpenAPI/Postman/HAR

cURL

TOKEN="${MOCKARTY_API_KEY:?Set MOCKARTY_API_KEY first}"
BASE="${MOCKARTY_URL:-http://127.0.0.1:5770}/api/v1"

# Send the OpenAPI file as JSON content and generate mocks in sandbox
jq -Rs --arg ns sandbox '{content: ., namespace: $ns}' < openapi.yaml | curl -X POST "$BASE/generators/openapi" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

# Import Postman collection to API Tester
# (the exported file's JSON goes under the collectionJson key)
curl -X POST "$BASE/api-tester/import/postman" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"collectionJson\": $(cat collection.json)}"

# Import Postman environment (*.postman_environment.json);
# activate=true makes it your active environment right away
curl -X POST "$BASE/api-tester/import/postman-env" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"environmentJson\": $(cat staging.postman_environment.json), \"activate\": true}"

# Import HAR recording (file content under the content key)
curl -X POST "$BASE/api-tester/import/har" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(jq -Rs . < recording.har)}"

# Import WSDL for SOAP testing — from a URL or inline content
curl -X POST "$BASE/api-tester/import/wsdl" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/service?wsdl"}'

CLI

# Generate mocks from an OpenAPI spec (namespace defaults to "sandbox")
mockarty-cli --namespace sandbox generate openapi openapi.yaml --upload

# Convert a Postman collection into mock files
mockarty-cli generate postman collection.json

# Generate mocks from a HAR recording
mockarty-cli generate har recording.har

Go

// Generate mocks from an OpenAPI/Swagger spec
spec, _ := os.ReadFile("openapi.yaml")
result, err := client.Generator().FromOpenAPI(context.Background(), &mockarty.GeneratorRequest{
    Spec:      string(spec),
    Namespace: "sandbox", // optional, "sandbox" is the default
})

// Import a Postman collection
data, _ := os.ReadFile("collection.json")
importResult, err := client.Import().Postman(context.Background(), data)

Python

# Generate mocks from an OpenAPI/Swagger spec
result = client.generator.from_openapi({
    "content": open("openapi.yaml").read(),
    "namespace": "sandbox",  # optional, "sandbox" is the default
})

# Import a Postman collection
import json
import_result = client.imports.postman(json.load(open("collection.json")))

Java

// Generate mocks from an OpenAPI/Swagger spec
GeneratorResponse result = client.generator().fromOpenAPI(
    new GeneratorRequest()
        .spec(Files.readString(Path.of("openapi.yaml")))
        .namespace("sandbox"));

// Import a Postman collection
ImportResult importResult = client.imports().postman(
    Files.readString(Path.of("collection.json")), "sandbox");

Setting Up Mocks Before Tests

cURL

# Create a mock for the sandbox workspace
TOKEN="${MOCKARTY_API_KEY:?Set MOCKARTY_API_KEY first}"
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ci-user-service",
    "namespace": "sandbox",
    "http": {"route": "/api/users/list", "httpMethod": "GET"},
    "response": {
      "statusCode": 200,
      "payload": {"id": "$.fake.UUID", "name": "Test User"}
    }
  }'

# Verify mock is active
curl http://localhost:5770/stubs/sandbox/api/users/list
# Returns: {"id": "a1b2c3d4-...", "name": "Test User"}

# Cleanup after tests
curl -X DELETE -H "X-API-Key: $TOKEN" \
  http://localhost:5770/api/v1/mocks/ci-user-service

CLI

# Create a mock from a JSON file
mockarty-cli mock create --file ci-mocks.json

# Verify mock is active
curl http://localhost:5770/stubs/sandbox/api/users/list

# Cleanup after tests
mockarty-cli mock delete ci-user-service

Go

// Create mock for CI
mock := mockarty.NewMockBuilder().
    ID("ci-user-service").
    Namespace("sandbox").
    HTTP(func(h *mockarty.HTTPBuilder) {
        h.Route("/api/users/list").Method("GET")
    }).
    Response(func(r *mockarty.ResponseBuilder) {
        r.Status(200).JSONBody(map[string]any{
            "id":   "$.fake.UUID",
            "name": "Test User",
        })
    }).
    Build()

_, err := client.Mocks().Create(context.Background(), mock)

// ... run tests ...

// Cleanup
err = client.Mocks().Delete(context.Background(), "ci-user-service")

Python

# Create mock for CI
mock = (
    MockBuilder.http("/api/users/list", "GET")
    .id("ci-user-service")
    .namespace("sandbox")
    .respond(200, body={"id": "$.fake.UUID", "name": "Test User"})
    .build()
)
client.mocks.create(mock)

# ... run tests ...

# Cleanup
client.mocks.delete("ci-user-service")

Java

// Create mock for CI
Mock mock = MockBuilder.http("/api/users/list", "GET")
    .id("ci-user-service")
    .namespace("sandbox")
    .respond(200, Map.of("id", "$.fake.UUID", "name", "Test User"))
    .build();

client.mocks().create(mock);

// ... run tests ...

// Cleanup
client.mocks().delete("ci-user-service");