Testing Policy

Quando rodar cada categoria de teste, prioridades, gating no CI, política de flakes, política de skips. Complementa `specs/testing/taxonomy.md` (definições) e `specs/testing/coverage-matrix.md` (componente → categorias).

Policy: Testing

1. Pirâmide de testes da Koder Stack

                     /\
                    /  \
                   / Mu \         mutation, soak, chaos
                  /------\        — só nightly / release tag
                 / Bench  \
                /----------\      perf, stress
               /  Behaviour \     — pre-push / nightly
              /--------------\
             /     Flow       \   flow, e2e, install, usability
            /------------------\  — pre-push (host); nightly (device)
           /     Integration    \
          /----------------------\ integration, api, contract
         /          UI            \— pre-push
        /--------------------------\
       /        Functional          \
      /------------------------------\ ui, functional
     /             Unit               \— pre-commit
    /----------------------------------\
   /                Static              \ regression, security, smoke
  /--------------------------------------\— pre-commit

Camada base = mais testes, mais rápidos, executados primeiro. Nunca inverter (anti~~padrão *ce~~cream cone* muitos E2E manuais, poucos unit).

2. Gating por estágio do pipeline

Estágio	Quando	Categorias rodadas	Falha bloqueia?
re-commit hook	git commit	smoke + unit (módulos modificados)	sim
re-push hook	git push	unit + functional + integration + ui + regression + a11y + i18n (módulos modificados)	sim
I on PR	abertura/atualização de PR	tudo de pre~~push + flow (host~~only) + api + rules + security (SAST) + compat (matriz mínima)	sim
I on merge to master	merge para `main`/`master`	tudo de PR + perf benchmark (compara com baseline)	só `> +5 %` regression
ightly	02:00 UTC daily	tudo de master + stress + soak + chaos + fuzz + mutation + flow `@requires-device`	abre ticket; não bloqueia
elease tag	tag `<area>/<module>/v*`	tudo + golden diffs + APK signature checks + install/upgrade real	sim — não publica release

3. Quando rodar cada categoria

unit · functional · regression · smoke

*empre*que código for tocado. Roda em pre-commit. Tempo total deve ficar * 30 s*mesmo em monorepo (parallelizado por módulo). Se ultrapassar, dividir em "fast" e "slow" via tags.

Pre-push. Aceita até 2 minutos. Falha ainda bloqueia.

flow

Variantes:

Host-only — pre-push (sem device, ~ 3 min)
@requires-device — nightly em emulator harness; opt-in via
flutter test integration_test/ localmente

api · rules

PR. Contract tests precisam de provider rodando — usar mock-depot (tests/e2e/lib/mock-depot/) para testes hub-side; CDC verifica contra o mock + provider real em nightly.

security

SAST — pre-push (Semgrep + govulncheck)
DAST — nightly contra ambiente staging
SCA — toda PR (Dependabot)
Pen test manual — uma vez por release tag (processo, não
comando)

performance

PR. Compara com baseline em master. > +5 % slower = bloqueia merge a menos que a label expected-perf-regression esteja no PR.

stress

Nightly. Cenários típicos: pico 10x SLA por 10 min. Falha abre ticket no backlog do módulo.

soak (durability/endurance)

*eekend run*(sexta~~feira 18:00 → segunda~~feira 06:00). Cobre 60 h de carga normal. Métricas registradas:

RSS ao longo do tempo (vazamento detectado se slope positivo
após 8 h)
Latência p99 (drift > 20 % em 24 h = ticket)
GC pause time / GC pressure
Open file descriptors / connection pool size

chaos

Nightly em ambiente de staging dedicado. NUNCA em produção sem plano explícito (não temos chaos contínuo em prod ainda — está no backlog #infradatakdb-vector#073).

fuzz

Nightly + on~~demand quando bug de input~~malformed aparecer (cria corpus a partir do input que disparou).

mutation

Weekly (domingo 22:00). Score-target por componente:

SDK: ≥ 80 %
engine: ≥ 75 %
backend: ≥ 70 %
app: ≥ 60 % (UI tem mutações pouco-úteis)

compat

PR (matriz mínima: latest Chrome + latest Firefox + Android 14 + iOS 17). Nightly: matriz completa.

install

Release tag — verifica que o pacote real instala em VM limpa.

usability

Pre-release (uma vez por sprint). Roteiros são manuais hoje; agregação em docs/tests/usability/<module>.md.

4. Política de flakes

Definição

Teste é *laky*quando produz resultados diferentes para o *esmo*input. Detectado quando:

Mesma SHA passa numa run, falha na próxima
Re-run sem mudança vira o resultado
Test runner reporta --retry 1 PASS (passou só na 2ª)

Resposta

*mediato* marcar @flaky no header do teste e abrir
ticket <module>/backlog/pending/NNN-flaky-<test-name>.md.
*4 h* ticket priorizado no próximo standup.
* dias* se não resolvido, teste *emovido*do gate
(ainda roda mas não bloqueia) com link para o ticket.
*0 dias* se ainda flaky, teste *eletado*ou
reescrito do zero.

Nunca: ignorar silenciosamente, comentar // TODO, ou adicionar --retry.

5. Política de skips

Skip é admitido só com:

*ustificativa em texto livre*em koder.toml [testing.justification].
*icket de revisão*com prazo (default 30 dias) em
<module>/backlog/pending/.
*arker no header*do arquivo skipado (se for arquivo
inteiro).

Skips não justificados aparecem como WARN no /k-housekeep e viram ERROR após 30 dias.

6. Política de testes longos

Tempo	Política
< 1 s	Pode ficar em pre-commit
1-10 s	Pre-commit OK; vigiar
10-60 s	Pre-push
1-10 min	PR; tag `@slow`
10-60 min	Nightly
> 1 h	Weekend / on-demand

Migrar de tier mais longo para mais curto via paralelização, fakes, fixtures menores, ou separação de "smoke" (1 caso) + "full" (matriz).

7. Tooling de gate

CI failure exige:

Mensagem failed-category=<slug> no log
Link para o ticket-template apropriado em
docs/tests/templates/
Dispatch automático para o canal #hub-quality (Slack/Talk)
quando flow ou regression falham em master

8. Auditoria periódica

/k-housekeep Fase Y, weekly:

Para cada módulo, compara categorias presentes vs
coverage-matrix.md
Detecta @flaky markers > 7 dias sem ticket
Detecta skips > 30 dias sem revisão
Mede mutation score e compara com target

9. Ownership

*ada test owner*(autor original) é responsável por mantê-lo
verde. Marcado em git blame + koder.manifest.json (owner: "<github-handle>").
*em owner*→ SDK lead (cross-cutting) ou tech lead do
Domínio (RFC-003).

10. Não-objetivos

Esta policy *ão cobre*

Code coverage (% de linhas cobertas) — orientação solta:

60 % é sinal de cuidado; > 90 % é frequentemente

contraproducente. Mutation score é a métrica mais fidedigna.
Strategy de teste de produtos B2B com clientes externos —
cabe à equipe comercial.
Performance budgeting na UI (FCPLCPTTI) — vive em
policies/web-perf.kmd quando criada (não existe ainda).