Testes¶
Testes unitários¶
Os testes unitários cobrem análise de ambiente, geração da configuração da ponte, tratamento de argumentos de inicialização e ferramentas locais de introspecção do Cloak.
Os testes de bloqueio de perfis persistentes cobrem a recuperação após o encerramento do proprietário, proprietários ativos ou com estado incerto, alterações no arquivo de bloqueio e limpeza após gravações parciais.
Testes de integração¶
Os testes de integração usam um processo filho MCP upstream falso e verificam que a ponte mescla ferramentas locais e encaminha chamadas upstream sem alterações.
npm run check inclui verificações estáticas, testes unitários/de integração e do CLI empacotado com upstream MCP simulado, sem Chromium. Nos PRs, os testes unitários/de integração e do CLI são executados uma vez por combinação de plataforma e Node.js: 22, 24, 26 em Linux x64/arm64, macOS x64/arm64 e Windows x64. Linux x64 coleta a cobertura para Codecov nessa mesma execução. As verificações estáticas e do pacote são executadas uma vez em Linux x64/Node.js 22.
Os testes do CLI empacotado verificam a reinicialização após um encerramento forçado, a rejeição de um servidor concorrente enquanto o proprietário está ativo e a limpeza quando o cliente fecha stdin.
A matriz de CI, o inventário de resultados esperados e a documentação leem as versões do Node.js de .github/workflows/ci.yml. Atualize esse arquivo quando as linhas de versões testadas mudarem.
Testes com navegador real e distribuições¶
npm run test:e2e
npm run test:e2e:playwright-console
npm run test:e2e:cdp
npm run test:e2e:npm-package
npm run test:e2e:docker
npm run test:e2e:cdp:docker
test:e2e combina testes de CLI com fake upstream e testes de console com Playwright Chromium real. test:e2e:playwright-console verifica métodos de console em sessões novas. test:e2e:cdp verifica acesso gerenciado por Chrome DevTools Protocol (CDP) com Free CloakBrowser e Playwright Chromium controlado.
test:e2e:npm-package empacota e instala o pacote em um projeto temporário. O teste do contrato de encaminhamento usa fake upstream; os cenários de navegador usam CloakBrowser real e páginas locais para verificar ferramentas padrão, estado persistente e ambos os presets de humanização. Outro teste verifica downloads concorrentes em um cache vazio e stdout sem texto adicional. A verificação do pacote, sozinha, não valida o navegador.
A matriz de navegador do PR verifica o console do Playwright e o CDP gerenciado com Node.js 26 nas mesmas cinco plataformas, além de Linux x64/Node.js 22 para CDP. Uma matriz paralela de Node.js 24 executa as suítes do pacote npm, proxy/GeoIP, extensões e ciclo de vida nas cinco plataformas, incluindo ambos os presets de humanização. A aceitação de Docker e CDP cobre ambos os motores em linux/amd64 e linux/arm64.
required-ci exige o sucesso de todas as suítes e do relatório agregado completo antes do merge. O mesmo workflow CI também é executado semanalmente e manualmente. Release compila e publica artefatos da revisão testada.
Relatórios de testes¶
Cada célula da matriz CI envia resultados sanitizados e anexos de diagnóstico. O job de agregação combina tudo em um relatório HTML do Allure, mantendo as etiquetas de suite e ambiente. Produtores esperados ausentes e testes com falha fazem a agregação falhar; os resultados originais e o HTML continuam disponíveis como artefatos do Actions.
PRs elegíveis podem publicar um link por meio do repositório separado de relatórios configurado. A publicação exige entrega habilitada, evidências validadas da execução e verificação bem-sucedida do Pages. O site de documentação é implantado separadamente. Relatórios públicos contêm apenas diagnósticos permitidos e sanitizados de fixtures controladas.
npm run test:report -- --suite unit --run-id local
npm run test:report:generate -- --input artifacts/test-results --output artifacts/test-report/local
npm run test:report:open -- --report artifacts/test-report/local
Use o diretório real de saída do coletor como entrada do gerador. Consulte Contribuindo para formatos, anexos e entrega pelo CI.
Verificação do pacote¶
Isso compila o pacote, executa npm pack, verifica a lista de arquivos do tarball, instala o tarball em um projeto temporário e valida --version e --help da CLI.
A verificação do pacote também valida server.json contra o esquema publicado de servidor MCP.
A montagem da versão usa npm run package:pack para criar o arquivo e validar seus metadados e arquivos incluídos. A instalação e a execução do CLI são verificadas antes do merge por package:verify.
Smoke test de Docker¶
O smoke test verifica que a imagem criada inicia e imprime a ajuda da CLI. O CI executa smoke tests das imagens Docker para linux/amd64 e linux/arm64.
Paridade com upstream¶
npm run bridge:compare
npm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json
O script de paridade inicia a imagem Docker oficial do Playwright MCP e a imagem da ponte CloakBrowser, compara os nomes das ferramentas upstream, exercita a superfície padrão de ferramentas de navegador em uma mesma página fixture e verifica as ferramentas locais de introspecção do Cloak.
CI envia o relatório JSON de paridade a partir dos jobs de Docker. A paridade do navegador é verificada em linux/amd64; ambas as arquiteturas executam testes básicos, análise de vulnerabilidades, testes de distribuição e CDP. A paridade cobre a versão fixada do Docker MCP; a suíte npm verifica npm MCP separadamente.
Verificações de segurança¶
O CI também executa CodeQL, Dependency Review, OpenSSF Scorecard, zizmor e Trivy. Essas ferramentas são gratuitas para repositórios públicos e não exigem contas externas.