Pular para conteúdo

REST API

A nova API HTTP/JSON expõe as operações de negócios do catálogo MCP sem um envelope JSON-RPC. As operações disponíveis dependem da versão instalada do servidor. É uma API orientada para a operação, não uma interface CRUD separada para cada tabela de banco de dados.

Acesso e permissões

Enviar uma chave de API MCP existente como Authorization: Bearer <key>. MCP deve ser ativado globalmente e para o projeto. Chaves de projeto também requerem X-ZTM-Project-UniqueId. Chaves globais precisam de acesso explícito ao projeto para as operações do projeto. O navegador e o Windows não substituem uma chave API.

As permissões do usuário, as portas de escrita, os recursos permitidos e as restrições de demonstração aplicam-se exatamente como eles fazem para MCP. Usar HTTPS fora dos testes locais. Nunca coloque chaves em URLs, código fonte ou logs. Ver Ações de segurança e MCP.

Descubra as operações

Pedido Resultado
GET /api/v1/operations Operações e contratos de introdução à disposição da chave e do projecto actuais
GET /api/v1/operations/{operationId} Um contrato de operação
GET /api/v1/openapi.json OpenAPI 3.1 para o mesmo contexto de autorização
POST /api/v1/operations/{operationId} Executar com o objeto argumento como o corpo de solicitação
POST /api/v1/resources/read Leia um recurso de exportação com chave

O OpenAPI contém um caminho POST concreto para cada operação disponível. Entradas usam os mesmos esquemas que MCP. Saúde da biblioteca, estabilidade dos resultados, anexos do projeto e comparações de lançamento/snapshots têm esquemas de saída digitados. Outros resultados dinâmicos de consulta/ação mantêm contratos extensíveis da JSON. O catálogo inclui ferramentas de pesquisa e ação compartilhadas; nem todos os itens do menu Web têm um endpoint dedicado.

$headers = @{
    Authorization = "Bearer $env:ZTM_API_KEY"
    'X-ZTM-Project-UniqueId' = $env:ZTM_PROJECT_UNIQUE_ID
}
$baseUrl = 'https://your-server.example'
Invoke-RestMethod "$baseUrl/api/v1/operations" -Headers $headers
Invoke-RestMethod "$baseUrl/api/v1/operations/ztm_usage_guide" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body '{}'

Essas variáveis de ambiente são lidas pelo script chamado PowerShell; elas não configuram automaticamente o servidor. Roteia projetos usando cabeçalhos, não argumentos de operação. Os corpos JSON são limitados a 1 MiB e 32 níveis de nidificação. Duplicar nomes de propriedades são rejeitados.

Ler a configuração de antevisão do Office

Uma chave global de API MCP pode ler o modo XLSX eficaz da instalação com POST /api/v1/operations/ztm_admin_office_preview_settings_get e o corpo {}. Uma resposta de exemplo é {"xlsxPreviewMode":"HtmlTable"}; o outro valor possível é DevExpressPdf. Uma chave de projecto é insuficiente. Esta operação é apenas para leitura. Use o administração do servidor para alterar a configuração.

Gravações e exportações

Siga o contrato de pré-visualização e commit explícito de cada operação, por exemplo ztm_project_action_prepare e ztm_project_action_commit. O acesso à API não substitui a aprovação de negócios. Mantenha pré-visualizações, chaves de idempotência e commits ligados ao mesmo contexto de usuário e projeto. Após um tempo livre, verifique o status da ação em vez de repetir cegamente uma escrita.

Exportações podem retornar um resourceUri. Leia-o através do POST /api/v1/resources/read com {"uri":"<resourceUri>"} usando a mesma chave e projeto. A resposta contém contents com texto ou dados Base64 e um tipo MIME. Os tickets podem expirar ou permitir uma única leitura; tratar URIs de recursos como confidenciais.

Erros

Os erros retornam o status HTTP e application/problem+json contendo code e traceId: 400 entradas inválidas, 401 autenticação ausente/rejeitada, 403 permissões insuficientes, 404 objeto ou operação indisponível, 409 conflito de ação, 413 corpo superdimensionado, 415 tipo de conteúdo não suportado, 500 falha interna. Conflitos requerem revisão, não tentativas automáticas. Dê suporte ao traceId, nunca chaves ou cargas confidenciais.

Regras pré-requisitas e testes bloqueados

ztm_project_query inclui rule para biblioteca e dependências planejadas: 0 = Dica apenas, 1 = Deve ter sucesso, 2 = Não deve ter falhado.

