feat(extractor): implement multi-engine article content extractor
- 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
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user