Поиск сущностей (имя → ID)

Mockarty предоставляет единый эндпоинт универсального пикера: он
переводит человекочитаемое имя в каноничный UUID для всех ключевых типов
сущностей. UI-пикеры (билдер айтемов Тест-плана, билдер расписаний,
билдер вебхуков, объединение Test Runs, DAG-редактор) используют именно
этот эндпоинт. API, CLI, SDK и MCP-инструмент дают одинаковую
поверхность: скрипты и AI-агенты видят те же данные, что и человек в UI.

О URL в примерах: все примеры используют http://localhost:5770.
Замените на адрес вашей установки. См.
Полезные функции и советы.

Связанные страницы: Руководство по CLI ·
Руководство по SDK · Справочник API

Когда применять

• CI/CD пайплайны — превратить имя Тест-плана в ID перед запуском.
• Кросс-сущностный поиск — найти всё в пространстве имён, что называется
  checkout, одним вызовом.
• AI-агенты — MCP-агент сначала вызывает search_entities, чтобы
  превратить человеческую фразу в ID, нужные другим инструментам.

Поддерживаемые типы

mock, test_plan, perf_config, fuzz_config, chaos_experiment,
contract_pact, request, collection, ui_test, wiki_page,
whiteboard, test_case, issue, user.

request и collection — сущности API Tester; полезны при построении
тест-планов с функциональными HTTP-шагами. ui_test показывает сохранённые
UI-записи, чтобы пункт тест-плана мог ссылаться на них напрямую. wiki_page
ищет по заголовку и тексту страницы; whiteboard — по имени и описанию
доски. test_case находит тест-кейсы TCM по имени или описанию и вместе с
id возвращает короткий номер кейса. issue находит задачи трекера по
заголовку или ключу (например, MK-12); задачи приватных проектов видны
только их участникам. user находит участников текущего пространства по
логину (алиас member) и возвращает логин вместе с id пользователя — это
подсказки для фильтра «Удалил» на странице Корзины; адреса электронной почты
никогда не возвращаются.

Эндпоинт

Параметры запроса:

Ответ:

{
  "items": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "type": "test_plan",
      "name": "smoke-suite",
      "namespace": "production",
      "createdAt": "2026-04-19T12:00:00Z",
      "numericId": 42
    }
  ],
  "total": 1
}

numericId присутствует только у сущностей со стабильным числовым ID
(сейчас — Тест-планы). items всегда возвращается как массив: он может
быть пустым [], но не null. Для test_plan поле total учитывает все
совпадающие активные планы в выбранном пространстве имён, даже если первая
страница содержит лишь часть каталога. Увеличивайте offset, пока не
прочитаете total строк. Символы % и _ в q ищутся как обычный текст.

Аутентификация

Передавайте API-токен через заголовок X-API-Key. Токены создаются в
Настройки → API-токены (или POST /api/v1/auth/tokens). Тенант-токены
молча игнорируют ?namespace= — побеждает пространство имён, привязанный к
токену.

export MOCKARTY_URL=http://localhost:5770
export MOCKARTY_API_TOKEN=mk_7_...
export MOCKARTY_NAMESPACE=default

Найти все Тест-планы со словом “smoke”

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/entity-search?type=test_plan&q=smoke&limit=25"

CLI

mockarty-cli search test_plan --query smoke --limit 25

Go

resp, err := client.EntitySearch().Search(ctx, mockarty.EntitySearchRequest{
    Type:  mockarty.EntityTypeTestPlan,
    Query: "smoke",
    Limit: 25,
})
for _, it := range resp.Items {
    fmt.Printf("%s  %s\n", it.ID, it.Name)
}

Python

resp = client.entity_search.search(
    entity_type="test_plan",
    query="smoke",
    limit=25,
)
for item in resp.items:
    print(item.id, item.name)

Java

EntitySearchResponse resp = client.entitySearch().search(
    new EntitySearchRequest()
        .type(EntitySearchRequest.TYPE_TEST_PLAN)
        .query("smoke")
        .limit(25));
for (EntitySearchResult item : resp.getItems()) {
    System.out.println(item.getId() + "  " + item.getName());
}

Перебор моков в активном пространстве имён

При поиске моков поле total учитывает все совпадения в доступном каталоге,
включая записи за пределами первой страницы. Если в каталоге больше 10 000
моков, поиск возвращает ошибку вместо неполного результата. При глобальном
поиске выберите одно пространство имён; если оно само больше лимита,
используйте отдельный API списка моков.

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/entity-search?type=mock&limit=50&offset=0"

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/entity-search?type=mock&limit=50&offset=50"

CLI

mockarty-cli search mock --limit 50 --offset 0
mockarty-cli search mock --limit 50 --offset 50

Go

for offset := 0; ; offset += 50 {
    resp, err := client.EntitySearch().Search(ctx, mockarty.EntitySearchRequest{
        Type:   mockarty.EntityTypeMock,
        Limit:  50,
        Offset: offset,
    })
    if err != nil || len(resp.Items) == 0 {
        break
    }
    // ... обработать resp.Items
}

JSON-вывод в CLI

CLI поддерживает глобальный флаг --output json, что удобно для
пайплайна с jq в CI:

mockarty-cli --output json search test_plan --query smoke \
  | jq -r '.items[] | [.id, .name] | @tsv'

Вызов из AI-агента (MCP)

Агенты ходят во встроенный MCP-сервер Mockarty. Вызывайте инструмент
search_entities перед инструментами, которым нужен ID:

{
  "name": "search_entities",
  "arguments": {
    "type": "test_plan",
    "q": "smoke",
    "limit": 25
  }
}

Агент получает тот же конверт { "items": [...], "total": N } и может
передать items[].id в run_test_plan, get_test_plan и т. п.

Ошибки

CLI, SDK и MCP-инструмент возвращают те же ошибки ещё до отправки HTTP-
запроса: опечатка в названии типа отлавливается локально.