Especificação do formato de arquivo TMH

.tmh arquivo é o formato de backup/migração do projeto usado pelo UiPath Test Manager. Esse documento descreve sua estrutura, conteúdo e requisitos de codificação em detalhes.

Estrutura do arquivo

<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

Observação:

Apenas os tipos de objetos que foram realmente exportados estão presentes. As pastas/arquivos ausentes são ignorados silenciosamente durante a importação.

Convenções de nomenclatura de arquivo

A maioria dos tipos de objetos — partes numeradas

Os arquivos são nomeados <type>-{n}.json onde {n} começa em 0 para exportações reais produzidas pelo sistema. Por exemplo:

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

O importador verifica todos os arquivos em cada pasta, portanto, tanto a numeração baseada em 0quanto a baseada em 1funcionam ao criar arquivos manualmente.

Grandes exportações podem ser divididas entre vários arquivos (testcases-0.json, testcases-1.json etc.) — o importador lê todos os arquivos na pasta.

Dica:

Para obter um desempenho ideal, limite cada arquivo a um máximo de 500 objetos.

Nomes de arquivos com escopo de tipo

Vários tipos de objeto delimitam seus arquivos pelo tipo de objeto ao qual eles pertencem. O importador lê todos os arquivos na pasta independentemente do qualificador, mas as exportações reais sempre usam esses nomes:

Tipo de Objeto	Padrão do nome do arquivo
ObjectLabels	objectlabels-testcase-{n}.json, objectlabels-testset-{n}.json, objectlabels-requirement-{n}.json,…
CustomFieldValues	customfieldvalues-testcase-{n}.json, customfieldvalues-requirement-{n}.json
Anexos	attachments-testexecution-{n}.json, attachments-requirement-{n}.json,…
Execuções de Teste	testexecutions-Manual-Finished-{n}.json, testexecutions-Automated-Finished-{n}.json,…
Filtros de objeto	objectfilters-testset-{n}.json
Agendamentos de Conjuntos de Testes	testsetschedules-testset-{n}.json

Configurações do projeto — sem sufixo de número

projectsettings/projectsettings.json

Esse arquivo é sempre único (sem número de bloco).

Codificação de requisitos

Todos os arquivos JSON devem ser codificados como UTF-8 sem BOM.

AVISO:

O Set-Content -Encoding utf8 do PowerShell 5.1 grava um BOM UTF-8 (EF BB BF). Isso faz com que JSON.parse no navegador gere SyntaxError: Unexpected token na posição 0. Sempre use [System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding($false))) ao criar arquivos .tmh a partir do PowerShell.

Controle de versão de esquema

O manifest.json carrega um campo schemaVersion (por exemplo, "1.0.16"). O importador usa essa versão junto com os atributos [IntroducedIn] em cada propriedade DTO para determinar quais campos ler. Os campos introduzidos em uma versão mais recente que a versão do esquema do pacote são ignorados durante a desserialização.

Versão mais recente atual: 1.0.16

Resumo do histórico da versão:

Versão	Adições notáveis
1.0.0	Inicial: requisitos, casos de teste, etapas de teste, conjuntos de teste, atribuições, rótulos, anexos, defeitos, valores de campo personalizado
1.0.1	preCondition em casos de teste
1.0.2	Execuções de teste, substituições de resultados de log de casos de teste, asserções
1.0.4	Exportação de subconjunto (isSubsetExport, exportSubsetDetails)
1.0.5	Rótulos de campos personalizados
1.0.7	Prompts definidos pelo usuário
1.0.9	postCondition em casos de teste
1.0.10	Parâmetros
1.0.11	Pacotes de conjuntos de testes, folderKey/folderName em conjuntos de testes, packageEntryPointUniqueId etc. em casos de teste
1.0.13	id campo em anexos
1.0.14	studioWebFileId/studioWebProjectId em casos de teste; id em atribuições de conjunto de teste/caso de teste
1.0.15	assigneeEmail em atribuições de conjunto de teste/caso de teste
1.0.16	Configuração do projeto (configurações, governança, signatários), definições de campos personalizados, autorizações do projeto

manifest.json

