# Desempenho e testes

TailwindPHP prioriza a correção. Quando uma alteração específica de PHP melhora o desempenho sem alterar a saída, ela é aplicada e marcada como `@port-deviation:performance`. A paridade com TailwindCSS não é presumida — ela é verificada continuamente com o próprio conjunto de testes de Tailwind.

## Desempenho

A versão portada de PHP prioriza a correspondência com a saída de TailwindCSS em vez da velocidade bruta, e o original em TypeScript continua mais rápido de qualquer forma — o JIT de V8 compila os trechos mais executados em código nativo de um modo que PHP não consegue igualar. Para CSS gerado por requisição ou página, reutilize um compilador (consulte [generateExact()](https://tailwindphp.inline0.dev/pt/docs/api#accumulating-vs-exact-generation)) e persista seu estado de construção com [`stateCacheFile`](https://tailwindphp.inline0.dev/pt/docs/advanced/caching#compiler-state-cache).

Alguns trechos mais executados contam com otimizações ajustadas manualmente que **preservam uma saída idêntica**:

- **`ast.php` `toCss()`** — acumula fragmentos em um array e os `implode` uma só vez, em vez de concatenar strings repetidamente, e usa strings de recuo pré-calculadas.
- **`css-parser.php`** — compara caracteres diretamente, sem passar por `ord()`, e acompanha o tamanho dos buffers em vez de recalcular `strlen()`.

Ambas estão documentadas com `@port-deviation:performance` e condicionadas ao conjunto de testes — não podem alterar o CSS gerado.

### Benchmarks

O diretório `benchmarks/` contém um script de comparação. Execute-o com:

```bash
composer bench         # PHP vs TypeScript
composer bench:save    # write benchmarks/results.json
```

Resultados de exemplo em PHP 8.4.5 / Node.js v22.17.0 (Apple M1):

| Benchmark | PHP | TypeScript |
|-----------|-----|------------|
| `css-parser` em preflight.css | ~816 ops/s | ~15.45K ops/s (≈20× mais rápido) |
| `toCss` | ~65.85K ops/s | ~2.59M ops/s (≈39× mais rápido) |

TypeScript é mais rápido nessas operações de baixo nível, como esperado. Para a geração de CSS de páginas completas — o caso de uso real —, o desempenho de PHP é adequado (cerca de 14 ms por página na execução de exemplo). Para entradas idênticas repetidas, o [cache de arquivos](https://tailwindphp.inline0.dev/pt/docs/advanced/caching) elimina totalmente esse custo.

## Testes e paridade

Os testes garantem que a versão portada de PHP produza a mesma saída que TailwindCSS. Duas abordagens funcionam em conjunto.

**1. Testes baseados em extração.** Os scripts em `test-coverage/` analisam os próprios arquivos `.test.ts` de TailwindCSS e extraem os casos de teste para JSON. Em seguida, PHPUnit executa esses casos por meio de TailwindPHP e compara a saída com o CSS esperado. Como as expectativas vêm diretamente do projeto upstream, qualquer divergência no comportamento de PHP aparece como falha. Esses testes cobrem os aspectos mais complexos: utilitários, variantes, integração, funções CSS e testes `ui.spec` no navegador.

**2. Testes unitários portados manualmente.** Arquivos de teste mais simples de TypeScript (AST, análise de CSS, escape, análise de candidatos, análise de valores, …) são portados diretamente para PHP e ficam ao lado do código-fonte como `*.test.php`, espelhando a estrutura e as asserções dos originais.

O ciclo é **extrair → executar → verificar**: extrair novamente da referência atual de TailwindCSS, executar o conjunto de testes e detectar qualquer divergência como falha. Isso mantém a versão portada em sincronia com o projeto upstream e permite validar mecanicamente uma atualização de TailwindCSS, em vez de inspecioná-la manualmente. Divergências fazem o CI falhar.

```bash
composer extract   # re-extract test cases from the TailwindCSS reference
composer test      # run the full suite
```

Há **4,427 testes aprovados** na versão 1.7.0 (referência TailwindCSS v4.3.3):

| Conjunto | Testes | Fonte |
|-------|-------|--------|
| Conjuntos de TailwindCSS extraídos (utilitários 706, variantes 164, índice 148, css-functions 64, `ui.spec` 68) | 1,150 | extraídos de `.test.ts` / `.spec.ts` |
| Cobertura de API (utilitários, modificadores, variantes, diretivas, plugins, importações, `@source`, cache, API público) | 2,252 | `tests/` |
| Testes unitários junto ao código-fonte (parser, AST, candidatos, tema, utilitários, parser de seletores, transformações de lightningcss, minificador) | 767 | versões portadas de `*.test.php` e testes específicos de PHP |
| CLI (análise de argumentos, saída, builds) | 84 | `tests/Cli*Test.php` |
| Versões portadas de plugins (tipografia, formulários) | 45 | `*.test.php` junto aos plugins |
| Bibliotecas complementares (clsx, tailwind-merge, CVA) | 129 | conjuntos de referência |

## Qualidade do código

A formatação e a análise estática são executadas por meio dos scripts de Composer:

```bash
composer lint      # Pint --test  (check formatting)
composer format    # Pint         (fix formatting)
composer analyse   # PHPStan      (static analysis, level 4)
composer quality   # lint + analyse
```

PHPStan é executado no nível 4 (`phpstan.neon`), com uma pequena lista de padrões ignorados para as estruturas dinâmicas de array usadas pela arquitetura baseada em funções. Todos os arquivos-fonte são analisados; os arquivos de teste são excluídos.

Para ver a estrutura verificada por esses testes e onde os desvios são registrados, consulte [Arquitetura](https://tailwindphp.inline0.dev/pt/docs/advanced/architecture).