TMH ファイル形式の仕様

Test Manager プロジェクトのバックアップと移行のための TMH ファイル形式の仕様です。マニフェストの構造、オブジェクトの種類、エンコードの要件が記載されています。

.tmh ファイルは、UiPath Test Manager で使用されるプロジェクトのバックアップ/移行形式です。このドキュメントでは、その構造、内容、およびエンコードの要件について詳しく説明します。

アーカイブの構造

<package-name>.tmh               ← ZIP archive
├── manifest.json                ← Package metadata and object counts
└── objects/
    ├── requirements/
    │   └── requirements-{n}.json
    ├── testcases/
    │   └── testcases-{n}.json
    ├── teststeps/
    │   └── teststeps-{n}.json
    ├── testsets/
    │   └── testsets-{n}.json
    ├── testsettestcaseassignments/
    │   └── testsettestcaseassignments-{n}.json
    ├── requirementtestcaseassignments/
    │   └── requirementtestcaseassignments-{n}.json
    ├── objectlabels/
    │   ├── objectlabels-testcase-{n}.json
    │   ├── objectlabels-testset-{n}.json
    │   ├── objectlabels-requirement-{n}.json
    │   ├── objectlabels-testexecution-{n}.json
    │   └── objectlabels-testcaselog-{n}.json
    ├── customfieldvalues/
    │   ├── customfieldvalues-testcase-{n}.json
    │   └── customfieldvalues-requirement-{n}.json
    ├── customfieldlabels/
    │   └── customfieldlabels-{n}.json
    ├── customfielddefinitions/
    │   └── customfielddefinitions-{n}.json
    ├── attachments/
    │   ├── attachments-testexecution-{n}.json
    │   ├── attachments-requirement-{n}.json
    │   ├── attachments-testcaselog-{n}.json
    │   ├── attachments-teststeplog-{n}.json
    │   └── attachments-project-{n}.json
    ├── testexecutions/
    │   ├── testexecutions-Manual-Finished-{n}.json
    │   ├── testexecutions-Automated-Finished-{n}.json
    │   └── testexecutions-Mixed-Finished-{n}.json
    ├── testcaselogs/
    │   └── testcaselogs-{n}.json
    ├── teststeplogs/
    │   └── teststeplogs-{n}.json
    ├── testcaselog-assertions/
    │   └── testcaselogassertions-{n}.json
    ├── testcaselogresultoverrides/
    │   └── testcaselogresultoverrides-{n}.json
    ├── assertion-attachments/
    │   └── assertion-attachments-{n}.json
    ├── defects/
    │   └── defects-{n}.json
    ├── parameters/
    │   └── parameters-{n}.json
    ├── testsetpackages/
    │   └── testsetpackages-{n}.json
    ├── testsettestcaseparameters/
    │   └── testsettestcaseparameters-{n}.json
    ├── testsetschedules/
    │   └── testsetschedules-testset-{n}.json
    ├── objectfilters/
    │   └── objectfilters-testset-{n}.json
    ├── projectauthorization/
    │   └── projectauthorization-{n}.json
    ├── projectsettings/
    │   └── projectsettings.json         ← singular, no number suffix
    └── prompts/
        └── prompts-{n}.json

注:

実際にエクスポートされたオブジェクトの種類のみが存在します。見つからないフォルダー/ファイルは、インポート中に通知なしにスキップされます。

ファイルの命名規則

ほとんどのオブジェクトの種類 — 番号付きのチャンク

ファイルには <type>-{n}.json という名前が付けられます。{n} は、システムによって生成される実際のエクスポートを対象として、0 から始まります。以下に例を示します。

requirementtestcaseassignments-0.json
testcases-0.json
teststeps-0.json

インポーターは各フォルダー内のすべてのファイルをスキャンするため、ファイルを手動で作成する場合、0 ベースの番号付けと 1 ベースの番号付けのどちらも有効です。

