Como fazer: executar testes a partir da CLI

Esta página mostra como executar um conjunto de testes UiPath Test Manager a partir da CLI como parte de um pipeline de CI — e, tão importante quanto, como ler o veredicto corretamente. A ferramenta uip tm divide uma execução de teste em três verbos por um motivo; usar apenas um deles pode produzir uma compilação aprovada, mesmo quando os testes falharam.

A regra de Ouro: iniciar → aguardar → verificar

Nenhum verbo uip tm sai diferente de zero porque os testes falharam. Fazer com que um pipeline falhe em uma execução de teste vermelha são necessários três comandos:

1. Iniciar — uip tm testsets run. Enfileira a execução e sai 0 assim que o Orchestrator aceita a solicitação. Status: "Running" na resposta reflete o estado no lançamento, não o resultado final.
2. Bloquear — uip tm wait. Pesquisa até que a execução atinja um estado terminal (Passed, Failed, Cancelled). Sai de 0 quando atinge qualquer estado terminal — porque "concluído" é o sinal de sucesso para wait. Saídas 2 em --timeout (uma reutilização específica do domínio do slot de erro de autenticação, para que os scripts possam ramificar em "demorei muito" sem analisar o texto).
3. Verificar — uip tm report get. Lê Data.Failed (e Passed, Skipped, PassRate). Sai de 0 sempre que busca o resumo com sucesso, independentemente de aprovação/falha — o script é responsável por transformar Data.Failed > 0 em uma saída diferente de zero.

Existem padrões de atalho (uip or jobs start --wait-for-completion, por exemplo, aguarda+verifica em um único trabalho), mas não para conjuntos de testes. Sempre escreva as três etapas.

Fragmento mínimo viável

#!/usr/bin/env bash
set -euo pipefail

# 1. Launch
EXECUTION_ID=$(uip tm testsets run \
  --test-set-key DEMO:10 \
  --output-filter "Data.ExecutionId" \
  --output plain)

# 2. Block (default timeout: 30 min; adjust with --timeout)
if ! uip tm wait \
  --execution-id "$EXECUTION_ID" \
  --project-key DEMO \
  --timeout 1800; then
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "test run did not finish within 30 minutes" >&2
    exit 2
  fi
  echo "wait failed (exit $code)" >&2
  exit "$code"
fi

# 3. Verify
FAILED=$(uip tm report get \
  --execution-id "$EXECUTION_ID" \
  --project-key DEMO \
  --output-filter "Data.Failed" \
  --output plain)

if [ "$FAILED" -gt 0 ]; then
  echo "$FAILED test case(s) failed" >&2
  exit 1
fi

echo "all tests passed"

--output plain o valor bruto para um resultado de filtro escalar; essa é a maneira mais segura de capturar um campo em uma variável de shell sem analisar JSON. Consulte Padrões de script — leitura de valores fora do envelope.

Escolha de entradas para os comandos

uip tm testsets run precisa da chave do conjunto de testes, não de seu UUID. A chave tem a forma <ProjectKey>:<Number> — por exemplo, DEMO:10. Duas maneiras de encontrá-lo:

# From the Test Manager UI — it is the "Key" column in the test set list.

# Or from the CLI:
uip tm testsets list --project-key DEMO --filter smoke \
  --output-filter "Data[*].{key:TestSetKey, name:Name}"

--project-key é obrigatório em list; run deriva o projeto do prefixo da chave do conjunto de testes (DEMO:10 → projeto DEMO).

Se você precisar do UUID numérico para uip tm executions list --test-set-id, esse é o campo Id na mesma saída de lista — não o TestSetKey.

Escolhendo quais casos são executados

uip tm testsets run --execution-type controla quais casos de teste dentro do conjunto são executados:

• automated padrão) — apenas casos de teste automatizados.
• manual apenas casos de teste manuais.
• mixed ambos.
• none sem filtro de tipo.

Para CI, mantenha o padrão (automated) — os casos manuais exigem que um humano marque como aprovado/falha e permanecerá em InProgress até --timeout.

Passando substituições de parâmetros

Se o conjunto de testes expor parâmetros (por exemplo, um URL de destino ou uma ID de conta), substitua-os no lançamento por --input-path:

cat > ./params.json <<'EOF'
[
  {"name": "TargetUrl", "type": "String", "value": "https://staging.example.com"},
  {"name": "AccountId", "type": "String", "value": "acme-staging"}
]
EOF

uip tm testsets run --test-set-key DEMO:10 --input-path ./params.json

As substituições são correspondidas com as definições de parâmetro atuais do conjunto de testes por name (sem diferença entre maiúsculas e minúsculas) e, quando presente, type. Se o servidor não relatar definições de parâmetros, as entradas serão enviadas como estão.

Leitura do veredicto em detalhes

uip tm report get é o leitor de resumo. A saída padrão fornece o cartão de pontuação; passe --query (um filtro no estilo jq) para extrair um subconjunto em uma chamada:

# Pretty scorecard
uip tm report get --execution-id "$EXECUTION_ID" --project-key DEMO

