No artigo anterior , apresentei a decisão de separar descoberta, modelo e serialização no Protheus OpenAPI. O primeiro experimento foi pequeno: representar manualmente o contrato do Hello World e produzir um documento JSON sem depender de tlpp.doc.generate().

Para implementar esse núcleo, precisei aprender como testar as regras em TL++ dentro do ambiente Protheus. Antes de construir o documento inteiro, havia uma pergunta mais básica: como comprovar que o teste está sendo executado e consegue detectar uma falha?

Neste artigo, mostro o caminho entre essa primeira verificação com PROBAT e os testes de composição do modelo. O recorte é o núcleo mínimo desenvolvido em agosto de 2026, com evidências preservadas no diário técnico do experimento .

Primeiro, testar o próprio caminho de execução

O primeiro passo foi preparar o harness: a estrutura mínima para o PROBAT encontrar e executar os testes. Neste experimento, o fixture é a função OApiTst, que reúne a preparação dos objetos e as asserções sobre seu comportamento. Cada asserção compara um resultado observado com o esperado.

O fixture do núcleo inicial usa os includes de TL++ e PROBAT, declara seu namespace e identifica a função com @TestFixture(). Abaixo está uma redução dessa estrutura para mostrar apenas a verificação inicial; o fixture completo inclui as classes e os demais cenários:

#include "tlpp-core.th"
#include "tlpp-probat.th"
#include "totvs.ch"

namespace custom.openapi.core.test

using namespace tlpp.probat

@TestFixture()
User Function OApiTst() as Logical

    assertEquals(.T., .T., "O harness PROBAT deve aceitar valores iguais.")

Return .T.

Uma asserção que compara dois valores iguais ajuda a verificar o caminho de sucesso. Para conferir a detecção de falhas, o experimento começou com uma comparação deliberadamente incorreta.

Em 24/08, o console registrou ok: 0 e err: 1. Depois da correção, a execução terminou sem erro de assert. Essa sequência ficou associada ao commit f25a72a.

A falha intencional tinha uma finalidade: verificar que o fluxo observava o teste executado. Um resultado sem erros só seria útil depois de demonstrar que esse mesmo caminho também acusava um erro conhecido.

Do RED inicial ao comportamento esperado

TDD é o desenvolvimento guiado por testes: escrever uma expectativa e observar sua falha (RED), implementar o necessário para atendê-la (GREEN) e refatorar mantendo os testes passando. O diário usado neste artigo registra os ciclos RED/GREEN; não detalha uma etapa de refatoração em cada incremento.

Com o harness conferido, a implementação avançou por partes: informações da API, respostas, operações, paths, documento e serializador.

O ciclo começava com uma expectativa expressa no teste. A execução falhava, a implementação era acrescentada e o fixture era executado novamente no RPO. O diário preserva os seguintes marcos:

EtapaEvidência de REDEvidência de GREEN
HarnessFalha deliberada com ok: 0, err: 1Execução sem erro de assert
Informações da APIinvalid class OAPIINFOGetters e validação de informações conferidos
Respostasinvalid class OAPIRESPPreservação dos dados e pendências conferidas
Operações e pathsClasses ainda inexistentesInclusões válidas e rejeição de conflitos conferidas
DocumentoRevisão voltou ao RED com sete assertsDuplicidade, reutilização e validação transitiva conferidas
Serializaçãoinvalid class OAPIJSONEstrutura JSON e cenários com múltiplos elementos conferidos

Um erro como invalid class OAPIINFO demonstra que o teste tentou usar uma classe ainda ausente. Ele confirma o primeiro RED, mas não basta para exercitar uma regra de negócio. Depois que a classe existe, o teste precisa distinguir uma implementação correta de uma que apenas permite instanciar o objeto. Uma execução que falha por configuração ou include ausente também não comprova a regra pretendida: é preciso conferir a causa da falha.

