TestIT Integration Guide

This guide covers two separate paths: pulling a Test IT case catalogue into
Mockarty, and sending JUnit XML results through mockarty-cli. A converted
JSON input is also available. Existing Test IT adapters send HTTP
requests directly to Test IT, so changing three environment variables alone
does not redirect them to Mockarty.

Mockarty does not serve the TestIT /api/v2/* wire protocol.
The translation happens inside mockarty-cli, which parses a JUnit XML file
or an explicitly converted JSON bundle locally and posts the normalised payload
to the canonical /tcm/external-runs endpoint Mockarty already
exposes for Allure + Ginkgo + pytest.

1. CLI connection settings

Replace the three TestIT-side env vars in your CI config:

mockarty-cli accepts both the TMS_* and MOCKARTY_* flavours.
If the MOCKARTY_* form is empty, the TMS_* form is picked up
automatically by Mockarty’s CLI commands. Set the URL to your Mockarty
admin and use a Mockarty API token and namespace; a Test IT token and numeric
project ID are not interchangeable with these values.

# Settings for mockarty-cli testit commands.
export TMS_URL=https://mockarty.example.com
export TMS_PRIVATE_TOKEN=<your Mockarty API token>
export TMS_PROJECT_ID=team-a

Token format

If you copy the raw Authorization header (PrivateToken hexhex…)
into TMS_PRIVATE_TOKEN, mockarty-cli strips the PrivateToken
prefix automatically. The same applies to a Bearer hexhex… prefix.
You don’t need to clean the value by hand.

2. CI results from JUnit XML

If your test runner produces JUnit XML, point --results/-r at a file or a
directory of XML files. mockarty-cli accepts the corresponding Test IT
testit-cli results upload option names, including --configuration-id/-ci,
--testrun-id/-ti, --separator/-s, --namespace/-ns (JUnit identity),
--classname/-cn, and --ignore-flaky-failure/-iff. The target Mockarty
namespace comes from TMS_PROJECT_ID or MOCKARTY_NAMESPACE.

# 1. Create a test run for this CI execution.
export TMS_TEST_RUN_NAME="CI #${CI_PIPELINE_IID}"
mockarty-cli testit testrun create --output ./testrun.id
RUN_ID=$(cat ./testrun.id)

# 2. Run tests; configure your runner to write JUnit XML to ./junit-reports.

# 3. Upload all JUnit XML files. The run ID is read from ./testrun.id here.
mockarty-cli testit results upload --results ./junit-reports --testrun-id "$RUN_ID"

# 4. Close the run.
mockarty-cli testit testrun complete "$RUN_ID"

An empty directory, malformed XML, or a file with no test cases fails the
command before any results are sent. A failed or cancelled run makes
testrun complete exit nonzero.

JUnit XML carries the test name, classname, duration, and pass/fail/error/skip
markers. It does not carry Test IT framework steps, inline images,
attachments, parameters, or arbitrary metadata. To move those, use a richer
adapter or a converted JSON bundle with the referenced attachment files.
Official Test IT framework adapters submit HTTP requests directly to Test IT;
replacing this CLI binary does not redirect their traffic.

Converted JSON bundle

If your own converter produces a JSON array of
AutoTestResultsForTestRunModel objects, keep using --file:

mockarty-cli testit results upload --file ./converted-results.json

For example, converted-results.json can contain:

[{"autoTestExternalId":"suite.test_login","outcome":"Passed","duration":250}]

What the upload does

results upload parses every JUnit case or converted JSON element and POSTs each
one (in parallel batches with retry/backoff) to:

POST /api/v1/namespaces/<ns>/tcm/external-runs

Converted JSON can carry per-result files when --attachments-dir contains
the referenced files named by attachment ID (or ID plus extension). Nested
step files are stored on the result with their original step path in metadata.
The command fails before uploading results if a referenced file is absent,
empty, or over the inline limit of 256 KiB per file (1 MiB per result, up to
32 files). Larger source files need the full migration workflow; this CLI
upload cannot preserve them yet. Result configuration ID, work item IDs,
links, properties and nested steps are kept with the case run.

3. Configuration UUIDs

TestIT uses configurationId as a UUID handle for “the environment
my tests ran under” (Chrome vs Safari, prod vs staging, …).

Mockarty stores configurations as a first-class entity:

# Mint a fresh UUID for CI.
export TMS_CONFIGURATION_ID="$(mockarty-cli testit configuration generate)"

# List existing configurations for this namespace.
mockarty-cli testit configuration list

# Create a configuration with a human-readable name.
mockarty-cli testit configuration create \
    --id "$TMS_CONFIGURATION_ID" \
    --name "Chrome / prod"

Once TMS_CONFIGURATION_ID is set, every result the CLI uploads
during this CI run is tagged with that UUID. The Mockarty reports
panel renders a by configuration breakdown so you can compare
runs across different environments in one launch.

4. Workflow states

The standard Mockarty test-case workflow has five states: Draft, In Review,
Changes Requested, Active, and Archived. Your namespace can use a different
workflow.

TestIT’s own work-item states are a shorter set (NeedsWork,
NotReady, Ready, plus any states your project defined). The importer
carries each case’s state over: the TestIT value is matched against the
namespace’s workflow states by code first, then by label, ignoring case
and surrounding spaces. The Test IT API’s default NotReady state maps to
Mockarty’s draft when that state exists. An exact namespace match takes
precedence; other source states, including Ready, need a matching code or
label in your chosen workflow. Re-importing updates the case’s mapped state
when it changes in Test IT.
A new case whose state has no equivalent keeps the namespace default;
an existing case keeps its current state. The import summary’s warnings
array names the case and source state so you can add a matching state
(or rename an existing one) and re-import.

States are user-editable (rename / recolor / add new ones). The
POST /tcm/workflow-states API and the Admin UI both surface CRUD.

List the workflow states (and their UUIDs) via the API:

curl -H "X-API-Key: mk_..." \
  http://localhost:5770/api/v1/namespaces/<ns>/tcm/workflow-states

5. Binary alias for supported commands

You can symlink the binary for the supported testit subcommands:

ln -s /usr/local/bin/mockarty-cli /usr/local/bin/testit-cli

The CLI routes that binary name to its testit subcommands. This alias does
not make Mockarty implement the Test IT HTTP API or accept every upstream
testit-cli flag.

For CI, you can instead change the command to mockarty-cli testit (or name
the same binary mcrtyctl and run mcrtyctl testit). Point its server and
token settings at Mockarty. The replacement uploads to Mockarty, not to your
Test IT tenant; an old Test IT PAT cannot authenticate to Mockarty.

testrun create --testruntags smoke,nightly saves run tags. results upload
and results import merge --testruntags into an existing run after checking
the input. --autotest-layer API (or TMS_AUTOTEST_LAYER) is retained in
result metadata. Typed --testrunlinks is rejected before upload because a
Mockarty run cannot yet store typed links; remove that flag only if your CI
does not need those links. The retained layer is not yet a filterable native
autotest layer.

6. Feature coverage today

Python pytest tests

For tests using testit-adapter-pytest, install mockarty[test] in its place
and change import testit to import mockarty.testit as testit. Set
MOCKARTY_BASE_URL, MOCKARTY_API_KEY and MOCKARTY_NAMESPACE, then keep
pytest --testit -q. Remove the old adapter dependency: both plugins register
--testit. This wrapper sends results only to Mockarty; Test IT project,
configuration and run IDs do not become Mockarty IDs.

The wrapper supports externalId, displayName, a step(...) context and
addAttachments(...) with text or file content. File bytes are preserved,
subject to the inline limits of 256 KiB per file, 1 MiB and 32 files per
result. Attachments added in a step currently belong to the overall result;
nested and fixture steps, workflow status and TMS_TEST_RUN_ID matching are
not yet preserved by this wrapper. An upload error fails the pytest result.

7. Bulk import a TestIT export

The sections above keep CI flowing into Mockarty result-by-result. To move
your existing TestIT catalogue — sections, cases, steps metadata — over in one
shot, use the live pull described in the next section. It connects to your
TestIT server and reads the catalogue through the TestIT API, and it is the
recommended path.

TestIT’s own UI exports work items as .xlsx, not JSON. If you have such a
file, import it through the spreadsheet endpoint
(POST /api/v1/namespaces/{namespace}/tcm/import/xlsx) instead.

There is also a JSON bulk-import endpoint:

POST /api/v1/namespaces/{namespace}/tcm/import/testit

It takes Mockarty’s own intermediate export shape ({project, sections, workItems, attributes, configurations}) — the structure the live pull builds
internally — not a file TestIT produces. Use it when you have generated that
structure yourself, e.g. from your own TestIT API script. The body is JSON (not
multipart) and is bounded to 64 MiB; larger payloads are rejected with a
validation error.

The CLI reads such a file and posts it for you:

mockarty-cli testit import --file ./testit-export.json

This JSON endpoint has no Test IT connection from which to download referenced
files. A case containing source attachment references fails with an item-level
error instead of silently losing its media. Use the live pull below for those
cases.

No export file? Pull straight from the TestIT server

If you can reach your TestIT server from Mockarty, skip the export file
entirely — Mockarty pulls the project over the TestIT REST API and imports it
through the same pipeline:

POST /api/v1/namespaces/{namespace}/tcm/import/testit/pull

For repeated imports, create a Test IT connection in Settings → Integrations.
Enter the server origin (without a path), project UUID and the ID of a secret
entry containing the PrivateToken. Enable the connection and test project access.
In Test Cases → Import → From Test IT server, select the saved connection:
the token stays on the server and does not need to be entered again.

Use a saved connection through the API with:

{"integrationId":"11111111-2222-3333-4444-555555555555","createPlan":false}

This mode requires test_case:write and integrations:read in the current
namespace. The connection must be enabled and use the Test IT adapter.
Do not supply baseUrl, token or projectId together with integrationId:
the server uses the saved destination and project. Imports run on demand;
creating this connection does not enable background synchronization.

During a pull, transient source responses (429, 502, 503, 504) and
connection failures on read requests are retried at most twice. Mockarty
respects Retry-After; if the source asks for a wait over 30 seconds, the
pull reports the error so you can retry later without exceeding that limit.
Cancelling the import stops the retry wait.

For a one-shot connection, supply the coordinates directly:

curl -X POST http://127.0.0.1:5770/api/v1/namespaces/default/tcm/import/testit/pull \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "baseUrl":   "https://testit.example.com",
        "token":     "<TestIT PrivateToken>",
        "projectId": "0fff1111-2222-3333-4444-555566667777"
      }'

In the UI: Test Cases → Import → From Test IT server — enter the server
URL, a PrivateToken and the project ID, and the pull runs with a live summary
toast when it finishes.

The live pull also fetches attachment bytes referenced by cases and steps,
including referenced shared steps and inline images. Mockarty verifies their
source size and checksum, applies the destination’s file size, quota, MIME and
scanner rules, and keeps the original bytes. Imported files belong to the
target case; source paths and file identities are retained with the case. A
failed file transfer fails that case in the summary. Repeat pulls reuse the
same imported file revision; a source rename is retained as another revision.
HTML step actions keep their source content; the step title becomes readable
text, and inline images open through the imported case’s protected file URL.
After a pull, an open case refreshes automatically if it has no unsaved edits.
Review files that exceed your destination limits before retrying. A live pull
creates reusable shared steps with their available numbered versions and keeps
case references linked to those steps. Files referenced by a shared step are
attached to the imported reusable step.

What it fetches: the section tree, every work item (test cases, checklists,
shared steps — with steps, shared-step references, tags, links, linked tracker
issues, iteration parameters), the project’s custom-attribute definitions (GUID keys resolved to
names and option labels) and the run configurations. The response shape is the
same summary as the file import, plus a warnings array for non-fatal issues
(e.g. an older server without the attributes endpoint).
The result panel keeps the complete warning and error list visible for review.
When additional source data still needs migration, the response includes
warningCode: "source_reconciliation_pending" and unmappedCounts; the panel
shows a translated review message. A case-only pull without outstanding data
does not show that message.

Notes:

• A one-shot token is used only for this pull — it is never stored, logged or
  echoed back.
• Optional body fields: "createPlan": true assembles a test plan over the
  imported cases, "planName" names it.
• Large projects are paged automatically; a pull is bounded to 50 000 work
  items per request. If the project exceeds that limit, an indexed work item
  cannot be read, or the source’s pagination count changes during the pull,
  the pull fails before importing cases. Resolve the source error and retry;
  an incomplete catalogue is never reported as a successful pull.
• Repeat imports match automated cases by the first external ID and manual
  cases by project and work-item ID. Renames preserve the existing target;
  different source cases with the same title remain separate. Legacy input
  without a work-item ID still matches by name.

Or call the endpoint directly:

curl -X POST http://127.0.0.1:5770/api/v1/namespaces/default/tcm/import/testit \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @testit-export.json

Response:

{
  "created": 124,
  "updated": 6,
  "placed": 118,
  "configsCreated": 3,
  "failed": 2,
  "errors": [
    "work item 91f3…: empty name"
  ]
}

Authentication & permissions. Send your Mockarty API token as
Authorization: Bearer <token>. The endpoint requires the test_case:write
permission and the TCM feature. The import only ever touches the namespace
in the URL path.

What gets imported

• Sections → folders. TestIT’s section tree is reconstructed (orphaned and
  cyclic sections are handled defensively, never dropped) and cases are placed
  into the matching folder. A missing section just lands the case at the root.
• Work items → cases. Test cases and checklists become cases. Shared steps
  are skipped (they embed into the cases that reference them).
• Priority is mapped onto Mockarty’s four levels: Lowest/Low → low,
  Medium → medium, High → high, Highest → critical (unknown values default to
  medium).
• Tags and description are carried over. External issues (Jira/etc.)
  and work-item links from the source detail become external references on the
  case. The source issue ID and metadata are retained separately for later
  reconciliation. A project with linked issues should still be checked after import.
• Attributes → custom fields, resolved losslessly: attribute keys (TestIT
  stores them as GUIDs) become their human names, and option-typed values
  (stored as option GUIDs) become their labels. The attribute type is
  preserved. Structured values remain available for later remapping; the case
  sidebar shows readable values and separates source information from your
  custom fields. See TCM Custom Fields.
• Case titles and steps: rich text in a Test IT title becomes a readable
  case name. Step content remains rich text while its short heading is plain
  text, so markup does not appear in the case tree or step list.
• Parameters → custom fields. A parameterized work item’s iteration
  parameters become typed param:<name> custom fields, so the binding is
  preserved on the case.
• Configurations → tcm_configurations. Each TestIT test-run configuration
  (browser/OS/env matrix) is imported as a Mockarty configuration. Its TestIT
  UUID is kept as the configuration’s external_id, so a later
  results upload keyed by that same UUID resolves to the imported
  configuration instead of leaving the run “Unspecified”.
• Automated identity. A work item’s first auto-test externalId becomes the
  case’s external full name, so a re-import or a later
  discovery sync / external run resolves to the same case.

A re-import merges custom fields — values you added by hand in the UI are
preserved; only the keys the import carries are overwritten.

The live pull now reads source plans, suites, test points, runs, detailed
results, available case versions, change history and discussion comments
before it imports cases. If one of these reads fails, no cases are imported;
retry after resolving the source error. Some Test IT servers return 404 for
the versions list even when change history exists. In that case the pull
retains the history and available version snapshots, and records the remaining
gap for reconciliation.

For a historical result, the pull checks its source case-version ID and
number against the saved source snapshot. It copies referenced image and file
bytes, then compares the step IDs and content with the same numbered Mockarty
version. If that version has different content, the pull retains a separate
historical version without changing the current case. Repeating the pull
reuses that version; changed source content under the same identity stops the
import for review. Missing source version identities and shared-step
definitions needed for a historical result stay pending. A result from version 1 is never
assigned to the current version 2 merely because both belong to the same
case. When the source result has a supported terminal outcome and an exact
version binding, the pull creates a native case run on that historical version.
It uses only step outcomes actually present in Test IT: a step comment by
itself does not become a passed step. If Test IT omits a start time, the run
records which available source time was used. A repeated pull reuses the same
run, and source corrections are retained as revisions without replacing local
edits.

An automated result without a test point can occur in an ad-hoc Test IT run.
The pull keeps it in the migration report as pending when its autotest identity
is valid; it does not invent a point, case version or native case run. A result
with outcomes inside a referenced shared step is also pending until those
individual member outcomes can be mapped. A visible parent run alone is not
proof that every shared-step outcome was transferred. Review these pending
items before switching the team.

These additional source records are available for migration reconciliation.
When every point in a source plan resolves to an imported case or checklist,
the pull creates a runnable Mockarty plan with stable case membership. The
plan’s original status, dates, attributes, suite hierarchy, point status and
configuration still require review; the source plan remains pending in the
migration report. Empty plans or plans with unresolved points stay pending
without a misleading subset. Supported historical results and their files are
linked to native case runs after checksum verification; source step comments
remain in the result metadata. Completed source plan runs with one supported
result per point also receive a stable native plan run. Its snapshot contains
only points with actual results; a repeated pull links the same case runs to
those points. Additional source run metadata, unsupported nested step outcomes
and standalone discussion comments still need migration review. The complete autotest catalogue
also remains to be migrated.
Review the reconciliation counts before switching your team to Mockarty.

Deduplication

Repeat imports use the following matching rules:

• Automated work items dedup by their external full name (the auto-test
  externalId).
• Manual work items with a source ID match by project and work-item ID.
  A rename updates the same case. Distinct source cases with identical names
  remain separate: if a name is occupied, the imported name receives a stable
  [Test IT …] suffix. The original name and source IDs remain in the case’s
  mockarty:testit:* custom fields.
• Legacy input without any work-item ID still matches by exact name.

An existing same-name case without a source binding is not automatically adopted.
This also applies to older imports made before source IDs were retained. Review
those records before another import; an unbound legacy case can remain alongside
its newly bound counterpart. Source attributes must not use the reserved
mockarty:testit: field prefix. The optional generated plan includes the exact
cases imported in this request, even when their original names match.

Supplied steps are reconciled on repeat import. Identical steps do not create
another version; an explicit empty step list clears them, while an absent list
leaves existing steps unchanged. A missing shared-step reference fails that case
instead of silently removing its content. If a step save fails after the case
was created, repeat the import: its source identity is retained for the retry.

8. Troubleshooting

401 on every call. Verify the token by running
mockarty-cli testit auth login — it lists the Mockarty namespaces the
Mockarty token can access. If the value starts with PrivateToken or
Bearer , the CLI strips that text; this does not convert a Test IT token
into a Mockarty token.

configuration_id must be a UUID. TestIT clients sometimes emit
brace-wrapped UUIDs ({abc-...}); the CLI accepts both forms but
you must mint a valid UUID first via testit configuration generate.

Cross-tenant results. Mockarty namespaces map 1:1 to TestIT
projects. A token bound to team-a cannot upload into team-b —
the call returns 403.

9. See also

• CLI Command Reference
• Allure Annotations Guide — sister
  adapter; same /tcm/external-runs endpoint underneath
• Test Discovery Sync — register your whole inventory from CI
• TCM Custom Fields
• Postman / Newman Migration