# Script-friendly — JSON with just the counts
uip tm report get --execution-id "$EXECUTION_ID" --project-key DEMO \
  --query '{total: .TotalTests, passed: .Passed, failed: .Failed}'

O envelope Data tem esses campos (esquema completo na referênciareport get ):

• TotalTests, Passed, Failed, Skipped, PassRate ("80%"), Duration (HH:MM:SS).
• FailedTests uma entrada por caso de teste com falha, com TestCaseName e uma string Error (o campo info do log ou uma lista concatenada de mensagens de asserção com falha).

Quando você precisar de um arquivo JUnit-XML que o painel de teste do seu CI possa ingerir, use uip tm result download em vez de (ou ao lado de) report get.

Exibição de casos com falha em logs de CI

Transforme a matriz FailedTests em uma linha legível por humanos por falha antes de sair do pipeline:

if [ "$FAILED" -gt 0 ]; then
  uip tm report get \
    --execution-id "$EXECUTION_ID" \
    --project-key DEMO \
    --output-filter "Data.FailedTests[*].[TestCaseName, Error]" \
    --output plain >&2
  echo "$FAILED test case(s) failed" >&2
  exit 1
fi

Para uma análise de falha mais profunda — detalhe asserção por asserção em um único caso com falha — use uip tm testcaselogs list-assertions nos IDs de log retornados por uip tm executions testcaselogs list --only-failed.

Nova tentativa de casos alterados

Se uma execução tiver falhas que podem ser persistentes (tempo, ambiente), tente novamente apenas os casos com falha :

uip tm executions retry \
  --execution-id "$EXECUTION_ID" \
  --project-key DEMO

uip tm executions retry reutiliza o mesmo ID de execução — nenhum novo é criado. Se não houver falhas para tentar novamente, ele imprimirá uma mensagem informativa e sairá 0 (intencionalmente não um erro).

Após retry, faça o loop de volta com wait + report get no mesmo ID de execução.

armadilhas comuns

• Analisando a saída testsets run para decidir se aprovado/reprovado. O campo Status no lançamento é normalmente Running — isso significa que a execução estava na fila, não que todos os testes foram aprovados. Sempre chame wait e depois report get.
• Esquecendo o --timeout em wait. O padrão é 1800 segundos (30 minutos). Passe 0 para esperar indefinidamente (raramente o que você deseja no CI); passe um número maior para conjuntos longos.
• Tratando a saída 2 de wait como uma falha de autenticação. Em wait especificamente, 2 significa tempo limite, não AuthenticationError — consulte códigos de saídauip tm wait .
• Usando testsets para criar testes. Os casos de teste e seus links para as automações do Orchestrator vêm de uip tm testcases; testsets apenas os agrupa.

Exemplo completo pronto para CI

Um fragmento bash para uma etapa do pipeline — falha na compilação quando qualquer teste falha, atinge o tempo limite ou causa erros:

#!/usr/bin/env bash
set -euo pipefail

TEST_SET_KEY="${TEST_SET_KEY:?TEST_SET_KEY is required}"
PROJECT_KEY="${PROJECT_KEY:?PROJECT_KEY is required}"
TIMEOUT="${TEST_TIMEOUT:-1800}"

EXECUTION_ID=$(uip tm testsets run \
  --test-set-key "$TEST_SET_KEY" \
  --output-filter "Data.ExecutionId" \
  --output plain)

echo "started execution $EXECUTION_ID" >&2

if ! uip tm wait \
  --execution-id "$EXECUTION_ID" \
  --project-key "$PROJECT_KEY" \
  --timeout "$TIMEOUT"; then
  code=$?
  case "$code" in
    2) echo "execution $EXECUTION_ID did not finish within ${TIMEOUT}s" >&2; exit 2 ;;
    *) echo "wait failed with exit $code" >&2; exit "$code" ;;
  esac
fi

# Get the scorecard and the names of any failed cases in one shot
uip tm report get \
  --execution-id "$EXECUTION_ID" \
  --project-key "$PROJECT_KEY"

FAILED=$(uip tm report get \
  --execution-id "$EXECUTION_ID" \
  --project-key "$PROJECT_KEY" \
  --output-filter "Data.Failed" \
  --output plain)

if [ "$FAILED" -gt 0 ]; then
  echo "$FAILED test case(s) failed" >&2
  exit 1
fi

echo "all tests passed"

Execute este script após sua etapa de implantação da Solução em qualquer uma das Receitas de CI. A única configuração específica do env é TEST_SET_KEY / PROJECT_KEY — defina-as por ambiente no pipeline e o mesmo script promoverá de forma limpa entre o dev/stage/prod.

Veja também

• uip tm visão geral — a superfície de comando completa.
• uip tm testsets run, uip tm wait, uip tm report get — os três verbos usados acima.
• uip tm result download — Exportação XML JUnit para painéis de CI.
• Padrões de script — pesquisa, filtragem JSON, pipelines idempotentes.
• Códigos de saída — o contrato compartilhado e o 2 específico do domínio de wait.