# Quickstart: Google News Headlines Extractor

Guia rápido para execução e validação de ponta a ponta do extrator de notícias via linha de comando.

---

## 1. Pré-requisitos e Instalação

Instale as dependências necessárias no ambiente Python:
```bash
pip install -r requirements.txt
```

Baixe os binários de browser stealth do Camoufox (executado uma única vez):
```bash
python -m camoufox fetch
```

---

## 2. Cenários Práticos de Uso

### Cenário 1: River Plate — Argentina (Espanhol / 2 Páginas / Salvar em Arquivo)
```bash
python scripts/extract_google_news.py -q "River Plate" -l es --locale AR -p 2 -o out/river_plate.json
```
* **Logs no terminal**:
  ```text
  [INFO] 🔍 Consultando Google News: 'River Plate' (idioma: es, locale: AR, max_pages: 2)...
  [INFO] 📥 Feed RSS recebido (162117 bytes).
  [INFO] 📰 20 artigos extraídos do feed XML.
  [INFO] 🔗 Decodificando 20 URLs do Google News para os portais reais...
  [INFO] ✅ 20/20 URLs resolvidas com sucesso para os domínios de origem.
  [INFO] 💾 Arquivo salvo com sucesso: 'out/river_plate.json' (20 notícias).
  ```

---

### Cenário 2: Cruzeiro — Brasil (Português / Formatado no Terminal)
```bash
python scripts/extract_google_news.py --query "Cruzeiro" --lang pt --locale BR --pretty
```
* Retorna JSON formatado com 10 manchetes e links diretos (*ge.globo.com, lance.com.br, gazetaesportiva.com*).

---

### Cenário 3: Fórmula 1 — Reino Unido (Inglês)
```bash
python scripts/extract_google_news.py --query "Formula 1" --lang en --locale GB --pretty
```
* Retorna notícias de veículos britânicos (*BBC Sport, Sky Sports F1, Autosport*).

---

### Cenário 4: Integração em Pipeline com `jq` (Modo Silencioso)
```bash
python scripts/extract_google_news.py -q "inteligência artificial" -s | jq '.items[].url'
```

---

### Cenário 5: Extração Rápida com Links Brutos (Sem Resolução de URLs)
```bash
python scripts/extract_google_news.py -q "São Paulo" --no-resolve-urls --pretty
```

---

## 3. Validação dos Testes Automatizados e Linter

```bash
# Executa todos os testes unitários e E2E ao vivo
pytest tests/test_extract_google_news.py -v

# Validação estática com Ruff e Mypy
ruff check scripts/extract_google_news.py tests/test_extract_google_news.py
mypy scripts/ tests/test_extract_google_news.py
```