autocannon: Pruebas de Carga HTTP con Node.js (Paso a Paso)

Usted escribió un endpoint HTTP y funciona cuando lo llama una vez desde Postman. El siguiente paso es medir qué ocurre cuando 200 clientes lo llaman al mismo tiempo: solicitudes por segundo, percentiles de latencia y respuestas no 2xx. autocannon le da esos números desde la terminal en unos segundos.

Prueba Apidog hoy

autocannon es una herramienta de benchmarking HTTP/1.1 escrita en Node.js. Genera carga controlada contra una URL y reporta rendimiento, latencia, errores y bytes leídos. En esta guía verá cómo instalarla, ejecutar pruebas básicas, enviar POST con headers y body, leer la salida y usarla desde scripts de Node para automatizar umbrales de rendimiento.

Qué es autocannon

autocannon abre un número fijo de conexiones concurrentes hacia una URL y envía solicitudes durante una duración definida o hasta completar una cantidad específica de requests. Mientras se ejecuta, mide latencia, throughput y respuestas.

Use autocannon para responder esta pregunta:

¿Cuánta carga soporta mi endpoint y qué latencia tiene bajo esa carga?

No lo use para validar si el JSON devuelto es correcto, si la API cumple su contrato OpenAPI o si un flujo de varios pasos mantiene la lógica esperada. Para eso necesita pruebas funcionales y de contrato.

Si ya ha usado wrk o Apache Bench, autocannon ocupa el mismo espacio, pero con instalación vía npm y API programática para JavaScript.

Instalación

Instale autocannon globalmente si quiere usar el comando desde cualquier directorio:

npm i autocannon -g

Verifique la instalación:

autocannon --version

Si no quiere instalarlo globalmente, ejecútelo con npx:

npx autocannon http://localhost:3000

Para usarlo dentro de scripts del proyecto, agréguelo como dependencia de desarrollo:

npm i autocannon --save-dev

Ejecución básica

El comando mínimo es:

autocannon http://localhost:3000

Por defecto, ejecuta una prueba de 10 conexiones durante 10 segundos.

Los tres flags que más usará son:

• -c: número de conexiones concurrentes.
• -d: duración en segundos.
• -p: pipelining, es decir, cuántas solicitudes envía cada conexión antes de esperar respuesta.

Ejemplo:

autocannon -c 100 -d 30 -p 10 http://localhost:3000

Este comando:

• abre 100 conexiones;
• ejecuta la prueba durante 30 segundos;
• usa pipelining de 10 solicitudes por conexión.

Aumente -c y -p gradualmente para encontrar el punto donde las solicitudes por segundo dejan de crecer y la latencia empieza a subir.

Enviar un número fijo de solicitudes

Si quiere detener la prueba después de una cantidad exacta de requests, use -a:

autocannon -c 10 -a 10000 http://localhost:3000

Esto envía 10,000 solicitudes y termina, sin importar cuánto tiempo tarde.

Use:

• -d para pruebas de carga en estado estable.
• -a para pruebas con volumen exacto de solicitudes.

Solicitudes POST, headers y body

Para cambiar el método HTTP use -m.

Para agregar headers use -H.

Para enviar un body use -b.

Ejemplo de POST JSON:

autocannon -c 50 -d 20 \
  -m POST \
  -H 'Content-Type=application/json' \
  -H 'Authorization=Bearer YOUR_TOKEN' \
  -b '{"name":"load-test","active":true}' \
  http://localhost:3000/api/users

El formato de headers es:

-H 'Key=Value'

Repita -H por cada header.

Si el body es grande o ya lo tiene en un archivo, use -i:

autocannon -m POST \
  -H 'Content-Type=application/json' \
  -i payload.json \
  http://localhost:3000/api/users

Limitar la tasa de solicitudes

Por defecto, autocannon envía solicitudes tan rápido como puede. Si quiere simular una carga más realista, limite las solicitudes por segundo con -R:

autocannon -c 50 -R 500 -d 60 http://localhost:3000

Este comando mantiene la prueba en 500 solicitudes por segundo durante 60 segundos.

Use -R cuando quiera medir latencia bajo una carga esperada, no necesariamente encontrar el punto de ruptura del servidor.

Calentamiento y workers

En pruebas más pesadas, use:

• -W: periodo de calentamiento antes de empezar a medir.
• -w: workers de Node para generar más carga.

Ejemplo:

autocannon -c 200 -d 30 -w 4 http://localhost:3000