Para alterar uma dependência de biblioteca existente, use ztm_project_action_context, em seguida, ztm_project_action_prepare com capabilityId: project.test-case.dependency.set-rule e argumentos testCaseId, dependencyId, rule. Reveja a pré-visualização e confirme-a com ztm_project_action_commit. A chave requer essa capacidade de escrita explícita. Criação permanece compatível: um novo relacionamento começa como uma dica; sua regra pode ser alterada. Os planos e as execuções existentes não são sincronizados automaticamente.

POST /api/v1/operations/ztm_test_prerequisites_read com {"plannedVariantId":123} avalia um teste visível planejado. A resposta inclui isBlocked, needsRecheck e blockers. Predecessores invisíveis ou ausentes não são divulgados pelo nome; hasHiddenPrerequisites indica-os. Esta avaliação ponto-em-tempo não concede direitos de execução nem substitui confirmação pessoal de reteste. A mesma operação está disponível através do MCP.

Anexos do projeto

ztm_project_attachments_read lista anexos de projeto e seus ownerId, com offset e limit (máximo 100). Forneça attachmentId para baixar contentBase64 (máximo 32 MiB). É necessário um administrador de projetos ativo ou um gestor de projetos. Os arquivos ligados dinamicamente estão listados, mas não podem ser descarregados através desta operação.

As gravações exigem a capacidade separada project.attachment.upload, project.attachment.update ou project.attachment.delete. As subvenções existentes para o planeamento e a instalação não concedem acesso ao arquivo do projecto. Use o ownerId retornado, que pode ser 0 para um projeto.

  1. Envio: chamada ztm_project_attachment_stage com targetKind: "project", targetId: <ownerId>, fileName, mimeType e contentBase64. O limite de estadiamento existente é de 512 KiB por arquivo.
  2. Chame ztm_project_action_prepare com a capacidade, um novo idempotencyKey e arguments. Argumentos de envio: ownerKind: "project", ownerId, attachmentReferenceId do ticket, opcional displayName e remarks. Atualização de metadados: ownerKind, ownerId, attachmentId, displayName, remarks. Excluir: ownerKind, ownerId, attachmentId.
  3. Reveja a pré-visualização e confirme através do ztm_project_action_commit com a mesma chave. Edições simultâneas causam um conflito; a repetição de um commit bem sucedido não cria outro anexo.

Apresentar comparações e decisões

ztm_release_snapshots_list lista comparações legíveis salvas com um filtro opcional targetId. Passe o NextCursor retornado como cursor para ler a página seguinte.

ztm_release_compare aceita baseId, targetId, baseRunIds/targetRunIds explícito e opcionais baseScopeRunIds/targetScopeRunIds arrays de { "runId": 123, "scopeRunId": 123 }. Opcional baseSnapshotId/targetSnapshotId selecione evidência salva. Ele retorna a comparação Web, incluindo Fingerprint, aplicando as mesmas regras de seleção e permissão de objetos.

Para salvar a evidência, conceda explicitamente project.release-review.snapshot-create e prepare/compromete argumentos query (o objeto do argumento de comparação), name e fingerprint. As alterações de provas são rejeitadas. Leia a comparação salva, decisionRevision e histórico de decisão com ztm_release_snapshot_read e snapshotId; historyBeforeRevision páginas decisões mais antigas.

Uma decisão também requer project.release-review.decision-record, autorização de gerenciamento de projetos e autorização humana explícita. Preparar aceita snapshotId, targetId, revision, outcome (1 aceito, 2 aceito com condições, 3 rejeitado, 4 revogado), responsibleUserId, comment, openPoints (um por linha) e humanConfirmed: true. O servidor grava o ator autenticado; a bandeira não substitui a aprovação humana real. Reveja a pré-visualização e, em seguida, commit. Regras Web ainda se aplicam: revisão atual, usuário responsável elegível, explicação, escopo completo e evidência inalterada. As cópias históricas do projecto não podem receber uma nova decisão.

Cobertura e limites

REST e MCP compartilham seu catálogo de operação. Isto não implica a cobertura completa de cada recurso Web. Os anexos do projeto agora têm um contrato de escrita separado; os contratos de upload existentes em caso de teste, exigência e planejamento permanecem separados. Operações diferidas permanecem visíveis no catálogo de capacidade.

