Pular para o conteúdo principal

Renderer.render_tests

Página gerada do fonte

Gerada por tools/gerar_documentacao.py. Definição: tools/documentacao/render.py:937.

Gera índice de suítes, casos, harness e modos de integração.

Tipo: função Python · Visibilidade: pública · Arquivo: tools/documentacao/render.py.

Assinatura e expansão​

def render_tests(self) -> None:

Parâmetros formais: self.

Como funciona​

Gera índice de suítes, casos, harness e modos de integração.

Implementação completa · 117 linhas
def render_tests(self) -> None:
"""Gera índice de suítes, casos, harness e modos de integração."""
self.category("testes", "Testes e rastreabilidade", 30)
suites = defaultdict(list)
for case in self.inv.cases:
suites[case["suite"]].append(case)
body = ["# Testes e rastreabilidade\n\n",
f"**{len(self.inv.cases)} casos em disco**, {len(suites)} suítes e {len(self.inv.modes)} modos "
"unitários/integração extraídos do harness. Contagens são estáticas: não são o total impresso por uma execução.\n\n",
"```bash\nmake test\nmake test-biblioteca\nmake test-portabilidade\nmake fuzz\n```\n\n",
"## Caminhos de execução\n\n",
"- **M0:** o compilador C processa diretamente as macros de `basicgol.h`.\n",
"- **M1:** `basicgolc` traduz blocos/açúcar para C; o compilador C ainda verifica tipos e liga a biblioteca.\n",
"- Casos de execução comparam stdout, stderr declarado e status com o resultado dourado principal ou alternativo.\n",
"- Negativos exigem falha e diagnóstico; avisos exigem W-xx sem necessariamente falhar a tradução.\n",
"- CR é normalizado nas comparações para acomodar o modo texto do CRT Windows.\n\n",
"| Suíte | Casos | Caminhos | Registro no runner |\n|---|---:|---|---|\n"]
for suite, cases in sorted(suites.items()):
folder = f"testes/casos/{suite}"
self.category(folder, suite, 10)
paths = sorted({("M0" if c["m0"] else "") + ("+M1" if c["m1"] else "") for c in cases})
registered = "sim" if all(c["runner_registered"] for c in cases) else "revisar"
body.append(f"| [{suite}](/{folder}/) | {len(cases)} | {', '.join(paths)} | {registered} |\n")
rows = [f"# Suíte {suite}\n\n", "| Caso | Tipo | M0 | M1 | Símbolos | Arquivos |\n|---|---|---|---|---:|---:|\n"]
for case in cases:
rows.append(f"| [{case['name']}](/{folder}/{case['name']}) | {case['mode']} | {'sim' if case['m0'] else 'não'} | {'sim' if case['m1'] else 'não'} | {len(case['symbols'])} | {len(case['files'])} |\n")
self.render_case(case)
rows.append(self.suite_faq(suite, cases))
self.page(folder + "/index", suite, "".join(rows), label="Casos", position=0)
body.append("\n:::caution[Descoberta não altera o runner]\nUm diretório novo aparece aqui automaticamente. "
"Para ser executado por `make test`, ele também precisa seguir a seleção de suítes de `tests/run.sh`; "
"a coluna acima mostra se o nome da suíte aparece nesse runner.\n:::\n\n")
body.append("## Harness, runners e modos\n\n- [Testes unitários e integração](/testes/harness)\n"
"- [Modos fatais e de stdin](/testes/modos/)\n- [Funções dos runners](/internos/)\n"
"- [Cobertura versionada](/testes/cobertura-versionada)\n")
body.append(self.faq(
"Perguntas frequentes sobre a suíte de testes, os caminhos M0/M1 e a leitura dos resultados.",
[
{"q": "Quais comandos cobrem a suíte inteira?",
"a": ["Cada alvo do Makefile executa uma camada diferente; `make test` não substitui "
"a suíte da biblioteca nem a matriz de portabilidade."],
"code": "make test\nmake test-biblioteca\nmake test-portabilidade\nmake test-sanitize\nmake fuzz",
"lang": "bash"},
{"q": "O que significa um caso ser M0, M1 ou ambos?",
"a": ["M0 compila o fonte diretamente com as macros de `basicgol.h`. M1 passa antes por "
"`basicgolc`, que traduz blocos e o açúcar `PARA i DE …`. Um caso só em M1 usa "
"sintaxe que o pré-processador não reduz sozinho."]},
{"q": "Como sei o que um caso compara?",
"a": ["Abra a página do caso: ela lista todos os arquivos versionados, inclusive o "
"`esperado`, entradas de stdin e alternativas aceitas, além do tipo "
"(`execução`, `negativo` ou `aviso`)."]},
{"q": "As contagens desta página são o total de verificações?",
"a": [f"Não. Aqui há **{len(self.inv.cases)} casos em disco** e "
f"**{len(self.inv.modes)} modos**. O total impresso por `make test` é dinâmico e "
"inclui verificações repetidas, sanitizers e ferramentas disponíveis."]},
{"q": "Como adicionar um caso novo?",
"a": ["Crie `tests/casos/<suite>/<caso>/` com o programa e os arquivos esperados. O "
"gerador descobre o diretório automaticamente; para ser executado, o nome da "
"suíte também precisa constar em `tests/run.sh`."],
"code": "mkdir -p tests/casos/20_minha_suite/n01_ola\n"
"printf '#include <basicgol.h>\nINICIO\n ESCREVAL(\"ola\");\nFIM\n' > tests/casos/20_minha_suite/n01_ola/programa.c\n"
"printf 'ola\n' > tests/casos/20_minha_suite/n01_ola/esperado.txt",
"lang": "bash"},
]))
self.page("testes/index", "Testes e rastreabilidade", "".join(body), label="Visão geral", position=0)
self.render_harness()
self.category("testes/modos", "Modos de integração", 30)
mode_rows = ["# Modos de integração e falha fatal\n\n",
"Cada modo é uma entrada de linha de comando de `tests/test_biblioteca.c`. "
"O runner verifica o código de saída e o diagnóstico; não basta o processo terminar.\n\n",
"| Modo | Ramo C | Chamadas | Invocação no runner |\n|---|---|---|---|\n"]
for mode in self.inv.modes:
slug = mode["mode"].lstrip("-")
runner = self.runner_mode_lines(mode["mode"])
calls = ", ".join(f"`{c}`" for c in mode["calls"])
mode_rows.append(f"| [`{mode['mode']}`](/testes/modos/{slug}) | {self.gh_link(mode['path'], mode['line'], label='ramo')} | {calls} | {self.gh_link('tests/run_biblioteca.sh', runner[0][0], label='invocação') if runner else 'não localizada'} |\n")
out = [f"# Modo `{mode['mode']}`\n\n", f"Ramo extraído de {self.gh_link(mode['path'], mode['line'])}.\n\n",
"## Código executado\n\n", fence(mode["body"], "c"), "\n"]
if mode["conditions"]:
out.append("## Condições de plataforma\n\n")
for cond in mode["conditions"]:
out.append(f"- `{cond['condition']}`\n")
out.append("\n")
out.append("## Como o runner usa este modo\n\n")
if runner:
for line, text in runner:
out.append(f"- {self.gh_link('tests/run_biblioteca.sh', line, label=f'L{line}')}: `{text.strip()}`\n")
if mode["mode"].startswith("--"):
out.append("\nO modo de stdin espera sucesso e a saída literal conferida pelo runner.\n")
elif "representabilidade" in "\n".join(t for _, t in runner):
out.append("\nAceita **status 3 sem stderr** quando o caso é representável na plataforma, ou **status 1 com o trecho esperado** de erro fatal.\n")
else:
out.append("\nExige **status 1** e o trecho de stderr declarado na invocação.\n")
else:
out.append("Nenhuma invocação literal foi localizada; revisar o harness.\n")
out.append(self.mode_faq(mode))
self.page(f"testes/modos/{slug}", mode["mode"], "".join(out), label=mode["mode"])
mode_rows.append(self.faq(
"Perguntas frequentes sobre os modos de integração e falha fatal do harness.",
[
{"q": "Por que alguns testes precisam de um modo separado?",
"a": ["`bg_erro` encerra o processo com status 1. Um teste que provoca erro fatal não "
"pode continuar no mesmo processo; o runner então reexecuta o binário com um modo "
"que isola o cenário e confere o diagnóstico."]},
{"q": "Como rodar todos os modos de uma vez?",
"a": ["A suíte da biblioteca percorre os modos e valida status e stderr."],
"code": "make test-biblioteca", "lang": "bash"},
{"q": "O que conta como aprovação?",
"a": [f"Há **{len(self.inv.modes)} modos** indexados. Cada invocação em "
"`tests/run_biblioteca.sh` declara o status e o texto de stderr aceitos; "
"terminar com sucesso onde se espera erro fatal é falha do teste."]},
{"q": "Um modo aprovado garante o mesmo comportamento em todo compilador?",
"a": ["Não. O harness é executado em GCC e Clang neste ambiente; MSVC, MinGW nativo e "
"AArch64 têm estados distintos registrados na [matriz]"
"(/projeto/11-matriz-compatibilidade)."]},
]))
self.page("testes/modos/index", "Modos de integração", "".join(mode_rows), label="Visão geral", position=0)

