Initial commit: navegator - Chrome CDP automation for LLMs

Add complete navegator system for stealthy browser automation: - CDP client with WebSocket communication - Browser API with navigation, storage, network, runtime - Stealth flags and anti-detection scripts - Persistent profile support - Examples and comprehensive documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-03-24 23:33:07 +01:00
commit 3253828fef
36 changed files with 8116 additions and 0 deletions
@@ -0,0 +1,557 @@
+# Testing Guide - Navegator
+
+Sistema completo de testing E2E para validar que los binarios funcionan correctamente.
+
+---
+
+## 🎯 Tipos de Tests
+
+### 1. **Tests Unitarios** (Go)
+Tests de funciones individuales en Go.
+
+```bash
+# Ejecutar todos los tests unitarios
+make test-unit
+
+# O directamente con go test
+go test -v ./pkg/browser/...
+go test -v ./pkg/cdp/...
+go test -v ./pkg/stealth/...
+```
+
+**Cobertura:**
+- ✅ Launch browser
+- ✅ Navigate
+- ✅ Screenshot
+- ✅ JavaScript evaluation
+- ✅ Stealth flags
+- ✅ Recorder
+- ✅ Profile persistence
+
+### 2. **Tests E2E** (Bash)
+Tests de binarios compilados end-to-end.
+
+```bash
+# Ejecutar tests E2E
+make test-e2e
+
+# O directamente
+./test/e2e_test.sh
+```
+
+**Cobertura:**
+- ✅ Screenshot básico y con opciones
+- ✅ Búsqueda (con timeout esperado)
+- ✅ Navegación y recording
+- ✅ Perfiles personalizados
+- ✅ Persistencia de perfiles
+- ✅ Error handling
+
+### 3. **Tests de Integración** (Bash)
+Tests de integración entre componentes.
+
+```bash
+# Ejecutar tests de integración
+make test-integration
+
+# O directamente
+./test/integration_test.sh
+```
+
+**Cobertura:**
+- ✅ Compartir perfiles entre binarios
+- ✅ Recording de múltiples acciones
+- ✅ Perfiles en paralelo (clonados)
+- ✅ Output JSON válido
+
+---
+
+## 🚀 Quick Start
+
+### Ejecutar todos los tests
+```bash
+make test
+```
+
+### Tests rápidos (solo unitarios)
+```bash
+make test-quick
+```
+
+### Solo E2E
+```bash
+make build
+make test-e2e
+```
+
+---
+
+## 📊 Estructura de Tests
+
+```
+navegator/
+├── pkg/
+│   └── browser/
+│       └── browser_test.go        # Tests unitarios
+├── test/
+│   ├── e2e_test.sh                # Tests E2E de binarios
+│   └── integration_test.sh        # Tests de integración
+├── Makefile                        # Comandos de testing
+└── .github/
+    └── workflows/
+        └── test.yml                # CI/CD automático
+```
+
+---
+
+## 🧪 Tests Unitarios Detallados
+
+### TestLaunchBrowser
+Verifica que el navegador se lance correctamente.
+
+```go
+func TestLaunchBrowser(t *testing.T) {
+    // Lanza Chrome con perfil temporal
+    // Verifica: perfil creado, debug URL, target ID
+}
+```
+
+### TestNavigate
+Verifica navegación a URLs.
+
+```go
+func TestNavigate(t *testing.T) {
+    // Navega a example.com
+    // Verifica URL correcta via JavaScript
+}
+```
+
+### TestScreenshot
+Verifica capturas de pantalla.
+
+```go
+func TestScreenshot(t *testing.T) {
+    // Toma screenshot
+    // Verifica: PNG válido, tamaño > 0
+}
+```
+
+### TestStealthFlags
+Verifica flags anti-detección.
+
+```go
+func TestStealthFlags(t *testing.T) {
+    // Evalúa navigator.webdriver
+    // Verifica: false o undefined
+    // Verifica: window.chrome existe
+}
+```
+
+---
+
+## 🎯 Tests E2E Detallados
+
+### Suite: screenshot
+
+**Test 1: Captura básica**
+```bash
+./screenshot -url https://example.com -o test.png
+# Verifica: PNG válido, archivo existe
+```
+
+**Test 2: Perfil personalizado**
+```bash
+./screenshot -profile custom-123 -url https://example.com
+# Verifica: perfil creado en disco
+```
+
+**Test 3: Dimensiones custom**
+```bash
+./screenshot -width=800 -height=600 -url https://example.com
+# Verifica: screenshot generado
+```
+
+### Suite: buscar
+
+**Test 4: Búsqueda básica**
+```bash
+./buscar -q "test" -n 3 -output results.json
+# Verifica: no crash (puede tener timeout de red)
+```
+
+**Test 5: Perfil personalizado**
+```bash
+./buscar -profile test-search -q "query"
+# Verifica: perfil creado
+```
+
+### Suite: navegar
+
+**Test 6: Navegación básica**
+```bash
+./navegar -url https://example.com -duration 2
+# Verifica: recording creado
+```
+
+**Test 7: Recording funciona**
+```bash
+# Verifica contenido del recording log
+grep "Navigate" recording_*.log
+```
+
+### Suite: Perfiles
+
+**Test 8: Persistencia**
+```bash
+# Primera sesión: crea perfil
+./screenshot -profile persist-test -url https://example.com
+
+# Segunda sesión: reutiliza
+./screenshot -profile persist-test -url https://example.com
+
+# Verifica: perfil existe después de ambas
+```
+
+**Test 9: Múltiples perfiles**
+```bash
+# Crear múltiples perfiles en paralelo
+./screenshot -profile multi-1 &
+./screenshot -profile multi-2 &
+wait
+
+# Verifica: ambos existen
+```
+
+---
+
+## 🔗 Tests de Integración Detallados
+
+### Test 1: Compartir perfil entre binarios
+```bash
+# navegar crea sesión
+./navegar -url https://example.com -profile shared
+
+# screenshot usa misma sesión
+./screenshot -url https://example.com -profile shared
+
+# Verifica: mismo perfil usado
+```
+
+### Test 2: Recording de múltiples acciones
+```bash
+./navegar -url https://example.com -duration 3
+
+# Verifica: recording contiene JSON válido con acciones
+```
+
+### Test 3: Perfiles clonados en paralelo
+```bash
+# Clonar perfil base
+cp -r base clone1
+cp -r base clone2
+
+# Ejecutar en paralelo
+./screenshot -profile clone1 &
+./screenshot -profile clone2 &
+
+# Verifica: ambos completan sin error
+```
+
+---
+
+## 📈 Cobertura de Código
+
+### Generar reporte
+```bash
+make coverage
+```
+
+Genera `coverage.html` con visualización de cobertura.
+
+### Ver cobertura en terminal
+```bash
+go test -cover ./pkg/...
+```
+
+### Cobertura por paquete
+```bash
+go test -coverprofile=coverage.out ./pkg/browser
+go tool cover -func=coverage.out
+```
+
+---
+
+## 🔄 CI/CD Automático
+
+### GitHub Actions
+
+El workflow `.github/workflows/test.yml` ejecuta automáticamente:
+
+1. **Unit Tests** - En cada push/PR
+2. **E2E Tests** - Con Chrome instalado
+3. **Integration Tests** - Verificación completa
+4. **Lint** - Análisis de código
+
+### Configuración
+
+```yaml
+on:
+  push:
+    branches: [ main, master, develop ]
+  pull_request:
+    branches: [ main, master ]
+```
+
+### Ver resultados
+
+En GitHub: **Actions** tab → Ver runs → Detalles de cada job
+
+---
+
+## 🐛 Debugging Tests Fallidos
+
+### Test unitario falla
+
+```bash
+# Ejecutar con verbose
+go test -v ./pkg/browser/ -run TestName
+
+# Ver logs completos
+go test -v ./pkg/browser/ 2>&1 | tee test.log
+```
+
+### Test E2E falla
+
+```bash
+# Ejecutar directamente sin make
+./test/e2e_test.sh
+
+# Ver archivos generados
+ls -la *.png *.json test-profiles/
+```
+
+### Chrome no se inicia
+
+```bash
+# Verificar Chrome instalado
+which google-chrome
+
+# Probar manualmente
+google-chrome --version
+
+# Ver si hay procesos colgados
+ps aux | grep chrome
+pkill -9 chrome
+```
+
+### Timeout en búsquedas
+
+Las búsquedas en DuckDuckGo pueden tardar. Esto es **esperado** y el test lo marca como `SKIP`.
+
+```bash
+# Test marcado como SKIP por timeout de red
+# Esto NO es un fallo del binario
+```
+
+---
+
+## 🎭 Tests de Regresión
+
+### Crear baseline
+
+```bash
+# Capturar estado actual
+make test > baseline.txt
+```
+
+### Comparar con baseline
+
+```bash
+# Ejecutar tests nuevamente
+make test > current.txt
+
+# Comparar
+diff baseline.txt current.txt
+```
+
+---
+
+## 📝 Escribir Nuevos Tests
+
+### Test unitario
+
+1. Crear archivo `*_test.go` en el paquete
+2. Función con prefijo `Test`
+3. Usar `t.TempDir()` para archivos temporales
+
+```go
+func TestMyFeature(t *testing.T) {
+    tempDir := t.TempDir()
+
+    // Tu código aquí
+
+    if resultado != esperado {
+        t.Errorf("Expected %v, got %v", esperado, resultado)
+    }
+}
+```
+
+### Test E2E
+
+Agregar a `test/e2e_test.sh`:
+
+```bash
+TEST_NAME="mi-feature: descripción"
+if ./mi-binario -arg valor; then
+    if [ condición ]; then
+        report_test "$TEST_NAME" "PASS"
+    else
+        report_test "$TEST_NAME" "FAIL" "Razón"
+    fi
+else
+    report_test "$TEST_NAME" "FAIL" "Error ejecución"
+fi
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### "Chrome crashed" o "Can't find Chrome"
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install google-chrome-stable
+
+# Verificar instalación
+google-chrome --version
+```
+
+### "Permission denied" en scripts
+
+```bash
+chmod +x test/*.sh
+chmod +x scripts/*.sh
+```
+
+### Tests pasan localmente pero fallan en CI
+
+```bash
+# Puede ser dependencia de Chrome
+# Verificar que Chrome se instala en CI (ver .github/workflows/test.yml)
+
+# O diferencias de timezone/locale
+export TZ=UTC
+export LANG=en_US.UTF-8
+```
+
+### Perfiles de test llenan disco
+
+```bash
+# Limpiar automáticamente
+make clean
+
+# O manualmente
+rm -rf test-profiles/
+rm -rf ~/.navegator/profiles/test-*
+```
+
+---
+
+## 📊 Métricas de Calidad
+
+### Objetivos
+
+- ✅ **Cobertura de código**: >70%
+- ✅ **Tests E2E**: >10 tests
+- ✅ **Tiempo de ejecución**: <5 minutos
+- ✅ **Pass rate**: >90%
+
+### Monitorear
+
+```bash
+# Tiempo de ejecución
+time make test
+
+# Cobertura
+make coverage
+# Ver coverage.html
+
+# Pass rate
+make test | grep "Pass rate"
+```
+
+---
+
+## 🔧 Comandos Útiles
+
+```bash
+# Ejecutar todo
+make test
+
+# Solo tests rápidos
+make test-quick
+
+# Solo E2E
+make test-e2e
+
+# Solo integración
+make test-integration
+
+# Con cobertura
+make coverage
+
+# Limpiar todo
+make clean
+
+# Ver ayuda
+make help
+```
+
+---
+
+## 📚 Recursos
+
+- **Go Testing**: https://go.dev/doc/tutorial/add-a-test
+- **Table-driven tests**: https://go.dev/wiki/TableDrivenTests
+- **CI/CD con GitHub Actions**: https://docs.github.com/actions
+
+---
+
+## ✅ Checklist Pre-Commit
+
+Antes de hacer commit, ejecutar:
+
+```bash
+□ make fmt          # Formatear código
+□ make lint         # Verificar código
+□ make test-quick   # Tests rápidos
+□ make test         # Tests completos (si hay tiempo)
+```
+
+Antes de hacer PR:
+
+```bash
+□ make test         # Todos los tests
+□ make coverage     # Verificar cobertura
+□ Revisar CI/CD     # Ver que pase en GitHub Actions
+```
+
+---
+
+## 🎯 Conclusión
+
+Con este sistema de testing puedes:
+
+✅ Verificar que los binarios funcionan correctamente
+✅ Detectar regresiones automáticamente
+✅ Validar cambios antes de deploy
+✅ Mantener calidad de código alta
+✅ CI/CD automático en cada push
+
+**Comando más importante:**
+```bash
+make test
+```
+
+Ejecuta todo: unitarios, E2E, integración. Si pasa, el código está listo.