A apresentação do navegador, as janelas de seleção de arquivos e o login interativo não precisam de terminais de domínio separados. A confirmação pessoal de um reteste manual real não é gerada automaticamente em nome de um testador. Visão geral de lançamento/PDF e importação de automação usam suas operações existentes; o transporte REST não expande sua cobertura de domínio. O anexo do projeto escreve e as operações de comparação/decisão de lançamento estão agora disponíveis como descrito acima. Caminhos do servidor arbitrário e links de arquivos Local Bridge permanecem fora dessas operações API. A copying e as importações de arquivos manifestos independentes não são ações separadas na implementação da Web revisada. Saídas digitadas cobrem anexos de projeto e comparações de versões/snapshots; saídas dinâmicas existentes de consulta/ação permanecem extensíveis JSON, modelos SDK não totalmente digitados.

Versões do caso de teste

O Versão do caso de teste está disponível através do POST /api/v1/operations/ztm_project_test_case_versions. Use operation: "list", testCaseID e opcional skip e take para uma lista limitada com a cabeça atual. read também requer revisionID, enquanto compare adiciona otherRevisionID; asset usa revisionID e assetID e retorna bytes codificados com base64. restore-preview verifica revisionID contra expectedHead.

Prepare a restauração através de ztm_project_action_prepare, capacidade project.test-case-version.restore e argumentos testCaseID, revisionID, expectedHead, opcional note e options. Confirme o token retornado através do ztm_project_action_commit. options pode conter explicitamente excluídos excludedAttributeIDs e flattenUnavailableReusableSteps. A vinculação do projeto, identidade ativa do usuário, permissões de objeto, escopos de escrita e proteção demo ainda se aplicam. Nunca coloque chaves API em exemplos, logs ou histórico de shell.

Saúde da biblioteca e estabilidade dos resultados

Essas operações de leitura usam os mesmos serviços e permissões de objeto que os relatórios da Web. Não é necessária nenhuma bolsa de escrita. Eles não modificam, apagam ou executam testes.

Operação Filtros opcionais
ztm_library_health_read unitId incluindo descendentes ou caseId; ageDays 1–36500 (padrão 180); reason; page de 1; pageSize 1–100 (padrão 50)
ztm_test_stability_read testPlanId; testEnvironmentId (0 para nenhum ambiente); fromUtc, toUtc como timestamps UTC tais como 2026-11-08T12:00:00Z; lookbackRuns 1–200 (padrão 50)

Exemplo: POST /api/v1/operations/ztm_library_health_read com {"ageDays":180,"reason":"NoVisibleUsage","pageSize":25}. A resposta tipificada inclui Findings, CandidateCount, ScannedCaseCount, IsComplete, Limit, Page e PageSize. As razões são NoVisibleUsage, NeverVisiblyExecuted, LongUnchanged, MissingTitle, MissingSteps, MissingExpectedResults, EmptyQuickContent e NoVariants. As razões podem sobrepor-se. Nenhum uso visível não estabelece que um teste não seja usado em todo o projeto; o conteúdo não alterado não é automaticamente obsoleto. A análise é limitada a 2000 casos visíveis e 20000 usos visíveis. Quando a análise de uso é incompleta, os indicadores de uso negativos são suprimidos.

Exemplo: POST /api/v1/operations/ztm_test_stability_read com {"lookbackRuns":50}. A resposta inclui Series, FailureGroups, Evidence individual e as contagens EligibleRuns, IncludedRuns, EligibleResults, IncludedResults, Truncated e InvalidEvidenceCount. Ele usa o resultado atual por execução/caso/variante em execuções finais visíveis, não o histórico de execução completo. No máximo 20000 observações de resultados são analisadas. Variantes, ambientes e origem são separados; as diferenças de construção permanecem visíveis. ContentDifferences e ContentFingerprint comparar apenas a descrição salva do caso de teste, não a especificação histórica completa. As mudanças de resultados são indicadores, não prova de flacidez. O texto de falha correspondente não prova uma causa partilhada. Origin: 0 = automação atual verificada, 1 = outra origem ou não verificada, 2 = evidência de automação alterada ou inválida.

Use o invólucro de entrada mostrado. Intervalos, datas ou filtros desconhecidos inválidos retornam 400; objetos de biblioteca explícitos ilegíveis retornam 403. As mesmas ferramentas e filtros estão disponíveis através do MCP.

Bases de referência

