# Quickstart & Validation Guide: Article Content Multi-Engine Extractor

Este guia descreve os passos para executar, testar e validar o extrator multimotor de artigos de notícias.

---

## 1. Pré-requisitos

Certifique-se de que as dependências necessárias estão instaladas no ambiente Python:

```bash
pip install foxcape trafilatura newspaper4k readability-lxml beautifulsoup4 lxml pytest
```

---

## 2. Cenários de Validação

### Cenário 1: Extração com Amostragem Rápida (Limit 2)
Testa o fluxo completo ponta a ponta com apenas 2 notícias para validação imediata:

```bash
python scripts/extract_article_contents.py -i out/river_plate.json --limit 2
```

**Resultado esperado:**
- Logs informativos no `stderr` indicando o progresso `[1/2]` e `[2/2]`.
- Arquivo `out/river_plate_extracted.json` gerado automaticamente.
- O JSON contém 2 artigos com os nós `trafilatura`, `newspaper4k` e `readability` populados.

---

### Cenário 2: Caminho Customizado de Saída
Testa a especificação explícita do arquivo de saída:

```bash
python scripts/extract_article_contents.py -i out/river_plate.json -o out/custom_test.json --limit 1
```

**Resultado esperado:**
- Arquivo `out/custom_test.json` criado com 1 artigo extraído com sucesso.

---

### Cenário 3: Modo Silencioso (`--silent`)
Testa a supressão de logs para integração em automações/pipes:

```bash
python scripts/extract_article_contents.py -i out/river_plate.json --limit 1 --silent
```

**Resultado esperado:**
- Nenhuma saída de log impressa no terminal.
- Código de saída 0 retornado.

---

### Cenário 4: Resiliência contra URLs Inválidas
Testa como o sistema lida com falhas pontuais de conexão ou páginas offline sem quebrar o lote:

```bash
# Executa contra fixture de teste contendo URLs inexistentes
pytest tests/test_extract_article_contents.py -k "test_resilience_on_failed_url"
```

**Resultado esperado:**
- O teste passa confirmando que o artigo com erro recebeu `extraction_status: "failed"` e os demais concluíram com sucesso.

---

## 3. Validação Automatizada de Testes

Executar a suíte de testes unitários e de integração:

```bash
pytest tests/test_extract_article_contents.py -v
```