Localizado na raiz do arquivo (não dentro de 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"
}

Observação:

As exportações reais também incluem um campo packageName (o nome de arquivo de download sugerido). O importador o ignora — omita-o em arquivos criados manualmente.

objetos/ — esquemas de arquivo JSON

Cada arquivo de objeto usa um objeto wrapper cuja única propriedade é uma matriz JSON. A matriz contém os registros de objetos individuais.

requisitos/{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"
    }
  ]
}

Campo	Tipo	Observações
id	String do GUID	Identificador exclusivo por requisito
name	String	Obrigatório; Máx. de 255 caracteres
description	String	Pode ser uma string vazia
foreignRef	String	Referência do sistema externo; pode estar vazio
connectorRequirementId	String do GUID	Use "00000000-0000-0000-0000-000000000000" quando não estiver vinculado a um conector

casos de teste/{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
    }
  ]
}

Campo	Tipo	Observações
id	String do GUID	Exclusivo por caso de teste
version	string | Nulo	null para casos de teste manuais; "1.0.0" casos de teste automatizados vinculados a uma versão do pacote; "" para casos de teste automatizados sem uma versão fixa
name	String	Obrigatório; Máx. de 255 caracteres
inputParams	string | Nulo	Parâmetros de entrada codificados em JSON; null manual
description	String	Descrição em rich text; "" ausente
automationId	string | Nulo	Identificador de automação da UiPath; null manual
automationTestCaseName	string | Nulo	Nome de exibição da automação; null manual
automationProjectName	string | Nulo	Projeto de automação; null manual
foreignRef	String	Referência do sistema externo; "" ausente
connectorTestCaseId	string | Nulo	ID do sistema de conector; null ausente
preCondition	string | nulo (v1.0.1+)	Texto de pré-condição; null ausente; Máx. de 8.000 caracteres
postCondition	string | nulo (v1.0.9+)	Texto de pós-condição; null ausente; Máx. de 8.000 caracteres
packageEntryPointUniqueId	string | nulo (v1.0.11+)	GUID do ponto de entrada do pacote; null manual
packageIdentifier	string | nulo (v1.0.11+)	ID do pacote; null manual
packageEntryPointName	string | nulo (v1.0.11+)	Nome do ponto de entrada; null manual
feedId	string | nulo (v1.0.11+)	ID do feed do pacote; null manual
packageSourceName	string | nulo (v1.0.11+)	Nome da origem do pacote; null manual
studioWebFileId	string | nulo (v1.0.14+)	ID do arquivo do Studio Web; null manual
studioWebProjectId	string | nulo (v1.0.14+)	ID do projeto do Studio Web; null manual

etapas de teste/{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": ""
    }
  ]
}

Campo	Tipo	Observações
id	String do GUID	Exclusivo por etapa
testCaseId	String do GUID	Deve fazer referência a um caso de teste existente id
orderNo	Número inteiro	Ordem de exibição baseada em 0 (primeira etapa = 0)
actionType	string | Nulo	null para etapas manuais
description	String	Texto da ação da etapa
expectedResult	String	Resultado esperado; "" ausente
clipboardData	String	Dados de área de transferência/captura de tela; máximo de 8000 caracteres; Geralmente ""

testessets/{n}.json

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

Campo	Tipo	Observações
id	String do GUID	Exclusivo por conjunto de teste
version	string | Nulo	null para conjuntos de testes gerenciados pelo Test Manager
name	String	Obrigatório; Máx. de 255 caracteres
description	String	"" quando ausente
source	String	"TestManager" (padrão) ou "Orchestrator" é uma string, não um número inteiro
externalTestSetId	string | Nulo	ID externo quando source é "Orchestrator"; null caso contrário
sourceDetails	string | Nulo	Metadados de origem adicionais; null ausente
folderKey	string | nulo (v1.0.11+)	Chave da pasta do UiPath Orchestrator; se null estiver vinculado
folderName	string (v1.0.11+)	Nome de exibição da pasta; se "" estiver vinculado; não armazenado no banco de dados, apenas informativo

testsettestcaseassignments/{n}.json

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