大規模なエクスポートは複数のファイル (testcases-0.json、testcases-1.json など) に分割される場合があります。インポーターはフォルダー内のすべてのファイルを読み取ります。

ヒント:

最適なパフォーマンスを得るには、各ファイルを最大 500 個のオブジェクトに制限します。

種類によって範囲が設定されるファイルの名前

いくつかのオブジェクトの種類では、そのファイルが属するオブジェクトの種類によって、ファイルの範囲が設定されます。インポーターは修飾子に関係なくフォルダー内のすべてのファイルを読み取りますが、実際のエクスポートでは常に以下の名前が使用されます。

オブジェクトの種類	ファイル名のパターン
ObjectLabels	objectlabels-testcase-{n}.json、objectlabels-testset-{n}.json、objectlabels-requirement-{n}.json、...
CustomFieldValues	customfieldvalues-testcase-{n}.json, customfieldvalues-requirement-{n}.json
添付ファイル	attachments-testexecution-{n}.json、attachments-requirement-{n}.json、...
テスト実行	testexecutions-Manual-Finished-{n}.json、testexecutions-Automated-Finished-{n}.json、...
オブジェクト フィルター	objectfilters-testset-{n}.json
テスト セットのスケジュール	testsetschedules-testset-{n}.json

プロジェクト設定 — 番号のサフィックスなし

projectsettings/projectsettings.json

このファイルは常に 1 つだけです (チャンク番号なし)。

エンコードの要件

すべての JSON ファイルは、BOM なしの UTF-8 としてエンコードされている必要があります。

警告:

PowerShell 5.1 の Set-Content -Encoding utf8 は、UTF-8 の BOM (EF BB BF) を書き込みます。これにより、ブラウザーの JSON.parse が位置 0 で SyntaxError: Unexpected token をスローします。.tmh ファイルを PowerShell から作成する場合は、常に [System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding($false))) を使用してください。

スキーマのバージョン管理

manifest.json には schemaVersion フィールドがあります (例: "1.0.16")。インポーターは、このバージョンを各 DTO プロパティの [IntroducedIn] 属性と一緒に使用して、読み取るフィールドを判断します。パッケージのスキーマ バージョンよりも新しいバージョンで導入されたフィールドは、逆シリアル化時に無視されます。

現在の最新バージョン: 1.0.16

バージョン履歴の概要

バージョン	重要な追加項目
1.0.0	初期バージョン: 要件、テスト ケース、テスト ステップ、テスト セット、割り当て、ラベル、添付ファイル、不具合、カスタム フィールド値
1.0.1	preCondition (テスト ケース)
1.0.2	テスト実行、テスト ケース ログの結果の上書き、アサーション
1.0.4	サブセットのエクスポート (isSubsetExport、exportSubsetDetails)
1.0.5	カスタム フィールドのラベル
1.0.7	ユーザー定義のプロンプト
1.0.9	postCondition (テスト ケース)
1.0.10	パラメーター
1.0.11	テスト セット パッケージ、folderKey/folderName (テスト セット)、packageEntryPointUniqueId など (テスト ケース)
1.0.13	id (添付ファイルのフィールド)
1.0.14	studioWebFileId/studioWebProjectId (テスト ケース)、id (テスト セット/テスト ケースの割り当て)
1.0.15	assigneeEmail (テスト セット/テスト ケースの割り当て)
1.0.16	プロジェクト設定 (設定、ガバナンス、署名者)、カスタム フィールドの定義、プロジェクトの承認

manifest.json

アーカイブのルートにあります (objects/ の内部ではありません)。