El calentamiento ayuda a evitar números distorsionados por cachés frías o JIT sin calentar.

Use -w solo si confirma que el generador de carga es el cuello de botella. Una señal típica es que la latencia se mantiene sospechosamente plana aunque aumente -c.

Interpretar los resultados

Una salida resumida de autocannon se ve así:

Ejecutando prueba de 10s @ http://localhost:3000
10 conexiones

┌─────────────┬──────┬──────┬───────┬──────┬────────┬─────────┬─────────┐
│ Estadística │ 2.5% │ 50%  │ 97.5% │ 99%  │ Prom   │ DesvEst │ Máx     │
├─────────────┼──────┼──────┼───────┼──────┼────────┼─────────┼─────────┤
│ Latencia    │ 0 ms │ 1 ms │ 4 ms  │ 6 ms │ 1.2 ms │ 0.9 ms  │ 24.1 ms │
└─────────────┴──────┴──────┴───────┴──────┴────────┴─────────┴─────────┘

251k solicitudes en 10.05s, 27.9 MB leídos

Lea la salida así:

• 50%: mediana de latencia.
• 97.5% y 99%: latencia de cola. Estos valores suelen revelar problemas reales.
• Prom: latencia promedio.
• DesvEst: dispersión de latencia. Si es alta, las respuestas son inconsistentes.
• Solicitudes en X segundos: throughput total. Divida solicitudes por segundos para obtener requests por segundo.

Para obtener más percentiles, use -l:

autocannon -c 100 -d 20 -l http://localhost:3000

Para ver el desglose por códigos de estado, agregue --renderStatusCodes:

autocannon -c 100 -d 20 -l --renderStatusCodes http://localhost:3000

Preste atención a:

• errores;
• timeouts;
• respuestas no 2xx;
• códigos 5xx.

Un servidor puede mostrar muchas solicitudes por segundo mientras devuelve errores. Si non-2xx no es cero, su throughput incluye fallas, no solo respuestas exitosas.

Uso programático desde Node.js

autocannon expone una API de Node.js. Esto permite ejecutar benchmarks desde scripts y fallar una build si se supera un presupuesto de latencia.

Ejemplo básico:

const autocannon = require('autocannon')

async function run() {
  const result = await autocannon({
    url: 'http://localhost:3000',
    connections: 100,
    duration: 20,
    pipelining: 1
  })

  console.log(`Avg latency: ${result.latency.average} ms`)
  console.log(`Req/sec: ${result.requests.average}`)
  console.log(`Non-2xx: ${result.non2xx}`)
}

run()

El objeto result incluye métricas como:

• result.latency.average
• result.latency.p99
• result.requests.average
• result.throughput.average
• result.errors
• result.timeouts
• result.non2xx

Convertir autocannon en una puerta de CI

Puede establecer un presupuesto de latencia y fallar el proceso si se excede:

const autocannon = require('autocannon')

const P99_BUDGET_MS = 250

async function run() {
  const result = await autocannon({
    url: 'http://localhost:3000/api/health',
    connections: 100,
    duration: 30
  })

  const p99 = result.latency.p99

  console.log(`Latencia p99: ${p99} ms`)
  console.log(`Presupuesto p99: ${P99_BUDGET_MS} ms`)
  console.log(`Non-2xx: ${result.non2xx}`)

  if (p99 > P99_BUDGET_MS || result.non2xx > 0) {
    console.error('Presupuesto de rendimiento excedido')
    process.exit(1)
  }
}

run()

Este patrón funciona bien en CI porque convierte el benchmark en una validación automática:

• pasa si la latencia está dentro del presupuesto;
• falla si el p99 sube demasiado;
• falla si aparecen respuestas no 2xx.

Mostrar progreso y tabla como en la CLI

Si quiere la barra de progreso y la tabla de resultados desde un script, use autocannon.track:

const autocannon = require('autocannon')

const instance = autocannon({
  url: 'http://localhost:3000',
  connections: 10,
  duration: 10
}, console.log)

autocannon.track(instance, { renderProgressBar: true })

process.once('SIGINT', () => instance.stop())

Escenarios con múltiples solicitudes

Para ejecutar varios requests dentro de la misma prueba, use el array requests:

const autocannon = require('autocannon')

autocannon({
  url: 'http://localhost:3000',
  connections: 20,
  duration: 15,
  requests: [
    {
      method: 'GET',
      path: '/api/users'
    },
    {
      method: 'POST',
      path: '/api/data',
      body: '{"x":1}',
      headers: {
        'Content-Type': 'application/json'
      }
    }
  ]
}, console.log)

