Testes e o oráculo do git

Pitmaster usa o binário canônico do git como oráculo: se git aceita o que Pitmaster grava, e Pitmaster lê o que git grava, o comportamento está correto. A infraestrutura de testes fica no repositório Pitmaster. O pacote Composer inclui apenas src/ e bin/pitmaster, então execute tudo abaixo a partir de um clone após composer install.

Suítes de testes

O CI executa a suíte de unidade em várias versões de PHP, a suíte de integração, a regressão do oráculo (PITMASTER_TEST_JOBS=4) e as verificações de evidências de suporte e divergências upstream.

Cenários do oráculo

Cada cenário é um diretório dentro de scenarios/<category>/ (761 no total; 156 escritos para Pitmaster e 605 importados de outras implementações de Git):

scenarios/diff/diff-add-lines/
  scenario.json   # commands and expectations
  setup.sh        # builds the starting repository
  oracle/         # outputs captured from git

scenario.json especifica o comando a executar com git e o comando equivalente de Pitmaster, além do que deve coincidir:

{
    "name": "diff-add-lines",
    "category": "diff",
    "operations": ["diff"],
    "oracle_commands": { "diff": "git -c color.ui=never diff" },
    "actual_commands": { "diff": "php \"{{ROOT}}/bin/pitmaster\" diff | perl -pe 's/\\e\\[[0-9;]*m//g'" },
    "expectations": { "exact_match": ["diff"], "fsck_clean": true }
}

Uma execução copia o repositório criado por setup.sh, executa o oráculo e os comandos Pitmaster em cópias separadas e compara saídas, objetos, referências e log. fsck_clean também exige que git fsck aceite o repositório gravado por Pitmaster. A saída do oráculo é capturada de git quando está ausente ou é atualizada; caso contrário, são usados os arquivos oracle/ incluídos no repositório.

Um cenário abrange exatamente os casos criados pela sua configuração. Os cenários de diff, por exemplo, comparam arquivos modificados, por isso não detectam as diferenças na saída de diff para arquivos novos, excluídos e binários listadas em Diff.

Trabalhar com cenários

./bin/test-scenario <name>                 # oracle, actual, compare for one scenario
./bin/test-regression                      # all scenarios
./bin/test-regression --jobs 4             # in parallel (or PITMASTER_TEST_JOBS=4)
./bin/test-regression --category diff      # one category
./bin/test-regression --fast               # pass/fail only, no reports

./bin/oracle <name>                        # capture git output for a scenario
./bin/oracle --refresh <name>              # re-capture, for example after a git upgrade
./bin/actual <name>                        # run Pitmaster and capture its output
./bin/compare <name>                       # compare oracle and actual output

Para verificar várias versões de git, liste-as em PITMASTER_TEST_GIT_BINARIES e execute o teste rápido:

PITMASTER_TEST_GIT_BINARIES=/path/to/git-2.45:/path/to/git-2.46 \
  vendor/bin/phpunit --filter MultiGitVersionSmokeTest

Conjuntos de testes upstream

Os cenários em scenarios/upstream/ são importados das suítes de teste de outras implementações: a suíte de testes do próprio git (412), isomorphic-git (71), libgit2 (63), go-git (46), JGit (7) e dulwich (6). As árvores de fixtures necessárias estão incluídas em fixtures/upstream/, então o conjunto completo pode ser executado a partir de um clone novo sem acesso à rede nem caminhos locais da máquina. Os scripts de configuração as encontram pela variável de ambiente PITMASTER_ROOT.

composer verify:drift (bin/audit-upstream-drift) verifica se cada caso upstream incluído está associado a um cenário.

Matriz de suporte

SUPPORT_MATRIX.md no repositório lista cada recurso de git dentro do escopo e seu status:

O arquivo é gerado por bin/support-matrix a partir de config/support-matrix.json. config/support-evidence.json associa cada linha de DONE e PART a testes concretos e cenários do oráculo, e composer verify:evidence falha quando uma linha não tem evidências. O CI regenera a matriz e falha se o arquivo no repositório for diferente.

Uma linha DONE significa que os cenários registrados para ela correspondem a git. O comportamento ainda pode divergir fora desses cenários; as diferenças conhecidas são acompanhadas no rastreador de problemas.

Benchmarks

O trabalho de desempenho usa o harness em bench/:

composer bench -- --suite=smoke --runs=1 --warmups=0   # quick check
composer bench:baseline                                # full report
composer bench:compare -- <before.json> <after.json>   # compare two reports
composer bench:verify -- <report.json> bench/reports/smoke-thresholds.json

O CI verifica o relatório do teste rápido em relação aos limites registrados.