{
  "objectCountDetails": {
    "testCases": 5,
    "testSets": 2,
    "requirements": 3,
    "objectLabels": 0,
    "attachments": 0,
    "testExecutions": 0,
    "testCaseLogs": 0,
    "testCaseResultOverrides": 0,
    "testSteps": 12,
    "testStepLogs": 0,
    "testSetTestCaseAssignments": 6,
    "requirementTestCaseAssignments": 4,
    "defects": 0,
    "customFieldValues": 0,
    "customFieldLabels": 0,
    "assertions": 0,
    "assertionScreenshots": 0,
    "testSetLabelFilters": 0,
    "userDefinedPrompts": 0,
    "parameters": 0,
    "testSetPackages": 0,
    "testSetTestCaseParameters": 0,
    "customFieldDefinitions": 0,
    "projectAuthorizations": 0
  },
  "project": {
    "name": "My Project",
    "description": "Project description",
    "projectPrefix": "MP"
  },
  "tmPackageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schemaVersion": "1.0.16"
}

注:

実際のエクスポートには、packageName フィールド (推奨されるダウンロードファイル名) も含まれます。インポーターはこのフィールドを無視します。手動で作成したファイルでは省略してください。

objects/ — JSON ファイル スキーマ

すべてのオブジェクト ファイルはラッパー オブジェクトを使用し、その唯一のプロパティは JSON 配列です。この配列には、個々のオブジェクト レコードが含まれます。

requirements/{n}.json

{
  "requirements": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "User can log in",
      "description": "The login form must accept valid credentials.",
      "foreignRef": "",
      "connectorRequirementId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

フィールド	入力	備考
id	GUID string	要件ごとの一意の識別子です。
name	string	必須です。最大 255 文字です。
description	string	空の文字列にすることができます。
foreignRef	string	外部システム参照です。空にすることができます。
connectorRequirementId	GUID string	コネクタにリンクされていない場合、"00000000-0000-0000-0000-000000000000" が使用されます。

testcases/{n}.json

{
  "testCases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "version": null,
      "name": "Verify login with valid credentials",
      "inputParams": null,
      "description": "",
      "automationId": null,
      "automationTestCaseName": null,
      "automationProjectName": null,
      "foreignRef": "",
      "connectorTestCaseId": null,
      "preCondition": null,
      "postCondition": null,
      "packageEntryPointUniqueId": null,
      "packageIdentifier": null,
      "packageEntryPointName": null,
      "feedId": null,
      "packageSourceName": null,
      "studioWebFileId": null,
      "studioWebProjectId": null
    }
  ]
}

フィールド	入力	備考
id	GUID string	テスト ケースごとに一意です。
version	string | null	null は手動テスト用のテスト ケースの場合です。特定のパッケージ バージョンにリンクされている自動化されたテスト ケースでは "1.0.0" です。固定されたバージョンのない自動化されたテスト ケースでは "" です。
name	string	必須です。最大 255 文字です。
inputParams	string | null	JSON エンコードの入力パラメーターです。手動の場合は null です。
description	string	リッチ テキストの説明です。存在しない場合は "" です。
automationId	string | null	UiPath オートメーション ID です。手動の場合は null です。
automationTestCaseName	string | null	オートメーションの表示名です。手動の場合は null です。
automationProjectName	string | null	オートメーション プロジェクトです。手動の場合は null です。
foreignRef	string	外部システム参照です。存在しない場合は "" です。
connectorTestCaseId	string | null	コネクタのシステム ID です。存在しない場合は null です。
preCondition	string | null (v1.0.1+)	事前条件のテキストです。存在しない場合は null です。最大 8,000 文字です。
postCondition	string | null (v1.0.9+)	事後条件のテキストです。存在しない場合は null です。最大 8,000 文字です。
packageEntryPointUniqueId	string | null (v1.0.11+)	パッケージのエントリ ポイントの GUID です。手動の場合は null です。
packageIdentifier	string | null (v1.0.11+)	パッケージ ID です。手動の場合は null です。
packageEntryPointName	string | null (v1.0.11+)	エントリ ポイント名です。手動の場合は null です。
feedId	string | null (v1.0.11+)	パッケージ フィードの ID です。手動の場合は null です。
packageSourceName	string | null (v1.0.11+)	パッケージ ソース名です。手動の場合は null です。
studioWebFileId	string | null (v1.0.14+)	Studio Web のファイル ID です。手動の場合は null です。
studioWebProjectId	string | null (v1.0.14+)	Studio Web のプロジェクト ID です。手動の場合は null です。