O Bases de referência fornece operações digitadas para opções de escopo, listagem, conteúdo histórico, comparação atual e arquivos salvos. A criação usa preparar/comprometer com a capacidade project.library-baseline.create explicitamente concedida; não há nenhuma operação de edição, restauração ou exclusão. Veja o capítulo vinculado para nomes de ferramentas, argumentos de escopo, regras de repetição e o limite de 512 KiB para respostas de arquivos API.

Planejando status de árvore e resultados personalizados

ztm_project_planning_tree_read retorna a árvore de planejamento permitida junto com definições de resultados disponíveis e filtros de execução. Pedido de exemplo:

{"resultDefinitionIds": [12, 15], "includeNoResult": true}

Use IDs reais do resultDefinitions; os IDs de exemplo são placeholders. IDs de estado usam OR; o treeFilterObjectId opcional restringe ainda mais as execuções. Seleções omissas não significam filtro para essa solicitação, independentemente das preferências de UI salvas. O resultado segue as configurações de visibilidade da árvore do usuário e retorna apenas nós permitidos. IDs explícitos desconhecidos são rejeitados. A operação de leitura não altera as preferências pessoais ou os resultados dos testes. O mesmo contrato está disponível através do MCP.

Origem do valor do atributo

Para ações de atributos existentes, ztm_project_action_context adiciona Metadata ao PromotedFields e ObjectAttributes. Ele inclui AttributeId, AttributeStyleFieldId, nome do campo, ID de estilo e nome, tipo de campo, tipo de proprietário e ID, Entail, e SourceKind (direct, inherited, default). Um padrão não salvo não tem ID de proprietário. As definições de campo em falta mantêm o ID original enquanto os detalhes de definição são nulos.

A mesma informação está disponível através de MCP e POST /api/v1/operations/ztm_project_action_context. As permissões e capacidades da ação de atributos existentes ainda se aplicam; o acesso ao contexto não concede permissão de leitura adicional. Os campos de senha estão excluídos. O contexto de leitura não persiste por omissão. Atributos explica a diferença entre herança por nome e campos promovidos.

Feedback de resultado alvo

Ferramentas somente leitura ztm_result_feedback_read, ztm_result_feedback_preview e ztm_result_feedback_export também estão disponíveis como operações POST abaixo /api/v1/operations/. Cada um requer sua capacidade de leitura project.result-feedback.read, .preview ou .export, além de acesso de leitura aos objetos selecionados.

read aceita testRunId. preview adiciona resultItemIds (1 a 100 IDs únicos), opcionalmente recipient, subject, message, externalReference e includeResultText (padrão false). Sua resposta inclui o Fingerprint do conteúdo revisado. export usa a mesma entrada mais expectedFingerprint, format (html ou xlsx) e opcionalmente language (de ou en). A resposta contém FileName, ContentType e ContentBase64.

O conteúdo alterado requer outra antevisão. Os resultados selecionados inacessíveis rejeitam todo o resultado; não há exportação parcial silenciosa. Nenhuma operação envia mensagens ou armazena destinatários no projeto. Veja Partilhar os resultados dos testes para o fluxo de usuário e limites de conteúdo.

Regras de funções AD

ztm_ldap_role_rules_get lê as regras de uma configuração de importação; ztm_ldap_role_rules_save salva-as com uma revisão esperada; ztm_ldap_role_rules_preview pré-visualiza as alterações de adesão. ztm_ldap_import_run executa a importação de AD existente, incluindo as regras salvas. As mesmas operações estão disponíveis como ferramentas MCP.

Todas as chamadas requerem configurationId. Salvar, pré-visualizar e importar também requerem expectedRevision da última resposta lida. O Save aceita rules contendo IDs de regras estáveis, estado habilitado, nome do atributo, valor exato, função e um nome de grupo dedicado. As chamadas não escolhem IDs de grupo. Contratos OpenAPI gerados descrevem os campos completos.

Salvar e importar são escritos administrativos que exigem uma chave administrativa habilitada com acesso ao projeto e o escopo correspondente. As permissões de administração do projeto também são verificadas. A antevisão não altera nenhuma associação, mas necessita de acesso ao directório configurado. A demonstração pública bloqueia estas chamadas administrativas. No conflito de revisão, leia e reveja a configuração novamente em vez de tentar cegamente uma importação com configurações desatualizadas.

Avaliação dos defeitos de frescura e de libertação manual

