gart/code/Engine/docs/04_TESTS_AND_WORKFLOW.md

04 — Testes, Fluxo de Trabalho e Estado Atual

1. Suíte de testes

1032 testes em 24 arquivos em tests/. Rode com uv run pytest tests/ -v.

Arquivo	Cobre
test_models.py	TimeValue (aritmética), Timecode, propriedades de Clip, modelos de validação, helpers de Timeline
test_writer.py	insert_clip, add_marker (todos os tipos), trim_clip, delete_clip, split_clip, change_speed
test_server.py	handlers MCP, parser, dispatch
test_rough_cut.py	RoughCutGenerator
test_features_v05.py	connected clips, roles, timeline diff, reformat, silêncio, export, compatibilidade
test_features_v06.py	features da v0.6
test_marker_pipeline.py	build_marker_element, batch auto-modes, índices de clip duplicados, write_fcpxml
test_refactored_helpers.py	_index_elements, _iter_spine_clips, _find_spine_clip_at_seconds, _resolve_clip_duration, _make_asset_clip, _format_batch_result, serialize_xml
test_transcribe.py	spans de frase/filler, álgebra de merge/invert de intervalos, degradação do Whisper, handlers por transcrição
test_media_intel.py	parse de silencedetect, mapeamento source→timeline, bounds de parâmetros, integração WAV real (skips sem ffmpeg)
test_diff.py	comparação de timelines
test_export.py	export Resolve / FCP7
test_live.py	modo live
test_security.py	segurança de path / XML
test_edge_cases.py, test_diversity.py, test_parser.py, test_validation.py, test_bundles.py, test_dtd_validation.py, test_relink.py, test_speed_cutting.py, test_targeted_gaps.py, test_fcpxml_writer.py	demais suítes

Fixtures: examples/sample.fcpxml + fixtures XML inline. NOTA: sample.fcpxml NÃO é DTD-conformante (assets pré-media-rep, markers de capítulo no sequence) — não o use como fixture de validade DTD. Testes criam arquivos temporários e limpam.

Obs. transcribe/media: testes exigem deps opcionais (ffmpeg, whisper). Sem eles, os testes relevantes fazem skip — o CI instala.

2. Fluxo de trabalho padrão (obrigatório)

Regra do sistema: sempre após concluir UMA correção de código, o sistema é automaticamente executado/validado.

./Engine/run_after_fix.sh

O que ele faz (e falha via set -e se qualquer um não passar):

1. uv run ruff check . --exclude docs/ → zero erros de lint.
2. uv run pytest tests/ -v → toda a suíte passa.

Equivalente manual (pre-commit)

ruff check . --exclude docs/   # lint — zero erros
pytest tests/ -v               # testes — todos passam

O CI roda ambos em todo push para main. Se um falhar, o commit ganha X no GitHub. Corrija o lint antes de commitar.

3. Como rodar a aplicação

uv run server.py                        # Inicia o servidor MCP (stdio)
uv run python admin/models_gui.py       # UI desktop de gestão de modelos (Flet)
uv run --extra dev pytest tests/ -v     # Testes com extra de dev

4. Estado atual do sistema (resumo "até agora")

• v0.6.35 — núcleo FCPXML completo em Python (fcpxml/).
• 62 ferramentas MCP em server.py, organizadas por dispatch TOOL_HANDLERS.
• Suporte FCPXML 1.8–1.14 (.fcpxml e bundles .fcpxmld com sidecars), escrita padrão 1.13.
• Dual-mode: XML (principal) + Live (push_to_fcp / list_fcp_libraries via Apple events).
• Inteligência de mídia (v0.10): silêncio via ffmpeg + beats via librosa (lazy).
• Transcrição local Whisper + gestão de modelos (model_manager.py, catálogo models.json, cache HF, cancelamento de download).
• UI desktop (Flet): admin/models_gui.py — aba Modelos (download/selecionar/ remover/config pasta de modelos) e aba Transcrição (projeto FCPXML → transcrição).
• API complementar: admin/models_api.py.
• Validação DTD: contra DTDs oficiais do bundle do FCP (v0.10+).
• Export cross-NLE: DaVinci Resolve v1.9 + FCP7 XMEML v5.

5. Evolução prevista (roadmaps)

• docs/CAPABILITY-AUDIT-2026-06.md — auditoria do ecossistema + roadmap dual-mode.
• docs/specs/06_IMPLEMENTATION_ROADMAP.md — roadmap de implementação.
• docs/TRANSCRIPTION-MODELS.md — fases da gestão de modelos (MCP handlers e wiring em transcribe() vêm em fase posterior; hoje model_manager.py é o esqueleto com catálogo e primitivas de cache reais).