Nomes internos referenciados: fence.

Como este símbolo aparece nos testes​

Sem uso direto localizado

Nenhuma referência direta a este nome foi encontrada nos arquivos de teste. Isso pode ser esperado para guardas de inclusão, configuração ou código exercitado indiretamente; não é uma afirmação de cobertura zero.

Compiladores, padrão C e sistema operacional​

Nenhum ramo condicional externo foi detectado para este símbolo. A implementação é compartilhada no fonte; isso não certifica compiladores ou sistemas não executados.

  • Script Python: usa a biblioteca padrão e pathlib/subprocess quando aplicável; caminhos não devem depender do separador de um único OS.
Não confunda implementação com certificação

A matriz histórica distingue executado, compilado, avaliado e não testado. Consulte a matriz, os compiladores e os logs atuais dos workflows antes de chamar um alvo de suportado.

Perguntas frequentes​

Perguntas reunidas a partir da definição, do contrato editorial e dos testes de Renderer.render_tests. As respostas repetem apenas o que o repositório mostra; quando não há evidência, isso é dito.

Em uma frase, o que Renderer.render_tests faz?​

Gera índice de suítes, casos, harness e modos de integração.

Qual é a assinatura e o tipo de retorno de Renderer.render_tests?​

Assinatura extraída de tools/documentacao/render.py; visibilidade pública.

def render_tests(self) -> None:

Como chamar Renderer.render_tests corretamente?​

Nenhum exemplo editorial nem chamada direta em teste foi localizada. A forma de uso é a assinatura acima; os chamadores aparecem na seção de evidência indireta quando existem.

def render_tests(self) -> None:

Por que não há teste direto para Renderer.render_tests?​

A busca estática não encontrou o identificador nos arquivos de teste. Isso é esperado para guardas de inclusão, configuração de build e nomes alcançados apenas por chamadores internos. O JSON de cobertura registra a lacuna em vez de convertê-la em aprovação.

Renderer.render_tests depende de compilador, padrão C ou sistema operacional?​

Renderer.render_tests é uma função Python: requer Python 3.10+ e biblioteca padrão, sem compilador C.

O que acontece em caso de falha ou uso inválido?​

Não há ressalva editorial específica para este nome. O comportamento em falha é o do corpo/expansão mostrado acima; não invente validação que o fonte não faz.