ztm_release_evidence_read, ztm_release_evidence_configure e ztm_release_evidence_observe ler limites de idade ou armazenar limites e explicitamente manual avaliações de defeitos. Eles usam os contratos MCP correspondentes e expectedRevision atual. Reler após o conflito (409); não repetir cegamente. observe requer o referenceId e sourceFingerprint real do report.EvidenceAssessment.Defects da visão geral, mais state, criticality, observedUtc com um fuso horário explícito, e comment.

Os escopos de escrita dedicados são project.release-evidence.configure e project.release-evidence.observe. O projeto habilitado escreve e as mesmas permissões de gerenciamento de lançamento que a Web também se aplicam. As declarações incluem o usuário de gravação e o tempo; não são automaticamente verificados dados do rastreador e não devem ser inventadas sem instrução humana explícita. ztm_release_overview_read adiciona EvidenceAssessment para novas capturas ao vivo; o nível assessment existente e razões incorporá-lo. As capturas históricas permanecem inalteradas. Ver Comparação e aceitação da versão.

Conjuntos de dados de ensaio estruturados

Estas ferramentas MCP também estão disponíveis como POST /api/v1/operations/<tool-name> com os mesmos contratos. Veja Matriz de dados de ensaio para regras funcionais.

Ferramenta (prefixo ztm_test_data_set_) Argumentos Resultado
list nenhum conjuntos de dados permitidos no items
read dataSetId conjunto de dados com revisão e IDs de linha estáveis
save data, expectedRevision, confirmed:true conjunto de dados persistentes com uma nova revisão
delete dataSetId, expectedRevision, confirmed:true deleted:true; os dados referenciados permanecem protegidos
binding variantId binding ou null
preview variantId, dataSetId, rowId textos, diagnósticos e impressões digitais sem alterações
apply argumentos de antevisão, expectedFingerprint, confirmed:true textos vinculativos e resolvidos persistentes
unbind variantId, expectedFingerprint, confirmed:true Textos resolvidos do unbound:true estão preservados
export dataSetId XLSX fileName, mimeType, contentBase64
import_preview dataSetId, expectedRevision, contentBase64 proposta não salva; explicitamente chamar save depois

Os campos de conjuntos de dados são Id, TestUnitId, Name, Revision, Columns e Rows; as linhas contêm Id e Values. A criação usa o GUID zero para Id e um expectedRevision vazio. As linhas requerem GUIDs exclusivos não nulos. As atualizações requerem a revisão lida anteriormente. Após conflitos, leia novamente e reveja as mudanças.

As quatro escrita requerem escopos individuais project.test-data-set.save, .delete, .apply ou .unbind, projetos habilitados escrevem e as permissões de objeto relevantes. A pré-visualização da importação nunca persiste, mas requer permissão de edição do proprietário, assim como a Web. As restrições de demonstração também se aplicam através de APIs. O REST usa chaves ao portador em vez de cookies de navegador e não necessita de um token CSRF; os formulários Web ainda requerem tokens antiforja.

XLSX usa uma planilha com _RowId como a primeira coluna. Fórmulas, macros e referências externas são rejeitadas. Limites: 4 MiB XLSX, 16 MiB conteúdo expandido, 30 colunas de dados, 1.000 linhas, 32.767 caracteres por célula e 2 MiB por conjunto de dados. Apenas salvar e importar visualização aceitar até 6 MiB transporte JSON, incluindo Base64; outras operações manter o limite existente 1-MiB.

binding também retorna ligações congeladas cuja fonte não está disponível: SourceAvailable:false e SourceUnavailable diagnóstico. O texto salvo permanece legível quando a variante é legível. Atualizar requer acesso à fonte; a desbinding usa a impressão digital de ligação atual.

Importar de outra ferramenta de teste

A compilação de desenvolvimento atual fornece POST /api/v1/operations/ztm_vendor_migration_preview e POST /api/v1/operations/ztm_vendor_migration_apply para migração de outra ferramenta. As ferramentas MCP equivalentes partilham este contrato.

Forneça targetUnitId, sourceKey, workbookBase64 e opcionalmente attachmentsZipBase64.

Para uma tabela de fornecedores, adicione provider (testrail, xray, zephyr, qase ou neutro) e fileName terminando em .xlsx ou .csv. Continue enviando os bytes no workbookBase64. Colunas detectadas são usadas por padrão. Use mapping para atribuir ExternalId, Nome, PastaPath, Descrição, Pré-requisitos, Passos, Resultado esperado e AnexoPath aos títulos existentes. Use a mesma fonte, arquivo e mapeamento ao aplicar a visualização. Pedidos XLSX neutros sem esses campos mantêm seu comportamento existente.