Esto es útil para endpoints relacionados, aunque no reemplaza una prueba funcional completa de flujo de negocio.

autocannon vs wrk y ab

Las tres herramientas responden una pregunta parecida: qué tan rápido responde un endpoint bajo carga.

• Apache Bench (ab): simple y disponible en muchos entornos, pero antiguo y de un solo hilo.
• wrk: rápido, compilado en C y con scripting Lua para solicitudes personalizadas.
• autocannon: buena opción si trabaja con Node.js. Se instala con npm, tiene API programática y soporta pipelining, archivos HAR y escenarios por solicitud.

Si Node ya forma parte de su stack, autocannon suele ser la opción con menos fricción.

También puede comparar otros enfoques:

• pruebas de carga sin Python;
• pruebas de carga con k6.

Dónde encajan las pruebas funcionales y Apidog

autocannon puede decirle que un endpoint sirve 12,000 solicitudes por segundo con p99 de 40 ms. No puede decirle si el endpoint devuelve los datos correctos.

Una prueba de carga puede pasar aunque la API:

• devuelva JSON malformado;
• ignore un header de autenticación;
• rompa su contrato OpenAPI;
• devuelva valores incorrectos en un flujo de varios pasos.

El rendimiento no equivale a corrección.

Ahí entran las pruebas funcionales y de contrato. Apidog complementa una herramienta de carga: ejecuta escenarios guardados para validar códigos de estado, esquemas de respuesta y valores en flujos de API.

Puede ejecutar la CLI de Apidog desde CI:

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

Parámetros principales:

• -t: escenario, carpeta o suite guardada por ID.
• -e: entorno.
• -r: reportadores, como cli, html, json o junit.

Para más detalles, consulte:

• cómo ejecutar pruebas de API desde la CLI de Apidog;
• pipeline de CI/CD de copiar y pegar;
• flujo de trabajo de GitHub Actions.

Un pipeline saludable separa responsabilidades:

1. En cada push: pruebas funcionales y de contrato.
2. Antes de un release: prueba de carga.
3. En producción: monitoreo y alertas.

Use autocannon para responder: “¿resiste bajo carga?”

Use Apidog para responder: “¿la API sigue siendo correcta?”

Preguntas frecuentes

¿autocannon es preciso para pruebas de carga en producción?

autocannon produce métricas fiables de rendimiento y latencia para endpoints HTTP/1.1. Si define una tasa objetivo con -R, también ayuda a evitar la omisión coordinada.

Para obtener mejores resultados:

• ejecútelo desde una máquina cercana al servidor;
• use un entorno de staging parecido a producción;
• aumente conexiones de forma gradual;
• verifique que el generador de carga no sea el cuello de botella;
• no lo ejecute contra el servidor de desarrollo de su portátil si quiere números representativos.

¿autocannon soporta HTTP/2 o WebSockets?

No. autocannon realiza benchmarks de HTTP/1.1.

Para HTTP/2 o WebSockets necesita otra herramienta de carga.

¿Cuántas conexiones debería usar?

Empiece con el valor predeterminado de 10:

autocannon http://localhost:3000

Luego aumente -c progresivamente:

autocannon -c 50 -d 30 http://localhost:3000
autocannon -c 100 -d 30 http://localhost:3000
autocannon -c 200 -d 30 http://localhost:3000

Busque el punto donde:

• las solicitudes por segundo dejan de subir;
• la latencia p95/p99 empieza a crecer;
• aparecen timeouts o errores.

Ese punto marca aproximadamente la capacidad útil del endpoint bajo esa configuración.

¿Puedo ejecutar autocannon en CI?

Sí. Use la API programática, lea result.latency.p99, result.non2xx, result.errors y result.timeouts, y termine con process.exit(1) si se supera un umbral.

Ejemplo de criterio simple:

if (
  result.latency.p99 > 250 ||
  result.non2xx > 0 ||
  result.errors > 0 ||
  result.timeouts > 0
) {
  process.exit(1)
}

¿Cuál es la diferencia entre -a y -d?

-d ejecuta la prueba durante una duración fija:

autocannon -d 30 http://localhost:3000

-a ejecuta la prueba hasta completar una cantidad fija de solicitudes:

autocannon -a 10000 http://localhost:3000

Use -d para pruebas de carga sostenida y -a cuando necesite enviar un número exacto de requests.