Saltar al contenido principal

📚 Guia: Histórico Versionado de Test Runs

Criado: 27 fev 2026
Versão: 1.0
Autor: Sistema de Gestão de Testes E2E

🎯 Visão Geral​

O sistema de histórico versionado permite:

  • ✅ Nunca sobrescrever artefactos de execuções anteriores
  • ✅ Comparar duas execuções lado-a-lado
  • ✅ Arquivar/restaurar execuções antigas
  • ✅ Gerir storage automaticamente com políticas configuráveis
  • ✅ Rastrear cada execução com metadata completa

🏗️ Estrutura de Armazenamento​

Diretório de Runs Versionadas​

frontend/test-results/runs/
├── 2026-02-27_13-15-22_login_passed_a1b2c3d/
│   ├── screenshots/
│   │   ├── login-01-page-loaded.png
│   │   ├── login-02-form-filled.png
│   │   └── login-03-success.png
│   ├── videos/
│   │   ├── login-sucesso.webm
│   │   └── login-erro.webm
│   └── metadata.json
├── 2026-02-27_12-30-45_login_failed_5d6e7f8/
└── .archived/  (runs arquivadas)
    └── 2026-02-26_10-00-00_login_passed_9g0h1i2/

Convenção de Naming​

Formato: {YYYY-MM-DD}_{HH-MM-SS}_{suite}_{status}_{hash}/

Exemplo: 2026-02-27_13-15-22_login_passed_a1b2c3d/

Componentes:

  • Data/Hora: Timestamp humanamente legível
  • Suite: Nome da suite de testes (login, locations, etc.)
  • Status: passed | failed | running
  • Hash: 7 caracteres únicos (sha256 da run_id)

🖥️ Interface do Utilizador​

1. Painel de Histórico Versionado​

Localização: Centro de Testes E2E → Tab "Visão Geral" → Painel superior

Funcionalidades:

  • Ver todas as execuções da suite selecionada
  • Toggle "Mostrar arquivadas" para incluir runs antigas
  • Ver metadata: timestamp, run_id, tamanho storage, status
  • Ações por run:
    • Esquerda/Direita: Selecionar para comparação
    • Arquivar/Restaurar: Soft delete reversível

Exemplo de entrada:

27 fev 13:15:22 · a1b2c3d
45.23 MB · Ativa
[Esquerda] [Direita] [Arquivar]

2. Comparação Lado-a-Lado​

Localização: Centro de Testes E2E → Tab "Visão Geral" → Painel "Comparação"

Como usar:

  1. Selecionar Run Esquerda no dropdown
  2. Selecionar Run Direita no dropdown
  3. Sistema carrega automaticamente:
    • Primeiro screenshot de cada run
    • Primeiro vídeo de cada run
  4. Comparar visualmente diferenças

Use cases:

  • Comparar execução que passou vs. que falhou
  • Verificar regressões visuais
  • Auditar mudanças de comportamento

3. Política de Retenção​

Localização: Centro de Testes E2E → Tab "Visão Geral" → Painel "Política de Retenção"

Configurações disponíveis:

Estratégia de Limpeza​

  • runs: Guardar apenas últimas N execuções
  • days: Guardar execuções dos últimos N dias
  • both: Aplicar ambos os limites (mais restritivo)

Limites​

  • Máx. execuções: Quantas runs manter (padrão: 50)
  • Máx. dias: Quantos dias manter (padrão: 30)
  • Limpeza ativa: Toggle ON/OFF para cleanup automático

Ações​

  • Guardar política: Persistir alterações
  • Executar limpeza agora: Trigger manual (não aguardar scheduler)

Exemplo de configuração conservadora:

Estratégia: both
Máx. execuções: 100
Máx. dias: 60
Limpeza ativa: ON

Exemplo de configuração agressiva:

Estratégia: runs
Máx. execuções: 20
Máx. dias: 7
Limpeza ativa: ON

🔧 Backend Configuration​

Variáveis de Ambiente (.env)​

# Storage Policy
TEST_STORAGE_CLEANUP_ENABLED=true
TEST_STORAGE_STRATEGY=both              # runs | days | both
TEST_STORAGE_MAX_RUNS=50
TEST_STORAGE_MAX_DAYS=30

Base de Dados​

Tabelas​

test_run_history

  • Metadata de cada execução versionada
  • run_id, run_hash, suite, status, timestamp
  • run_path (diretório físico)
  • storage_size_mb, duration_seconds
  • is_archived (soft delete flag)

test_artifacts

  • Lista de artefactos por run
  • run_id (FK), type (screenshot/video), relative_path

storage_policies

  • Configuração persistida de retenção
  • max_runs, max_days, strategy, cleanup_enabled

🚀 API Endpoints​

Histórico​

GET /api/testing/runs/history
    ?limit=50
    &include_archived=false

GET /api/testing/runs/history/{run_id}

GET /api/testing/runs/history/{run_id}/artifacts

Arquivo/Restauro​

POST /api/testing/runs/history/{run_id}/archive
POST /api/testing/runs/history/{run_id}/restore

Storage Policy​

GET  /api/testing/storage/policy
PUT  /api/testing/storage/policy
POST /api/testing/storage/cleanup

🔒 Segurança & Reliability​

Soft Delete​

  • Arquivar uma run não elimina dados
  • Marca is_archived = true na BD
  • Move diretório físico para .archived/
  • Pode ser restaurado a qualquer momento