Visualização usa a capacidade de leitura project.vendor-migration.preview. Uma chave de leitura do projeto é suficiente; seu usuário também precisa de permissão para criar casos no alvo. Nenhum escopo de escrita é necessário para visualização. Ele retorna Fingerprint, Items, Diagnostics e CanApply sem salvar. Aplicar apenas quando o CanApply for verdadeiro; reveja uma nova visualização após alterações.

Para aplicar, envie os mesmos arquivos, a impressão digital de visualização como expectedFingerprint, um UUID fresco como operationId e confirmed: true. Tente novamente a mesma operação com o mesmo UUID após uma interrupção de rede.

A aplicação requer ações de gravação habilitadas e o escopo project.vendor-migration.apply. As permissões de objetos e restrições de demonstração correspondem ao fluxo de trabalho da Web. O pedido JSON, incluindo dados Base64, está limitado a 6 MiB.

Quando o banco de dados do projeto está ocupado, REST retorna HTTP 503 com DatabaseBusy e Retry-After: 2. MCP retorna actionErrorCode: "DatabaseBusy" e retryAfterSeconds: 2 nos dados de erro. Após o acesso ser liberado, tente novamente o mesmo pedido com o mesmo operationId; os recibos salvos são devolvidos após verificar as permissões e conteúdo atual novamente, sem criar mais cópias.

Entregar um ensaio

Use uma chave de projeto pessoal com o escopo de escrita project.test-run.handover para ler os destinatários elegíveis e a revisão atual. MCP e REST usam os mesmos argumentos.

  1. Chama o ztm_project_action_context com o {"capabilityId":"project.test-run.handover","itemKind":"test-run","itemId":23}.
  2. Escolha um ID de Recipients e use Revision como expectedRevision. Por exemplo, chame ztm_run_handover ou POST /api/v1/operations/ztm_run_handover com {"runId":23,"recipientUserId":7,"expectedRevision":0}.

O Applied confirma que a transferência foi salva. mailStatus relata o estado de entrega (Sent, NotConfigured, MissingAddress, MissingLink ou Failed). Repetindo o pedido para o destinatário atual retorna AlreadyApplied com mailStatus: null. Leia o contexto novamente após um conflito (HTTP 409). O proprietário da chave precisa de permissão para editar a execução. Chaves globais e instâncias de demonstração não podem realizar a entrega.

Atribuir casos de ensaio planeados

  1. Use o ztm_project_action_context para ler o estado atual de cada execução. Envia o {"capabilityId":"project.test-run.assign","itemKind":"test-run","itemId":23}. Escolha casos do Cases e um destinatário do Recipients.
  2. Chamar ztm_run_assign em MCP ou enviar POST /api/v1/operations/ztm_run_assign. Para um caso não atribuído, envie por exemplo {"recipientUserId":7,"selection":[{"caseId":42,"runId":23,"expected":null}]}. Se o caso já estiver atribuído, passe seu userId, assignedUtc e assignedByUserId sob expected. Passe o recipientUserId: null para limpar a missão.
  3. Leia a carga de trabalho através de ztm_run_workload_read ou POST /api/v1/operations/ztm_run_workload_read com {"planId":9}.

A escrita requer uma chave pessoal com o escopo project.test-run.assign, executar permissão de edição e acesso aos casos selecionados. Não está disponível na demonstração pública. No conflito, leia novamente o estado atual. Cada requisição salva sua seleção em uma única operação. A carga de trabalho inclui apenas operações abertas visíveis.

Cobertura de versão de leitura

  1. Chamar ztm_coverage_matrix_read em MCP ou enviar POST /api/v1/operations/ztm_coverage_matrix_read com {}. Releases contém os IDs e nomes de lançamento visíveis.
  2. Envie o releaseId selecionado e opcionalmente filter. Por exemplo, {"releaseId":"6bebaee0-20b9-4ff8-b4d1-abdd5d37833c","filter":"without-result"}. Os filtros all, without-test, without-result e failed correspondem à vista do navegador.
  3. Leia Rows por exigência, caso de teste e ambiente. Status é 0 para nenhum resultado, 1 para não avaliável, 2 para passado, 3 para falhou e 4 para parcialmente passado. Onde a evidência salva é visível, as células incluem ResultItemId, RunTitle, RecordedUtc e Tester. Totals conta os requisitos filtrados. Um requisito pode contribuir para várias categorias.