teststeps/{n}.json

{
  "testSteps": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "testCaseId": "550e8400-e29b-41d4-a716-446655440001",
      "orderNo": 0,
      "actionType": null,
      "description": "Navigate to the login page",
      "expectedResult": "Login page is displayed",
      "clipboardData": ""
    }
  ]
}

フィールド	入力	備考
id	GUID string	ステップごとに一意です。
testCaseId	GUID string	既存のテスト ケース id を参照する必要があります。 id
orderNo	integer	0 ベースの表示順序です (最初のステップ = 0)。
actionType	string | null	null は手動ステップの場合です。
description	string	ステップのアクションのテキストです。
expectedResult	string	期待される結果です。存在しない場合は "" です。
clipboardData	string	クリップボード/スクリーンショットのデータです。最大 8,000 文字です。通常は ""

testsets/{n}.json

{
  "testSets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "version": null,
      "name": "Regression Suite",
      "description": "",
      "source": "TestManager",
      "externalTestSetId": null,
      "sourceDetails": null,
      "folderKey": null,
      "folderName": ""
    }
  ]
}

フィールド	入力	備考
id	GUID string	テスト セットごとに一意です。
version	string | null	null は、Test Manager で管理されるテスト セットの場合です。
name	string	必須です。最大 255 文字です。
description	string	"" (存在しない場合)
source	string	"TestManager" (既定) または "Orchestrator" です。整数ではなく文字列です。
externalTestSetId	string | null	source が "Orchestrator" の場合は外部 ID です。それ以外の場合は null です。
sourceDetails	string | null	追加のソース メタデータです。存在しない場合は null です。
folderKey	string | null (v1.0.11+)	UiPath Orchestrator のフォルダー キーです。リンクされていない場合は null です。
folderName	string (v1.0.11+)	フォルダーの表示名です。リンクされていない場合は "" です。DB には保存されず、情報提供のみが目的です。

testsettestcaseassignments/{n}.json

{
  "testSetTestCaseAssignments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440030",
      "testSetId": "550e8400-e29b-41d4-a716-446655440020",
      "testCaseId": "550e8400-e29b-41d4-a716-446655440001",
      "assigneeEmail": null
    }
  ]
}

フィールド	入力	備考
id	GUID string (v1.0.14+)	割り当ての識別子です。
testSetId	GUID string	テスト セット ID を参照します。 id
testCaseId	GUID string	テスト ケース ID を参照します。 id
assigneeEmail	string | null (v1.0.15+)	担当者のメール アドレスです。未割り当ての場合は null です。

requirementtestcaseassignments/{n}.json

