# 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

| Comando | O que executa | Precisa de `git` |
|---------|--------------|-------------|
| `composer test:unit` | Suíte PHPUnit `unit`: testes isolados de componentes | Não |
| `composer test:integration` | Suíte PHPUnit `integration`: Pitmaster e `git` trabalhando nos mesmos repositórios | Sim |
| `composer test:oracle` | `bin/test-regression`: todos os cenários do oráculo | Sim |
| `composer test` | PHPUnit (ambas as suítes) mais a regressão do oráculo | Sim |
| `./bin/verify-all` | `composer verify`: evidências de suporte, divergências upstream, artefato de prova, teste rápido de mutação, `composer audit`, PHPStan, padrões de código e `composer test` | Sim |

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:

```json
{
    "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](https://pitmaster.inline0.dev/pt/docs/operations/diff).

### Trabalhar com cenários

```bash
./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:

```bash
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:

| Status | Significado |
|--------|---------|
| `DONE` | Implementado e verificado pelo oráculo dentro do escopo de paridade declarado |
| `PART` | Parcialmente implementado |
| `TODO` | Dentro do escopo, ainda não implementado |
| `DEFER` | Ainda não planejado |
| `N/A` | Fora do escopo |

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](https://github.com/inline0/pitmaster/issues).

## Benchmarks

O trabalho de desempenho usa o harness em `bench/`:

```bash
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.