No caso de OApiInfo, por exemplo, o fixture verifica preservação de título, descrição e versão, além das pendências geradas quando título e versão estão vazios. Para operações, acrescenta normalização do verbo e rejeição de respostas duplicadas.

O ciclo RED/GREEN ajudou a construir a API pública em incrementos pequenos. A revisão dos próprios testes foi necessária para tornar essa proteção mais exigente.

Lançar um erro é apenas parte do contrato

Uma regra do núcleo determina que duas respostas com o mesmo código não podem ser registradas na mesma operação. A segunda inclusão precisa falhar sem substituir a primeira.

Seria possível escrever um teste que verificasse somente a ocorrência da exceção. Esse teste deixaria uma pergunta aberta: o objeto continuou correto depois da tentativa?

O fixture verifica o diagnóstico e consulta novamente a coleção. Este é um trecho do teste, executado depois de já existir uma resposta 200 em oOper:

oDupResp := OApiResp():new("200", "Resposta que não deve substituir a original.")

Try
    oOper:addResp(oDupResp)
Catch oError
    lDupErr := .T.
    cDupErr := oError:Description
EndTry

assertEquals(.T., lDupErr, "Resposta duplicada deve falhar imediatamente.")
assertEquals("Resposta duplicada: 200.", cDupErr, "O erro deve diagnosticar o código duplicado.")

aResps := oOper:getResps()
assertEquals(1, Len(aResps), "A falha não deve incluir nem substituir a resposta original.")
If Len(aResps) >= 1
    assertEquals("Resposta retornada com sucesso.", aResps[1]:getDesc(), "A resposta original deve permanecer inalterada.")
EndIf

No fixture completo, as variáveis são declaradas no início da função e lDupErr começa com .F.. O trecho pressupõe que a resposta original foi criada com a descrição Resposta retornada com sucesso.. Conferir apenas o tamanho do array não detectaria uma substituição indevida: ele poderia continuar com um elemento, mas conter a resposta errada.

Depois da rejeição, o teste inclui uma nova resposta válida, com código 201, e confere sua presença. Assim, também verifica se o objeto continua utilizável.

São três comportamentos ligados: recusar a duplicidade, preservar o estado anterior e continuar aceitando inclusões válidas. A mesma preocupação aparece nos testes de operações e paths.

Esse foi um aprendizado importante do experimento: quando uma operação pode falhar durante a composição, o contrato deve dizer o que acontece com o objeto após a falha.

A revisão também pode começar outro RED

Na etapa do documento, a revisão acrescentou sete asserts para verificar duplicidade, reutilização e validação transitiva. O trabalho voltou ao RED e chegou a um novo GREEN em 25/08, registrado no commit afcedd9.

A validação transitiva verifica se uma pendência de um objeto interno chega ao documento com contexto suficiente. Uma operação sem respostas, por exemplo, precisa produzir um diagnóstico que identifique seu path e verbo.

Também foram exercitados múltiplos paths e a ordem determinística das pendências. Isso evita depender apenas do caso mais simples, no qual existe um único objeto em cada nível.

No serializador, a mesma ideia levou a cenários com dois paths, duas operações em um mesmo path e múltiplas respostas. Os testes interpretam o JSON e verificam sua estrutura, sem depender da ordem textual das propriedades.

O objetivo dessas verificações era proteger regras observáveis pelo cliente da biblioteca. A quantidade de asserts, isoladamente, não explica essa proteção.

O que a compilação e o runtime ensinaram sobre TL++

Além das regras do modelo, o desenvolvimento encontrou detalhes que só uma leitura do código não resolveria.

Um nome de atributo pode conflitar com o preprocessador

O identificador interno planejado como cVer conflitou com uma macro existente em sigawin.ch. O campo foi renomeado para cApiVer, preservando o método público getVer().

A ocorrência mostrou por que a compilação no ambiente de destino faz parte da validação. Um nome aparentemente adequado dentro da classe pode ter outro significado depois da expansão dos includes.

A correção ficou no detalhe interno. Para quem usa o objeto, o acesso à versão continuou pelo mesmo método público.

