README original dos testes
make test # tudo
make test-v # tudo, listando cada verificação aprovada
./tests/run.sh 03 # só uma suíte (prefixo do nome)
make test-portabilidade # matriz de compiladores, avisos, multi-UO, C++, alvos cruzados
make test-sanitize # a suíte inteira sob ASan + UBSan + LeakSanitizer
make test-matriz # a suíte inteira com cada compilador encontrado
make fuzz # mutação determinística do transpilador
make test-checkout # os comandos do README, a partir de um checkout limpo
python3 tests/auditar_exemplos.py --cc gcc --flag=-std=c11 --basicgolc build/basicgolc --library build/libbasicgol.a
# também tenta examples/, com sondagens separadas por alvo
A suíte de linguagem usa bash, um compilador C11, build/basicgolc e
build/libbasicgol.a (construídos por make). Os testes unitários da biblioteca
são tests/test_biblioteca.c, executados por tests/run_biblioteca.sh. O conjunto
completo também precisa de ar, mktemp, diff e Python 3 para a cobertura. Os
runners criam diretórios temporários e os apagam ao terminar.
make test-biblioteca # somente biblioteca modular
make test # linguagem M0/M1 + biblioteca
A ideia central: um caso, dois caminhos
Todo caso de execução roda duas vezes — caminho M0 (as macros de
include/basicgol.h) e caminho M1 (build/basicgolc traduz e compila o C emitido) —
e só passa se os dois produzirem exatamente a saída dourada. A equivalência M0 × M1
(AC-32) não é um teste solto: ela é uma propriedade de cada um dos casos.
Layout
tests/
├── run.sh # as suítes 01…11 (cada uma é um bloco if; 09_tipos_expr é
│ # dirigida pela árvore de casos, como 02…08)
├── lib.sh # compila_m0, compila_m1, compila_objetos, roda, difere, caso_*
├── expansoes.txt # tabela de ouro das expansões (AC-22), comparada com `cc -dM -E`
├── COBERTURA.md # matriz de rastreabilidade (gerada por `make cobertura`)
└── casos/
├── 02_basico/ tipos, operadores, texto, utilidades
├── 03_controle/ SE/ENQUANTO/REPITA/PARA/ESCOLHA e desvios
├── 04_estruturas/ VETOR, REGISTRO, ENUMERACAO, funções, recursão
├── 05_entrada_saida/ ESCREVA*, LEIA*, ERRO/AFIRME, truncamento
├── 06_negativos/ erros do compilador C (esperado_erro.txt)
├── 07_multiarquivo/ módulos, EXTERNO/ESTATICO, C puro junto de BG
├── 08_aplicacao/ sistema de acervo (3 módulos + cabeçalho)
├── 09_tipos_expr/ tipos, conversões, precedência, divisão verificada,
│ texto seguro, entrada numérica, extensões opcionais
├── 12_negativos_m1/ diagnósticos do transpilador (esperado_erro.txt)
└── 13_avisos/ um caso por aviso W-01…W-07
Convenção de arquivos de um caso
| Arquivo | Papel |
|---|---|
programa.c, *.c, *.h | fontes do caso — a fonte BG é .c (todos compilados juntos) |
entrada.txt | o que vai para o stdin (ausente = /dev/null) |
esperado.txt | saída esperada em stdout (obrigatório em caso de execução) |
alternativo.txt | outra saída exata aceita quando a plataforma difere (ex.: precisão x87) |
esperado_rc.txt | código de saída esperado (padrão 0) |
esperado_stderr.txt | trecho que precisa aparecer em stderr |
esperado_erro.txt | mensagens de erro aceitas (casos negativos) — ver abaixo |
cflags.txt | flags extras só deste caso — evite: a Fase 6 trocou a única que havia (-Wno-implicit-fallthrough no caso c19) por __attribute__((fallthrough)) no ponto exato |
objetos | marcador: compilar cada fonte com -c e ligar depois (multi-arquivo real) |
sem_m0 / sem_m1 | marcador: pular um dos caminhos |
Um caso só precisa declarar o que é diferente do padrão — a ausência de entrada.txt,
por exemplo, significa "sem entrada".
Casos negativos e o texto do compilador
esperado_erro.txt lista, uma por linha, as mensagens aceitas para o caso: linha vazia é
ignorada e linha que começa com # é comentário. O caso passa se o programa não compilar
(e, no caminho M1, se o basicgolc recusar) e se pelo menos uma das linhas aparecer no
diagnóstico — comparação de texto fixo, sem expressão regular.
Isso é de propósito. O texto das mensagens do caminho M0 é do compilador, não da linguagem: GCC e Clang redigem o mesmo erro de formas diferentes, e o próprio GCC muda a redação entre versões. Por isso cada caso guarda as variantes (normalmente uma do GCC e uma do Clang) em vez de exigir uma frase única:
# GCC: "expected expression before '=' token"; Clang: "expected expression".
expected expression
Duas salvaguardas completam isso, para que a suíte não dependa da máquina:
tests/run.shfixaLC_ALL=C— com locale UTF-8 o GCC troca'por‘, e um locale traduzido mudaria a mensagem inteira. A biblioteca em si nunca chamasetlocale(D-17).tests/lib.shnormaliza as aspas tipográficas (‘ ’ “ ”→' ") antes de comparar, então a comparação também vale quando alguém roda o runner fora do CI com outro locale.- Os runners comparam a saída de console sem
\r: o CRT do Windows pode traduzir\npara\r\n, enquanto os arquivos de saída esperada permanecem com LF.
Os diagnósticos do basicgolc (12_negativos_m1) usam o mesmo formato — ali o texto é
nosso e vem da especificação (§4.3), então basta uma linha por caso.
No Windows com MSVC
A suíte de linhas de comando continua sendo bash (rode no Git Bash); o que muda é
o compilador. tests/run_biblioteca.sh aceita o binário de testes compilado pelo MSVC
(build\test-biblioteca.exe) e normaliza o \r que o CRT escreve no modo texto. Para os
exemplos, tests/run_msvc.sh reconstrói cada um com cl.exe nos caminhos M0 e M1 e
compara com a saída dourada (byte a byte, ignorando apenas \r):
:: num Developer Command Prompt (ou Git Bash: barras e / são aceitos pelo cl.exe)
mkdir build\biblioteca
cl /nologo /TC /std:c11 /W4 /WX /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_WARNINGS tools\basicgolc.c /Fo:build\basicgolc.obj /Fe:build\basicgolc.exe
for %%f in (src\biblioteca\*.c) do cl /nologo /TC /std:c11 /W4 /WX /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_WARNINGS /I include /c %%f /Fo:build\biblioteca\
lib /nologo /OUT:build\libbasicgol.lib build\biblioteca\*.obj
cl /nologo /TC /std:c11 /W4 /WX /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_WARNINGS /I include tests\test_biblioteca.c /Fo:build\test-biblioteca.obj /Fe:build\test-biblioteca.exe /link build\libbasicgol.lib
bash ./tests/run_biblioteca.sh build/test-biblioteca.exe
bash ./tests/run_msvc.sh
O passo a passo exato (inclusive a linha do lib.exe sobre os .obj) está no workflow
.github/workflows/msvc.yml, que roda tudo isso no
windows-latest a cada push e pull request. tests/run.sh (a suíte da linguagem) depende
do driver GCC — -std=, -lm, -o — e não fala cl.exe; não é para rodar no MSVC.
Programas de portabilidade (tests/portabilidade/)
Fora da árvore casos/ — porque não são casos M0×M1 com saída dourada, e sim
programas que exercitam a portabilidade — ficam os arquivos consumidos por
tests/run_portabilidade.sh:
| Arquivo | O que prova |
|---|---|
precedencia.c | a precedência documentada (E/OU/NAO, aritmética, comparação) avaliada em execução |
controle.c | SE/ENQUANTO/REPITA/ESCOLHA/PARE/PROSSIGA em casos de borda, nos dois perfis |
entrada.c (.entrada.txt, .esperado.txt) | contrato de LEIA/LEIA_TEXTO/LEIA_INTEIRO e o comportamento em entrada inválida, com saída dourada |
fronteira.c | limites de tipo (176 verificações): INT_MAX, estouro, MIN/-1, NaN, long double |
cabecalhos_tu{1,2,3}.c + cabecalhos_principal.c | 4 unidades de tradução, inclusão múltipla do mesmo cabeçalho, BG_SEM_APELIDOS, BG_USAR_EXTENSOES por UO, e nenhum símbolo global extra (auditado com nm) |
cpp_inclusao.cpp | os cabeçalhos de módulo em C++17 (extern "C" + BG_NORETURN) |
O runner tem 11 seções (padrões de C, cabeçalhos autocontidos, programas por
compilador, M0×M1, saída dourada, multi-UO, nm, conjunto estrito de avisos,
sanitizers, C++, alvos cruzados) e grava uma linha por verificação em
build/relatorio/portabilidade.tsv. Ele ignora (não aprova) o que não pode
executar: sem zig no PATH, as verificações de alvo cruzado não rodam; sem
wine, os binários Windows não são executados.
Ferramentas auxiliares
| Script | Função |
|---|---|
run_portabilidade.sh | a matriz acima (-v lista as aprovadas, -q só o resumo) |
run_matriz.sh | roda as três suítes com cada compilador encontrado, em build-matriz/<nome>/ |
run_checkout_limpo.sh | copia só o que o Git versionaria e roda os comandos da documentação |
fuzz_basicgolc.py | mutações determinísticas (seed fixa) do basicgolc; contrato: não derrubar, não travar |
tools/cobertura.py | gera COBERTURA.md sem data (determinístico, para o CI comparar); --data gera a versão datada |
Como adicionar um caso
- Crie
tests/casos/<suíte>/<nome>/programa.c. - Rode o programa uma vez e confira à mão a saída (nunca aceite a saída só porque o programa a produziu: o teste existe para pegar erro, não para congelar erro).
- Salve como
esperado.txte rode./tests/run.sh <suíte>. - Rode
make coberturapara atualizar a matriz — ela lista o caso automaticamente. O arquivo gerado é determinístico (sem data), então o commit mostra só a linha nova.
Se o caso documenta uma decisão da especificação, cite o C-xx/D-xx no comentário do
fonte: quem lê o teste depois entende por que ele existe.
Símbolos citados neste documento
Nomes que aparecem literalmente no texto acima e que possuem página de referência gerada do fonte:
BG_NORETURN, BG_SEM_APELIDOS, BG_USAR_EXTENSOES.
Perguntas frequentes
Perguntas frequentes sobre este documento, respondidas a partir do conteúdo versionado e da referência gerada.
Quais são os comandos de teste?
make test roda a suíte completa; os demais alvos isolam camadas (biblioteca, portabilidade, sanitizers, matriz, fuzz, checkout limpo).
make test
make test-biblioteca
make test-portabilidade
make test-sanitize
make fuzz
O que preciso ter instalado?
Bash, compilador C11, ar, mktemp, diff e Python 3 para a cobertura. Os runners criam diretórios temporários e os apagam ao terminar; no Windows o projeto usa Git Bash/MSYS2.
Como rodo só uma suíte?
./tests/run.sh aceita o prefixo do nome da suíte.
./tests/run.sh 03
Por que o total impresso muda entre execuções?
Porque o runner conta o que realmente executou naquele ambiente: ferramentas disponíveis, sanitizers e modos. As contagens do site são estáticas e não substituem o log.