andreferraro
6a45368cb0
- Added scripts/extract_article_contents.py for batch scraping with stealth Foxcape and triple extraction (Trafilatura, Newspaper4k, Readability) - Created unit, integration, and E2E test suite in tests/test_extract_article_contents.py (90/90 passing) - Updated specs/003-article-content-extractor and README.md with usage documentation and CLI contracts - Passed ruff linting/formatting and mypy type checking cleanly
78 lines
2.2 KiB
Markdown
78 lines
2.2 KiB
Markdown
# 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
|
|
```
|