Campo	Tipo	Observações
id	String GUID (v1.0.14+)	Identificador de atribuição
testSetId	String do GUID	Referencia um conjunto de teste id
testCaseId	String do GUID	Referencia um caso de teste id
assigneeEmail	string | nulo (v1.0.15+)	E-mail do destinatário; se null atribuído

requirementstestcaseassignments/{n}.json

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

AVISO:

Nenhum campo id . Ao contrário da maioria dos outros tipos de objetos, as atribuições de caso de requisito de teste têm apenas requirementId e testCaseId.

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

Observação:

Nomenclatura de arquivo: as exportações reais usam um nome qualificado por tipo, como objectlabels-testcase-1.json, objectlabels-testset-1.json, objectlabels-requirement-1.json, etc. O importador lê todos os arquivos na pasta objectlabels/ , portanto, o qualificador não é estritamente necessário ao criar arquivos manualmente, mas é recomendável seguir a convenção.

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

Campo	Tipo	Observações
objectId	String do GUID	ID do objeto rotulado
name	String	Texto do rótulo
description	String	Descrição do rótulo; "" ausente
labelType	Número inteiro	1 = rótulo do sistema (por exemplo "manual", "automated"); 0 = rótulo definido pelo usuário
objectType	String	"TestCase", "TestSet", "Requirement", "TestExecution", "TestCaseLog"

valoresdecampo personalizado/{n}.json

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

projectsettings/projectsettings.json

Introduzido na versão do esquema 1.0.16. Presente apenas quando "Exportar configuração do projeto" está habilitado.

{
  "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]"
    }
  ]
}

Observação:

projectsettings.json contrário de todos os outros arquivos de objeto, é um objeto direto (não uma matriz de wrapper). O arquivo contém um único objeto JSON plano.

Campo	Tipo	Observações
projectTimeZone	string | Nulo	String de fuso horário IANA (por exemplo, "Europe/Vienna")
folderKey	GUID | Nulo	Pasta do Orchestrator vinculada
governanceEnabled	booleano | Nulo	Se a governança está habilitada para o projeto
governedByDefault	booleano | Nulo	Se os novos casos de teste são governados por padrão
signatories	matriz | Nulo	Lista de aprovadores/signatários
signatories[].signatoryId	GUID	ID do Usuário ou do Grupo
signatories[].signatoryType	Número inteiro	0 = Usuário, 1 = Grupo de Usuários
signatories[].signatoryLastKnownDetails	String	Nome ou email de exibição no momento da exportação

Observação:

(o carimbo de data/hora de desabilitação da governança) é excluído lastDisabledAt da exportação — é um carimbo de data/hora interno que não é significativo para um projeto reimportado.

Regras e restrições

1. Todos os IDs devem ser GUIDs exclusivos e válidos. Não reutilize IDs em objetos do mesmo tipo ou de diferentes tipos.

2. As referências cruzadas devem ser resolvidas. Um testCaseId em uma etapa de teste ou atribuição deve se referir a um caso de teste id presente no mesmo pacote.

3. Os objetos do wrapper são obrigatórios. Mesmo quando a coleção tem um item, ele ainda deve ser envolvido: { "testCases": [ {...} ] }, nunca um array ou objeto vazio.

4. Convençõesnull vs. "" : use null para campos opcionais que estão instantaneamente ausentes (por exemplo automationId, inputParams, preCondition, connectorTestCaseId, todos os campos package* em casos de teste manuais). Use "" apenas para campos que estão sempre presentes como strings, mas estão vazios (por exemplo foreignRef, description, clipboardData). Combinar esses dados — particularmente usando "" onde null é esperado — pode causar falhas de importação silenciosas.

5. noobjectCountDetails deve corresponder às contagens reais de objetos presentes, mas o importador não valida estritamente as contagens — as incompatibilidades afetam apenas a exibição do resumo pré-importação.

6. O UTF-8 sem BOM é obrigatório para todos os arquivos.

Arquivo TMH mínimo válido (fabricado manualmente)

O menor arquivo .tmh válido que o Test Manager aceitará contém apenas um manifest.json:

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

Todos os subdiretórios objects/ são opcionais. O importador ignora silenciosamente qualquer tipo de objeto não presente no arquivo.