# Test Coverage Plan (Português (Portugal)) 🌐 **Languages:** 🇺🇸 [English](../../../../ops/COVERAGE_PLAN.md) · 🇪🇹 [am](../../../am/docs/ops/COVERAGE_PLAN.md) · 🇸🇦 [ar](../../../ar/docs/ops/COVERAGE_PLAN.md) · 🇦🇿 [az](../../../az/docs/ops/COVERAGE_PLAN.md) · 🇧🇬 [bg](../../../bg/docs/ops/COVERAGE_PLAN.md) · 🇧🇩 [bn](../../../bn/docs/ops/COVERAGE_PLAN.md) · 🇧🇦 [bs](../../../bs/docs/ops/COVERAGE_PLAN.md) · 🇨🇿 [cs](../../../cs/docs/ops/COVERAGE_PLAN.md) · 🇩🇰 [da](../../../da/docs/ops/COVERAGE_PLAN.md) · 🇩🇪 [de](../../../de/docs/ops/COVERAGE_PLAN.md) · 🇬🇷 [el](../../../el/docs/ops/COVERAGE_PLAN.md) · 🇪🇸 [es](../../../es/docs/ops/COVERAGE_PLAN.md) · 🇪🇪 [et](../../../et/docs/ops/COVERAGE_PLAN.md) · 🇮🇷 [fa](../../../fa/docs/ops/COVERAGE_PLAN.md) · 🇫🇮 [fi](../../../fi/docs/ops/COVERAGE_PLAN.md) · 🇫🇷 [fr](../../../fr/docs/ops/COVERAGE_PLAN.md) · 🇮🇪 [ga](../../../ga/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [gu](../../../gu/docs/ops/COVERAGE_PLAN.md) · 🇳🇬 [ha](../../../ha/docs/ops/COVERAGE_PLAN.md) · 🇮🇱 [he](../../../he/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [hi](../../../hi/docs/ops/COVERAGE_PLAN.md) · 🇭🇷 [hr](../../../hr/docs/ops/COVERAGE_PLAN.md) · 🇭🇺 [hu](../../../hu/docs/ops/COVERAGE_PLAN.md) · 🇦🇲 [hy](../../../hy/docs/ops/COVERAGE_PLAN.md) · 🇮🇩 [id](../../../id/docs/ops/COVERAGE_PLAN.md) · 🇳🇬 [ig](../../../ig/docs/ops/COVERAGE_PLAN.md) · 🇮🇹 [it](../../../it/docs/ops/COVERAGE_PLAN.md) · 🇯🇵 [ja](../../../ja/docs/ops/COVERAGE_PLAN.md) · 🇬🇪 [ka](../../../ka/docs/ops/COVERAGE_PLAN.md) · 🇰🇭 [km](../../../km/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [kn](../../../kn/docs/ops/COVERAGE_PLAN.md) · 🇰🇷 [ko](../../../ko/docs/ops/COVERAGE_PLAN.md) · 🇱🇹 [lt](../../../lt/docs/ops/COVERAGE_PLAN.md) · 🇱🇻 [lv](../../../lv/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [ml](../../../ml/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [mr](../../../mr/docs/ops/COVERAGE_PLAN.md) · 🇲🇾 [ms](../../../ms/docs/ops/COVERAGE_PLAN.md) · 🇲🇹 [mt](../../../mt/docs/ops/COVERAGE_PLAN.md) · 🇲🇲 [my](../../../my/docs/ops/COVERAGE_PLAN.md) · 🇳🇵 [ne](../../../ne/docs/ops/COVERAGE_PLAN.md) · 🇳🇱 [nl](../../../nl/docs/ops/COVERAGE_PLAN.md) · 🇳🇴 [no](../../../no/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [or](../../../or/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [pa](../../../pa/docs/ops/COVERAGE_PLAN.md) · 🇵🇭 [phi](../../../phi/docs/ops/COVERAGE_PLAN.md) · 🇵🇱 [pl](../../../pl/docs/ops/COVERAGE_PLAN.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/COVERAGE_PLAN.md) · 🇷🇴 [ro](../../../ro/docs/ops/COVERAGE_PLAN.md) · 🇷🇺 [ru](../../../ru/docs/ops/COVERAGE_PLAN.md) · 🇱🇰 [si](../../../si/docs/ops/COVERAGE_PLAN.md) · 🇸🇰 [sk](../../../sk/docs/ops/COVERAGE_PLAN.md) · 🇸🇮 [sl](../../../sl/docs/ops/COVERAGE_PLAN.md) · 🇷🇸 [sr](../../../sr/docs/ops/COVERAGE_PLAN.md) · 🇸🇪 [sv](../../../sv/docs/ops/COVERAGE_PLAN.md) · 🇰🇪 [sw](../../../sw/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [ta](../../../ta/docs/ops/COVERAGE_PLAN.md) · 🇮🇳 [te](../../../te/docs/ops/COVERAGE_PLAN.md) · 🇹🇭 [th](../../../th/docs/ops/COVERAGE_PLAN.md) · 🇹🇷 [tr](../../../tr/docs/ops/COVERAGE_PLAN.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/COVERAGE_PLAN.md) · 🇵🇰 [ur](../../../ur/docs/ops/COVERAGE_PLAN.md) · 🇺🇿 [uz](../../../uz/docs/ops/COVERAGE_PLAN.md) · 🇻🇳 [vi](../../../vi/docs/ops/COVERAGE_PLAN.md) · 🇳🇬 [yo](../../../yo/docs/ops/COVERAGE_PLAN.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/COVERAGE_PLAN.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/COVERAGE_PLAN.md) --- Última atualização: 2026-06-28 > Estado medido em 2026-05-13: linhas 82,58%, instruções 82,58%, funções 84,23%, ramificações 75,22%. As fases 1-5 estão concluídas. O foco atual é a Fase 6 (>=85%) e a Fase 7 (>=90%). ## Referência Existem vários valores de cobertura, dependendo da forma como o relatório é calculado. Para efeitos de planeamento, apenas um deles é útil. | Métrica | Âmbito | Instruções / Linhas | Ramificações | Funções | Notas | | ---------------------- | ------------------------------------------------------------ | ------------------: | -----------: | ------: | ------------------------------------------------------------ | | Legada | Antigo `npm run test:coverage` | 79,42% | 75,15% | 67,94% | Inflacionada: conta ficheiros de teste e exclui `open-sse` | | Diagnóstico | Apenas código-fonte, excluindo testes e excluindo `open-sse` | 68,16% | 63,55% | 64,06% | Útil apenas para isolar `src/**` | | Referência recomendada | Apenas código-fonte, excluindo testes e incluindo `open-sse` | 82,58% | 75,22% | 84,23% | Esta é a referência global do projeto que deve ser melhorada | A referência recomendada é o valor a otimizar. ## Regras - Os objetivos de cobertura aplicam-se aos ficheiros de código-fonte, não a `tests/**`. - `open-sse/**` faz parte do produto e tem de permanecer no âmbito. - O novo código não deve reduzir a cobertura nas áreas alteradas. - Deve dar-se preferência a testar o comportamento e os resultados das ramificações, em vez dos detalhes de implementação. - Para `src/lib/db/**`, devem preferir-se bases de dados SQLite temporárias e pequenas fixtures a mocks abrangentes. ## Conjunto atual de comandos - `npm run test:coverage` - Principal mecanismo de controlo da cobertura do código-fonte para o conjunto de testes unitários - Gera `text-summary`, `html`, `json-summary` e `lcov` - `npm run coverage:report` - Relatório detalhado, ficheiro a ficheiro, da execução mais recente - `npm run test:coverage:legacy` - Apenas para comparação histórica ## Marcos | Fase | Objetivo | Foco | Estado | | ------ | -------------------------: | --------------------------------------------------------------------------------------- | ------------ | | Fase 1 | 60% de instruções / linhas | Ganhos rápidos e cobertura de utilitários de baixo risco | ✅ Concluída | | Fase 2 | 65% de instruções / linhas | Fundamentos da base de dados e das rotas | ✅ Concluída | | Fase 3 | 70% de instruções / linhas | Validação de fornecedores e análise de utilização | ✅ Concluída | | Fase 4 | 75% de instruções / linhas | Tradutores e auxiliares de `open-sse` | ✅ Concluída | | Fase 5 | 80% de instruções / linhas | Handlers de `open-sse` e ramificações do executor | ✅ Concluída | | Fase 6 | 85% de instruções / linhas | Casos extremos mais difíceis, défice de ramificações e conjuntos de testes de regressão | Em curso | | Fase 7 | 90% de instruções / linhas | Revisão final, eliminação de lacunas e progressão estrita | Pendente | A cobertura de ramificações e funções deve aumentar progressivamente em cada fase, mas o principal objetivo obrigatório é a cobertura de instruções / linhas. ## Pontos críticos prioritários Estes ficheiros têm atualmente a cobertura de linhas mais baixa (< 60%) e oferecem o melhor retorno para as Fases 6-7. Gerado a partir de `coverage/coverage-summary.json` em 2026-05-13: | # | Ficheiro | Linhas % | | --- | ------------------------------------------------------------ | -------: | | 1 | `open-sse/services/compression/validation.ts` | 7.87% | | 2 | `src/app/api/v1/batches/route.ts` | 9.67% | | 3 | `src/app/docs/components/FeedbackWidget.tsx` | 9.80% | | 4 | `open-sse/services/compression/toolResultCompressor.ts` | 10.00% | | 5 | `src/app/docs/components/DocCodeBlocks.tsx` | 10.63% | | 6 | `open-sse/services/compression/engines/rtk/lineFilter.ts` | 10.96% | | 7 | `open-sse/services/specificityRules.ts` | 11.28% | | 8 | `src/mitm/systemCommands.ts` | 12.19% | | 9 | `open-sse/services/compression/aggressive.ts` | 12.77% | | 10 | `src/app/api/v1/batches/[id]/cancel/route.ts` | 12.98% | | 11 | `open-sse/services/compression/progressiveAging.ts` | 13.26% | | 12 | `open-sse/services/compression/engines/rtk/smartTruncate.ts` | 13.43% | | 13 | `open-sse/services/compression/engines/rtk/deduplicator.ts` | 13.51% | | 14 | `src/lib/cloudAgent/agents/jules.ts` | 13.52% | | 15 | `open-sse/services/compression/lite.ts` | 14.46% | | 16 | `src/app/api/v1/rerank/route.ts` | 14.94% | | 17 | `open-sse/services/compression/preservation.ts` | 15.07% | | 18 | `src/lib/cloudAgent/agents/codex.ts` | 15.54% | | 19 | `open-sse/services/tierResolver.ts` | 16.66% | | 20 | `src/app/docs/components/DocsLazyWrapper.tsx` | 16.66% | Temas para as Fases 6-7: - `open-sse/services/compression/**` é o conjunto mais denso de ficheiros com baixa cobertura e representa a maior parte da lacuna restante. - As rotas das API de lotes e reordenação (`src/app/api/v1/batches/**`, `src/app/api/v1/rerank/route.ts`) necessitam de testes ao nível dos handlers. - Os adaptadores de agentes na nuvem (`src/lib/cloudAgent/agents/jules.ts`, `codex.ts`) e `tierResolver.ts` necessitam de testes de cenários. - Os componentes da IU da documentação e `src/mitm/systemCommands.ts` têm menor prioridade, mas permitem ganhos rápidos na cobertura de ramificações. ## Lista de verificação da execução ### Fase 1: 56.95% -> 60% - [x] Corrigir a métrica de cobertura para que reflita o código-fonte em vez dos ficheiros de teste - [x] Manter um script de cobertura legado para comparação - [x] Registar a referência inicial e os pontos críticos no repositório - [ ] Adicionar testes direcionados para utilitários de baixo risco: - `src/shared/utils/upstreamError.ts` - `src/shared/utils/fetchTimeout.ts` - `src/lib/api/errorResponse.ts` - `src/shared/utils/apiAuth.ts` - `src/lib/display/names.ts` - [ ] Adicionar testes de rotas para: - `src/app/api/settings/require-login/route.ts` - `src/app/api/providers/[id]/models/route.ts` ### Fase 2: 60% -> 65% - [ ] Adicionar testes suportados por uma base de dados para: - `src/lib/db/modelComboMappings.ts` - `src/lib/db/settings.ts` - `src/lib/db/registeredKeys.ts` - [ ] Cobrir o comportamento das ramificações em: - `src/lib/providers/validation.ts` - `src/app/api/v1/embeddings/route.ts` - `src/app/api/v1/moderations/route.ts` ### Fase 3: 65% -> 70% - [ ] Adicionar testes de análise de utilização para: - `src/lib/usage/usageHistory.ts` - `src/lib/usage/usageStats.ts` - `src/lib/usage/costCalculator.ts` - [ ] Expandir a cobertura de rotas para a gestão de proxies e as ramificações das definições ### Fase 4: 70% -> 75% - [ ] Cobrir os utilitários do tradutor e os caminhos centrais de tradução: - `open-sse/translator/index.ts` - `open-sse/translator/helpers/*` - `open-sse/translator/request/*` - `open-sse/translator/response/*` ### Fase 5: 75% -> 80% - [ ] Adicionar testes ao nível dos handlers para: - `open-sse/handlers/chatCore.ts` - `open-sse/handlers/responsesHandler.js` - `open-sse/handlers/imageGeneration.js` - `open-sse/handlers/embeddings.js` - [ ] Adicionar cobertura de ramificações do executor para autenticação específica de fornecedores, novas tentativas e substituições de endpoints ### Fase 6: 80% -> 85% - [ ] Integrar mais conjuntos de testes de casos extremos no fluxo principal de cobertura - [ ] Aumentar a cobertura de funções dos módulos de base de dados com baixa cobertura de construtores/utilitários - [ ] Eliminar lacunas de cobertura de ramificações em `settings.ts`, `registeredKeys.ts`, `validation.ts` e nos utilitários do tradutor ### Fase 7: 85% -> 90% - [ ] Tratar os restantes ficheiros com baixa cobertura como bloqueadores - [ ] Adicionar testes de regressão para todos os erros em produção corrigidos durante o avanço até aos 90% - [ ] Aumentar o limite mínimo de cobertura na CI apenas depois de a referência local permanecer estável durante, pelo menos, duas execuções consecutivas ## Política de ratchet Atualize os limiares de `npm run test:coverage` apenas depois de o projeto ultrapassar efetivamente o marco seguinte com uma margem confortável. **Limite atual:** `npm run test:coverage` impõe **60 instruções / 60 linhas / 60 funções / 60 ramificações** (a métrica foi recalibrada na Fase 6A.1 das Quality-Gates — o valor de referência anterior de 82,58% estava inflacionado porque contabilizava os ficheiros de teste e excluía `open-sse`). O comando `test:coverage:legacy` preserva a antiga métrica 50/50/50 para comparação histórica. Para verificações pontuais dos limiares com base no relatório mais recente, utilize: ```bash node scripts/check/test-report-summary.mjs --threshold 75 ``` Sequência de ratchet recomendada (a ordem é `instruções-linhas / ramificações / funções`): 1. 55/60/55 2. 60/62/58 3. 65/64/62 4. 70/66/66 5. 75/70/72 <-- limite atual (75/70/75) 6. 80/75/78 7. 85/80/84 8. 90/85/88 O próximo objetivo do ratchet é `80/75/78`, assim que a cobertura de ramificações se mantiver acima de 78% em duas execuções consecutivas. ## Lacuna conhecida O comando de cobertura atual mede o conjunto principal de testes unitários do Node e inclui o código-fonte alcançado a partir do mesmo, incluindo `open-sse`. Ainda não combina a cobertura do Vitest num único relatório unificado. Vale a pena efetuar essa combinação mais tarde, mas não constitui um impedimento para iniciar a progressão de 60% -> 80%.