{
  "requirementTestCaseAssignments": [
    {
      "requirementId": "550e8400-e29b-41d4-a716-446655440000",
      "testCaseId": "550e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

警告:

id フィールドはありません。他のほとんどのオブジェクトの種類とは異なり、要件とテスト ケースの割り当てには requirementId と testCaseId しかありません。

objectlabels/objectlabels-{objecttype}-{n}.json

注:

ファイルの命名: 実際のエクスポートでは、objectlabels-testcase-1.json、objectlabels-testset-1.json、objectlabels-requirement-1.json など、種類で修飾された名前が使用されます。インポーターは objectlabels/ フォルダー内のすべてのファイルを読み込むため、ファイルを手動で作成する場合は厳密には修飾子は必要ありませんが、規則に従うことをお勧めします。

{
  "objectLabels": [
    {
      "objectId": "550e8400-e29b-41d4-a716-446655440001",
      "name": "regression",
      "description": "",
      "labelType": 0,
      "objectType": "TestCase"
    }
  ]
}

フィールド	入力	備考
objectId	GUID string	ラベル付けされたオブジェクトの ID です。
name	string	ラベルのテキストです。
description	string	ラベルの説明です。存在しない場合は "" です。
labelType	integer	1 = システム ラベルです (例: "manual"、"automated")。0 = ユーザー定義のラベルです。
objectType	string	"TestCase"、"TestSet"、"Requirement"、"TestExecution"、"TestCaseLog"

customfieldvalues/{n}.json

{
  "customFieldValues": [
    {
      "objectId": "550e8400-e29b-41d4-a716-446655440001",
      "objectType": "TestCase",
      "fieldName": "Priority",
      "fieldValue": "High"
    }
  ]
}

projectsettings/projectsettings.json

スキーマ バージョン 1.0.16 で導入されました。[プロジェクト設定をエクスポート] が有効化されている場合にのみ存在します。

{
  "projectTimeZone": "Europe/Vienna",
  "folderKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "governanceEnabled": true,
  "governedByDefault": false,
  "signatories": [
    {
      "signatoryId": "550e8400-e29b-41d4-a716-446655440099",
      "signatoryType": 0,
      "signatoryLastKnownDetails": "[e-mail]"
    }
  ]
}

注:

他のすべてのオブジェクト ファイルとは異なり、projectsettings.json は直接オブジェクトです (ラッパー配列ではありません)。このファイルには、1 つのフラットな JSON オブジェクトが含まれます。

フィールド	入力	備考
projectTimeZone	string | null	IANA 形式のタイムゾーン文字列です (例: "Europe/Vienna")。
folderKey	GUID | null	リンクされている Orchestrator フォルダーです。
governanceEnabled	boolean | null	プロジェクトに対してガバナンスが有効化されているかどうかを示します。
governedByDefault	boolean | null	新しいテスト ケースが既定で管理されるかどうかを示します。
signatories	array | null	承認者/署名者のリストです。
signatories[].signatoryId	GUID	ユーザーまたはグループの ID です。
signatories[].signatoryType	integer	0 = ユーザー、1 = ユーザー グループです。
signatories[].signatoryLastKnownDetails	string	エクスポート時の表示名またはメール アドレスです。

注:

lastDisabledAt (ガバナンスの無効化のタイムスタンプ) は、エクスポートから意図的に除外されています。これは内部タイムスタンプであり、再インポートされたプロジェクトでは意味がありません。

ルールと制約

1. すべての ID は、一意の有効な GUID である必要がある。同じ種類または異なる種類のオブジェクト間で ID を流用しないでください。

2. 相互参照を解決できる必要がある。テスト ステップまたは割り当て内の testCaseId は、同じパッケージに存在するテスト ケース id を参照する必要があります。

3. ラッパー オブジェクトが必要である。コレクションの項目が 1 つであっても、{ "testCases": [ {...} ] } のようにラップする必要があります。裸の配列やオブジェクトにしないでください。

4. null と "" に関する規則: null は、実際には存在しない任意のフィールドに使用します (例: automationId、inputParams、preCondition、connectorTestCaseId、手動テスト用のテスト ケースのすべての package* フィールド)。"" は、常に文字列として存在するものの、たまたま空であるフィールドにのみ使用します (例: foreignRef、description、clipboardData)。これらを混在させると (特に null が予期される場所で "" を使用すると)、インポートが通知なしに失敗する可能性があります。

5. マニフェスト内の objectCountDetails は、存在するオブジェクトの実際の数と一致する必要がある。ただし、インポーターは数を厳密に検証しません。不一致があってもインポート前の概要の表示にしか影響しません。

6. BOM なしの UTF-8 がすべてのファイルで必須である。

最小限の有効な TMH ファイル (手動で作成)

Test Manager で受け入れられる最小の有効な .tmh ファイルには、次のような manifest.json のみが含まれます。

{
  "objectCountDetails": { ... },
  "project": { "name": "Test Project", "description": "", "projectPrefix": "TP" },
  "tmPackageId": "<new-guid>",
  "schemaVersion": "1.0.16"
}

objects/ サブディレクトリはすべて任意です。インポーターは、アーカイブに存在しないオブジェクトの種類を通知なしにスキップします。