Você precisa de uma chave de projeto pessoal e leia o acesso aos dados solicitados. O recurso Requisitos deve ser ativado para o projeto. Esta operação lê a matriz.

Chamada ztm_share_link_create em MCP ou POST /api/v1/operations/ztm_share_link_create em REST. Ambos aceitam o mesmo corpo da JSON.

{"targetKind":"run","targetId":"23","validityDays":7,"requestId":"869744c5-8cdb-45e1-a300-918d308345f1","includeErrors":false,"includeFindings":false}

Definir targetKind para run, plan ou release. Forneça o ID alvo como uma string, usando seu UUID para uma versão. Escolha 7 ou 30 dias. Os problemas e as descobertas estão ocultos por padrão. Adicione recipientEmail para enviar o link por e-mail do projeto.

Manter o shareId para revogação. A resposta retorna o endereço de convidado no url uma vez, juntamente com expiresUtc e mailStatus (NotRequested, Sent ou Failed). Resolver um endereço de convidado relativo contra a origem do endpoint da API. Tratar o endereço, incluindo o seu fragmento, como uma senha. Se a entrega falhar, o link já foi criado. Tentar novamente com o mesmo requestId não pode criar outro link ou enviar outro e-mail. Se a resposta foi perdida, revogue a entrada original no Ligações partilhadas antes de criar uma substituição.

Revogar com ztm_share_link_revoke ou POST /api/v1/operations/ztm_share_link_revoke e {"shareId":"<share UUID>"}. A resposta contém shareId e revokedUtc. A revogação repetida devolve o calendário original.

Ambas as ações requerem HTTPS (loopback é permitido localmente), escrita de projeto habilitado e uma chave de projeto pessoal com o escopo relevante project.share-link.create ou project.share-link.revoke. As permissões de destino e restrições de demonstração aplicam-se como no cliente web. Ver acesso de hóspedes.

Editar vários casos de teste

Chamar ztm_library_bulk_update em MCP ou POST /api/v1/operations/ztm_library_bulk_update. Por exemplo, preview configurando um atributo de módulo:

{"operation":"preview","action":"attribute","caseIds":[12,31],"attributeName":"Modul","attributeValue":"Checkout"}

Verifica o Rows. Em seguida, definir operation para apply e enviar os mesmos parâmetros com o Fingerprint retornado em fingerprint. Adicionar um UUID no requestId para tentativas. Repetindo o mesmo pedido com esse ID retorna seu recibo enquanto o servidor mantém o trabalho. HTTP 409 requer uma nova visualização.

Use targetUnitId com move ou archive, reviewGroupId com review e variantValueIds com variant. Um destino de arquivo deve ser marcado como uma unidade de arquivo. Cada pedido aceita até 200 casos de teste. Use uma chave de projeto pessoal com o escopo project.test-library.bulk-update. O servidor verifica os direitos atuais para cada caso. Chaves globais e acesso demo estão bloqueados.

Use o {"operation":"undo","requestId":"<RequestId from receipt>"} com a mesma chave do projeto para desfazer movimentos ou alterações de atributos enquanto o trabalho permanece na memória do servidor. As permissões e as mudanças intervenientes são verificadas novamente.

O opcional booleano isArchive em argumentos project.test-unit.update marca uma unidade como um arquivo. Use o fluxo de visualização/compromisso existente com itemId e title. A omissão do isArchive preserva o seu valor. A unidade Project Knowledge lê também expõe isArchive.

Reteste os resultados selecionados

ztm_library_retest ou POST /api/v1/operations/ztm_library_retest usa o mesmo fluxo de trabalho que Manter a biblioteca de testes:

  1. Envie operation: "options" e findings para ler as execuções de código-fonte permitidas, ambientes e testadores. Cada achado contém caseId, plannedCaseId ou resultId; incluem variantId conhecidos, planId e runId. Escolha explicitamente um contexto quando vários estiverem disponíveis.
  2. Envie operation: "preview", a mesma seleção, e planId, runId, environment e testerId. Items lista as variantes eficazes, incluindo pré-requisitos obrigatórios. O Skipped identifica achados excluídos pelo índice de seleção baseado em zero. Defina acceptOldTemplate: true apenas após decidir explicitamente usar modelos desatualizados.
  3. Envie operation: "create" com entradas idênticas, o Fingerprint retornado como fingerprint, e RequestId como requestId. O recibo inclui RunId, Url e achados ignorados. Após uma falha de conexão, tente novamente o mesmo ID de solicitação para evitar criar uma segunda execução.

