Tests End to End con IA usando Stagehand

En esta clase subimos el nivel: pasamos de tests E2E “a mano” (buscando selectores y simulando clics de forma muy determinista) a tests E2E con IA, donde describimos lo que queremos en lenguaje natural y el sistema interactúa con la web como lo haría un usuario real.

La idea es simple: si le decimos “compra dos entradas y dime el subtotal”, esperamos que un usuario también entienda la interfaz. Y si la IA se pierde, probablemente tu UX también tiene algo que decirte.

¿Qué significa “E2E con IA”?

Hasta ahora, el enfoque clásico es:

Inspeccionar el HTML
Encontrar selectores exactos
Automatizar pasos como si fuéramos un “programador agarrándole la mano al usuario”

Con IA, cambiamos el paradigma:

Describimos acciones en lenguaje natural: “haz clic en comprar entradas”
Pedimos extracción de información: “extrae el subtotal”
El test se parece más a cómo navega alguien que no sabe tu DOM de memoria

La librería: Stagehand (Browserbase)

Vamos a usar Stagehand, una librería que permite automatizar navegación e interacción con la web usando IA. La gracia es que desbloquea flujos donde no tienes que decirle exactamente qué selector tocar, sino qué quieres conseguir.

Además, soporta distintos proveedores/modelos (OpenAI, Google, Anthropic, etc.) y también modelos locales tipo Ollama (aunque más lentos).

Setup del proyecto

1) Inicializar proyecto e instalar dependencias

npm init -y
npm install @browserbasehq/stagehand dotenv

En el vídeo se instala Stagehand desde BrowserbaseHQ y se prepara un archivo de test dedicado.

2) Variables de entorno con .env

Creamos un .env:

OPENAI_API_KEY=tu_api_key_aqui

Y lo cargamos al inicio del test:

import 'dotenv/config'

Importante: si tienes una OPENAI_API_KEY definida a nivel global en tu sistema/terminal, puede tener prioridad sobre la del .env y volverte loco. Solución: revisa tu configuración de entorno en la terminal y elimina/ajusta la variable global si corresponde.

3) Asegurar ESM (si lo necesitas)

En el vídeo se cambia el package.json a:

{
  "type": "module"
}

Porque el runner y los imports están en formato ESM.

Las 5 capacidades clave de Stagehand

Stagehand expone varias formas de interactuar con una página. Las más útiles para el día a día suelen ser:

act: ejecutar una acción concreta (click, escribir, etc.) con instrucciones en lenguaje natural
extract: extraer información de la página (ideal para asserts)
observe: explorar la UI para encontrar elementos o entender qué hay
agent: flujos más autónomos (hace “todo” con menos control)
evals: evaluar coste/fiabilidad/efectividad de los tests

Nuestro primer test: comprar 2 entradas y validar el subtotal

Vamos a automatizar un flujo real:

Ir a la web de JSConf
Pulsar “comprar entradas”
Añadir 2 entradas “General”
Extraer el subtotal
Afirmar que el subtotal es el esperado (287,98€ en el ejemplo)

Ejemplo de test (Node test runner + assert)

import 'dotenv/config'
import test from 'node:test'
import assert from 'node:assert/strict'

import { Stagehand } from '@browserbasehq/stagehand'

test('Un usuario puede comprar 2 entradas y ver el subtotal correcto', async () => {
  const stagehand = new Stagehand({
    env: 'LOCAL', // LOCAL (tu máquina) o BROWSERBASE (servicio de pago)
    modelName: 'gpt-5-mini' // el nombre debe coincidir con el del provider/API
  })

  await stagehand.init()

  const page = stagehand.page
  await page.goto('https://jsconf.es')

  // Interacciones guiadas por lenguaje natural
  await stagehand.act('Haz clic en el botón de comprar entradas')
  await stagehand.act('Añade un ticket de entrada general al carrito')
  await stagehand.act('Añade otro ticket de entrada general al carrito')

  // Extracción de info para validar
  const subtotal = await stagehand.extract('Extract the subtotal from the page')

  assert.equal(subtotal, '287,98')

  await stagehand.close()
})

Notas importantes del vídeo:

En español, algunas extracciones pueden fallar y funcionar mejor en inglés (“subtotal” fue un caso claro).
Puedes empezar dando instrucciones más “guiadas” y luego irlas haciendo más naturales para ver si el sistema se comporta como un usuario real.

Local vs Browserbase

Stagehand puede ejecutarse:

LOCAL: corre en tu máquina (más barato, ideal para aprender y prototipar)
BROWSERBASE: corre en infraestructura de Browserbase (más cómodo para empresa, pero de pago)

En el vídeo se usa LOCAL para no depender de costes durante el directo.

Lo que hemos aprendido

Qué aporta un enfoque E2E con IA frente a tests deterministas por selectores
Cómo configurar un proyecto Node para correr tests con Stagehand (.env, ESM, runner)
Cómo usar act para acciones y extract para obtener datos verificables
Por qué a veces conviene escribir prompts en inglés para mejorar la fiabilidad

Con esto ya puedes montar tests que validen no solo que “tu código funciona”, sino que la interfaz se entiende. Y si tu test falla porque no encuentra el subtotal… quizá el usuario tampoco lo estaba encontrando.