Pular para o conteúdo principal

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​

ArquivoPapel
programa.c, *.c, *.hfontes do caso — a fonte BG é .c (todos compilados juntos)
entrada.txto que vai para o stdin (ausente = /dev/null)
esperado.txtsaída esperada em stdout (obrigatório em caso de execução)
alternativo.txtoutra saída exata aceita quando a plataforma difere (ex.: precisão x87)
esperado_rc.txtcódigo de saída esperado (padrão 0)
esperado_stderr.txttrecho que precisa aparecer em stderr
esperado_erro.txtmensagens de erro aceitas (casos negativos) — ver abaixo
cflags.txtflags 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
objetosmarcador: compilar cada fonte com -c e ligar depois (multi-arquivo real)
sem_m0 / sem_m1marcador: 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.sh fixa LC_ALL=C — com locale UTF-8 o GCC troca ' por ‘, e um locale traduzido mudaria a mensagem inteira. A biblioteca em si nunca chama setlocale (D-17).
  • tests/lib.sh normaliza 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 \n para \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:

ArquivoO que prova
precedencia.ca precedência documentada (E/OU/NAO, aritmética, comparação) avaliada em execução
controle.cSE/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.climites de tipo (176 verificações): INT_MAX, estouro, MIN/-1, NaN, long double
cabecalhos_tu{1,2,3}.c + cabecalhos_principal.c4 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.cppos 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​

ScriptFunção
run_portabilidade.sha matriz acima (-v lista as aprovadas, -q só o resumo)
run_matriz.shroda as três suítes com cada compilador encontrado, em build-matriz/<nome>/
run_checkout_limpo.shcopia só o que o Git versionaria e roda os comandos da documentação
fuzz_basicgolc.pymutações determinísticas (seed fixa) do basicgolc; contrato: não derrubar, não travar
tools/cobertura.pygera COBERTURA.md sem data (determinístico, para o CI comparar); --data gera a versão datada

Como adicionar um caso​

  1. Crie tests/casos/<suíte>/<nome>/programa.c.
  2. 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).
  3. Salve como esperado.txt e rode ./tests/run.sh <suíte>.
  4. Rode make cobertura para 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.