As visualizações expiram após 30 minutos e pertencem ao projeto e usuário. Alterações na seleção, permissões ou conteúdo requerem uma nova visualização. Cada solicitação aceita no máximo 200 descobertas; é necessária uma execução de fonte existente. O parâmetro opcional tab (health, impact, results) também verifica se a respectiva aba está disponível.

Use uma chave de projeto pessoal com o escopo de escrita project.test-library.retest e permissão para criar execuções no plano selecionado. As chaves de administrador globais e o modo de demonstração público estão excluídos. As ferramentas existentes e a sincronização através do project.planned-test-case.synchronize-from-library permanecem inalteradas.

Comentários do objeto

Use o ztm_comment_read para ler comentários e atividades para um objeto. Fonte kind (test-case, requirement, run, result) e id. Página offset e activityOffset independentemente. Use o commentId para localizar a página contendo um comentário. Tratar o Markdown retornado como conteúdo do usuário.

ztm_comment_add salva markdown com um UUID gerado pelo cliente como commentId. Forneça parentId para responder. Você pode usar o mentionUserIds para notificar usuários explicitamente selecionados com acesso de leitura. O texto deve incluir a sua menção. Tente novamente com o mesmo UUID e conteúdo. Created distingue um novo comentário de uma repetição. MailFailed relata um problema de entrega enquanto o comentário permanece salvo.

Ambas as ferramentas requerem que os comentários sejam habilitados para o projeto. Eles usam o proprietário ativo de uma chave de projeto pessoal e verificam as permissões atuais do objeto. A publicação requer a escrita do projeto e o escopo project.comments.add. REST usa POST /api/v1/operations/ztm_comment_read e POST /api/v1/operations/ztm_comment_add. Fluxo de trabalho Web

Criar um reteste a partir de uma execução

A ferramenta MCP ztm_retest_create e a rota REST POST /api/v1/operations/ztm_retest_create aceitam os mesmos argumentos. Visualize a seleção primeiro. Este exemplo inclui variantes não testadas, além das que falharam e bloquearam.

{"mode":"preview","sourceRunId":36,"includeUntested":true}

Revisão RequestedCount, pré-requisitos adicionais (RequiredCount) e Errors. Use o ambiente (Environment), um ID do testador de Testers e o ComparisonToken desta antevisão. Substitua os valores de exemplo e gere um UUID fresco para cada nova solicitação. Se RequiresOldTemplate for verdadeiro, a criação requer aprovação explícita com acceptOldTemplate: true.

{
  "mode": "create",
  "sourceRunId": 36,
  "includeUntested": true,
  "environment": "Staging",
  "testerId": 7,
  "comparisonToken": "<ComparisonToken>",
  "creationId": "179e6928-a673-4dac-acae-b913914a13df"
}

A resposta contém o novo testRunId da execução não iniciada. Se a conexão falhar, tente novamente o pedido idêntico, incluindo seu creationId. Ambos os modos exigem que as gravações sejam habilitadas, o escopo project.retest.create e permissões de projeto e objeto para visualizar a fonte e criar a execução. As restrições de demonstração também se aplicam. Usando o painel web.

Criar um problema a partir de um resultado de teste

ztm_issue_create_from_result · POST /api/v1/operations/ztm_issue_create_from_result

Use a ferramenta MCP ou sua operação REST correspondente com o escopo de gravação pessoal project.defect.create. O testCaseId é o ID da variante planejada. Para etapas estruturadas, linhas rápidas e itens de lista, stepIndex começa em zero. Omite-o para resultados globais e texto não estruturado.

{"mode":"prepare","testRunId":40,"testCaseId":371,"stepKind":"structured","stepIndex":3}

Reveja os campos devolvidos e as opções de anexos. Após a confirmação, use o RequestId retornado como requestId e envie os valores escolhidos e os IDs de anexo de resultados acessíveis.

{"mode":"create","testRunId":40,"testCaseId":371,"requestId":"4c2ef7c8-b3a2-43e4-a721-6f04bb164b42","attachmentIds":[38]}

Após Retryable, tente novamente com o mesmo ID uma vez que o rastreador está disponível. Após Unknown, verifique o rastreador e envie o número existente como existingIssueReference. Após LinkPending, repita o pedido para ligar o problema conhecido. Para colar uma imagem diretamente, use a janela Web.