Devolver uma coleção exige definir o alcance da cópia

Os getters de coleções usam AClone() para proteger a composição dos arrays internos. O fixture altera o array devolvido, consulta o getter novamente e verifica que a inclusão externa não alterou a coleção mantida pelo objeto.

Essa proteção tem um limite: os objetos contidos continuam compartilhados. A cópia não transforma toda a árvore em objetos independentes nem torna o modelo imutável.

O teste precisa refletir essa promessa específica. Neste núcleo, a garantia é impedir alterações externas na composição dos arrays retornados.

Encoding também faz parte do contrato dos fontes

Os fontes do experimento usam Windows-1252 sem BOM. O contrato estático verifica essa convenção, junto de includes, namespace e declarações esperadas.

Ao reproduzir o exemplo, é necessário preservar a convenção do projeto nos arquivos TL++. O Markdown deste artigo continua em UTF-8; copiar um trecho para um novo fonte exige atenção à codificação escolhida pelo editor.

Cada verificação responde a uma pergunta

O experimento combinou verificações locais, compilação, PROBAT e chamadas HTTP. Cada uma forneceu um tipo diferente de evidência:

VerificaçãoO que foi conferido no recorte
Contratos estáticosConvenções dos fontes, encoding e dependências proibidas no núcleo
CompilaçãoAceitação dos fontes e includes no ambiente Protheus
PROBAT no RPOComportamento das classes, rejeições e estrutura serializada
HTTPPublicação da demonstração e comportamento de autenticação do AppServer

O ambiente registrado foi Protheus 12.1.2510, AppServer 24.3.1.5 e TLPPCore 01.06.01. O PROBAT foi executado pelo fluxo disponível no TDS/AppServer. Os scripts locais não executam esses testes TL++ no RPO.

Os exemplos mostram o código do fixture, mas pressupõem um ambiente de compilação e execução já configurado. Os resultados relatados são os registros históricos de agosto; esta revisão do artigo não inclui uma nova execução no AppServer.

Para conferir os contratos locais no snapshot de referência, o diário orienta usar os scripts Python que substituíram os antigos arquivos PowerShell:

python tests/openapi-core/validate-sources.py
python scripts/validate-hello-openapi.py --path tests/openapi-core/fixtures/hello-core.json

Esses comandos devem ser executados na raiz do repositório Protheus OpenAPI. Eles não substituem a compilação e a execução do fixture OApiTst no ambiente configurado.

O fixture histórico do núcleo mínimo contém 98 chamadas a assertEquals() no fonte, incluindo chamadas dentro de condicionais e de um laço. Essa contagem estática não corresponde necessariamente à quantidade de asserções executadas. O diário informa que várias execuções não preservaram a contagem final do PROBAT; por isso, esse número não deve ser apresentado como um relatório de 98 testes aprovados.

As evidências HTTP registram 401 sem autenticação e 200 com application/json na chamada autenticada. Elas complementam a validação do núcleo, mas não demonstram conformidade de qualquer documento com toda a especificação OpenAPI.

O aprendizado que fica para o próximo incremento

O núcleo mínimo ofereceu um exercício concreto de TL++: representar objetos, definir regras de composição, testar falhas e produzir uma saída verificável. O PROBAT permitiu executar essas expectativas no ambiente em que as classes seriam usadas.

O processo também mostrou onde os testes precisavam melhorar. Depois de uma exceção, foi necessário verificar o estado preservado. Depois do primeiro objeto, foi necessário testar coleções com mais elementos. Depois do código escrito, foi necessário compilar com os includes reais.

Esse recorte ainda era manual: parâmetros, schemas e descoberta automática não faziam parte da primeira entrega. Os incrementos posteriores não mudam o que foi demonstrado nessa etapa.

Na próxima parte da série, vou detalhar a composição entre documento, paths, operações e respostas, incluindo a diferença entre conflitos rejeitados imediatamente e pendências acumuladas por validate().

Referências