Test Discovery Sync

About URLs in examples: all examples use 127.0.0.1:5770 as the default Mockarty address. If your instance runs on a remote server, replace it with the actual address. See Tips & Useful Features for details.

Test discovery sync registers your whole test inventory into the TCM
catalogue from CI — including tests that did not run in the current build.
You upload a small JSON manifest listing every test your framework collected,
and Mockarty reconciles it against the namespace’s test cases: new tests are
created, existing tests keep their human-authored metadata, and tests that
disappeared from your code can be marked orphaned.

This complements external runs: an external run only teaches
Mockarty about a test the moment it executes. Discovery sync keeps the catalogue
a living mirror of the code base, so a test you skipped or quarantined this build
is still visible in TCM.

What it does

Each discovered test is matched by its deterministic identity. If you set an
explicit testCaseId it is the authoritative key (it survives a method or
parameter rename); otherwise the required fullName is used. This is the same
identity an external run resolves on, so a test discovered here and later
executed lands on a single case.

The manifest format

{
  "source": "pytest:auth-suite",
  "framework": "pytest",
  "pruneMissing": true,
  "cases": [
    {
      "testCaseId": "AUTH-1042",
      "fullName": "tests.auth.test_login.test_valid_credentials",
      "name": "Login with valid credentials",
      "suite": "tests.auth.test_login",
      "description": "User can sign in with a correct email + password.",
      "sourceRef": "tests/auth/test_login.py:42",
      "labels": ["auth", "smoke"]
    },
    {
      "fullName": "tests.auth.test_login.test_locked_account",
      "name": "Locked account is rejected",
      "sourceRef": "tests/auth/test_login.py:58"
    }
  ]
}

Sync via the API

POST /api/v1/namespaces/{namespace}/tcm/discovery

curl -X POST http://127.0.0.1:5770/api/v1/namespaces/default/tcm/discovery \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @manifest.json

Response:

{
  "source": "pytest:auth-suite",
  "created": 2,
  "updated": 18,
  "orphaned": 1,
  "total": 20
}

Authentication & permissions. Send your API token as
Authorization: Bearer <token>. The endpoint requires the test_case:write
permission (a manifest is a write into the workspace) and the TCM feature.

Sync via the CLI

The CLI wraps the endpoint as mockarty-cli tcm discover. The manifest is read
from a file (--manifest <path>) or stdin (--manifest -).

# From a file, scoping + pruning this source:
mockarty-cli tcm discover --manifest cases.json --source pytest:auth-suite --prune

# From stdin, in a CI pipe:
pytest --collect-only -q | my-converter | \
  mockarty-cli tcm discover --manifest - --source pytest:auth-suite --framework pytest --prune

Flag values win over the manifest’s own top-level fields, so a generic converter
can emit a source-less manifest that CI then scopes per-suite.

Orphaning semantics (pruneMissing)

Pruning is per-source and non-destructive:

• Without pruneMissing (or --prune), the sync only ever adds and
  updates — nothing is orphaned.
• With it, Mockarty compares the cases previously discovered under this exact
  source against the current manifest. Any that vanished are marked
  orphaned — a soft state, never a delete. They remain visible and
  exportable so QA can decide whether the test was intentionally removed.
• Because pruning is scoped to a single source, running the auth-suite
  manifest never touches cases discovered by your checkout-suite manifest.

A re-sync of an unchanged manifest is idempotent: it creates nothing new and
orphans nothing extra.

Rate limiting (HTTP 429)

A manifest can carry thousands of cases, each an upsert. To protect the database
when a large CI fleet syncs at once, the server bounds the number of
simultaneous in-flight syncs. When that ceiling is reached the endpoint returns
HTTP 429 with a Retry-After: 1 header:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

Back off and retry. The CLI and SDKs retry 429 with backoff automatically. The
concurrency ceiling defaults to four times the server’s CPU count and can be
tuned by the administrator with the MOCKARTY_DISCOVERY_CONCURRENCY environment
variable (clamped to 2–1024).

Notifications

When a sync actually changes the catalogue — new cases created and/or cases
orphaned — Mockarty emits a discovery synced event to the namespace’s
configured webhooks and notification channels, and pushes a live update to any
open case tree so the new/orphaned cases appear without a manual refresh. A
no-op re-sync (everything updated, nothing new or orphaned) stays quiet so CI
runs do not spam your subscribers.

See also

• Test Case Management — the catalogue, external runs, and metadata.
• TestIT Integration Guide — including bulk import of a Test IT export.
• Allure Annotations in Scripts — fullName / testCaseId identity.
• CLI Command Reference — full mockarty-cli surface.