Thread Safety​

  • Worker que faz snapshot usa sessão DB dedicada
  • Evita race conditions em snapshot paralelo

Compatibilidade​

  • Endpoint legacy /api/testing/generate-videos mantido
  • Frontend detecta execuções antigas e faz fallback
  • Coexistência com tabela test_runs original

📊 Fluxo de Execução Completo​

1. User clica "Executar testes"
   ↓
2. Backend cria run_id único
   ↓
3. Playwright executa suite
   ↓
4. Artefactos salvos em frontend/test-results/ (temporário)
   ↓
5. Ao terminar run:
   a) Criar diretório versionado com naming convention
   b) Snapshot: copiar artefactos → diretório versionado
   c) Salvar metadata na BD (test_run_history + test_artifacts)
   d) Aplicar política de retenção (arquivar runs antigas)
   ↓
6. UI atualiza lista de histórico automaticamente

🐛 Troubleshooting​

Problema: Artefactos não aparecem no histórico​

Diagnóstico:

# Verificar se diretórios existem
ls -la frontend/test-results/runs/

# Verificar runs na BD
SELECT run_id, suite, status, run_path FROM test_run_history ORDER BY started_at DESC LIMIT 10;

Soluções:

  • Verificar se backend tem permissões de escrita em test-results/
  • Verificar logs do backend para erros de snapshot
  • Confirmar que TEST_STORAGE_CLEANUP_ENABLED não está a arquivar tudo imediatamente

Problema: Storage a crescer muito rapidamente​

Diagnóstico:

# Ver tamanho de cada run
du -sh frontend/test-results/runs/*/ | sort -h

# Ver total de storage usado
du -sh frontend/test-results/runs/

Soluções:

  • Reduzir TEST_STORAGE_MAX_RUNS (ex: 20 em vez de 50)
  • Reduzir TEST_STORAGE_MAX_DAYS (ex: 7 em vez de 30)
  • Executar cleanup manual: UI → "Executar limpeza agora"
  • Considerar comprimir vídeos (ffmpeg)

Problema: Comparação mostra runs vazias​

Diagnóstico:

  • Verificar se run_id selecionado existe
  • Verificar se diretório da run tem artefactos

Soluções:

  • Recarregar página (F5)
  • Verificar console do browser para erros de fetch
  • Confirmar que backend está a correr

📈 Melhores Práticas​

Para Developers​

  1. Sempre verificar artifacts antes de commit:

    • Não fazer commit de test-results/runs/* no git
    • Adicionar ao .gitignore se necessário

  2. Testar políticas de retenção localmente:

    • Criar várias runs dummy
    • Ajustar max_runs=5 temporariamente
    • Verificar se cleanup funciona

  3. Usar comparação para regressions:

    • Guardar screenshots "golden" de run que passou
    • Comparar novas runs com golden
    • Facilita detecção de mudanças visuais

Para QA​

  1. Documentar runs importantes:

    • Anotar run_id de bugs encontrados
    • Evitar arquivar runs com evidências de bugs
    • Partilhar run_id com developers

  2. Validar comparações:

    • Sempre comparar passed vs failed para mesmo cenário
    • Screenshots devem estar na mesma sequência
    • Vídeos devem ter timestamp visível

Para DevOps​

  1. Monitoring de storage:

    • Alertar se test-results/ > 1GB
    • Limpar .archived/ periodicamente (ex: 90 dias)

  2. Backup de runs críticas:

    • Fazer backup externo de runs de produção
    • Guardar evidências de incidentes

🎓 Exemplos de Uso​

Exemplo 1: Investigar falha intermitente​

# Cenário: Login falha às vezes, mas não sempre

1. Visão Geral → Histórico Versionado
2. Encontrar runs recentes: algumas passed, algumas failed
3. Selecionar run PASSED no dropdown Esquerda
4. Selecionar run FAILED no dropdown Direita
5. Comparação Lado-a-Lado → Ver screenshots
6. Identificar diferença visual (ex: loading spinner ainda visível)
7. Conclusão: Race condition no timing

Exemplo 2: Verificar impacto de mudança CSS​

# Cenário: Alterou cor de botão, quer confirmar visualmente

1. Executar testes ANTES da mudança → run_id: abc123d
2. Aplicar mudança CSS (commit)
3. Executar testes DEPOIS da mudança → run_id: def456e
4. Comparação: abc123d vs def456e
5. Screenshots mostram botão verde → azul ✅

Exemplo 3: Limpar storage para CI/CD​

# Cenário: CI está a ficar sem espaço

1. Política de Retenção → Estratégia: "runs"
2. Máx. execuções: 10 (CI não precisa guardar muito)
3. Limpeza ativa: ON
4. Guardar política
5. Executar limpeza agora
6. Mensagem: "Limpeza concluída. Execuções arquivadas: 35"

📚 Referências​

  • Plano técnico: /PLANO-TEST-RUNS-VERSIONAMENTO.md
  • Código backend: /backend/src/modules/testing/
  • Código frontend: /frontend/src/pages/admin/testing/TestingCenterPage.tsx
  • Commits relevantes:
    • 47be520: Fase 1 (Models)
    • c582674: Fase 2 (Services)
    • 0bad672: Fase 3 (API)
    • 26e9bcf: Fase 4 (Frontend inicial)
    • 8b31bf1: Fase 5 (UI completa)

Última atualização: 27 fev 2026
Versão: 1.0
Status: ✅ Production Ready

Última actualización en por CI Governance Bot