Promptfoo: prueba prompts como código

Los prompts son código que llega directo a los usuarios, pero la mayoría de los equipos los edita a ciegas. Ajustas una frase, revisas una o dos salidas a ojo, despliegas, y te enteras por una queja de que el cambio rompió algo en otro caso totalmente distinto. El problema es de fondo. Los prompts no tienen suite de pruebas, así que no hay nada que correr antes de mandarlos. Promptfoo llena ese hueco con la respuesta más aburrida posible: un archivo de config, un test runner y un diff. Acá va qué es Promptfoo realmente, cuándo vale la pena frente a un script de eval hecho a mano o una plataforma de evals alojada, un quickstart que pegas en un repo en cinco minutos y las concesiones que duelen, sobre todo el grader LLM no determinista que, usado sin cuidado, te tumba el build sin razón real.

01 · Qué es en realidad

Promptfoo es dos cosas en un mismo binario: un test runner para prompts y modelos, y un visor local que muestra los resultados como una grilla. Describes el trabajo en un config YAML (qué prompts, qué providers, qué casos de prueba) y Promptfoo corre cada combinación y compara la salida contra los asserts que declaraste.

La forma fácil de pensarlo es como una hoja de cálculo. Las filas son tus casos de prueba, cada uno con sus propias variables de entrada. Las columnas son las combinaciones de prompt-y-provider que estás probando. Cada celda es una salida del modelo con su pasa/falla y su costo. Abres el visor y lees toda la matriz de un golpe: qué entradas se rompieron, qué modelo sale más barato, dónde divergen dos prompts.

• Un prompt es un archivo de plantilla o un string inline con «{{variables}}» que se rellenan en cada caso de prueba.
• Un provider es un endpoint de modelo, por ejemplo anthropic:claude-opus-4-8, y puedes listar varios para compararlos cara a cara.
• Un test es una fila: un conjunto de valores de variables más los asserts que esa salida tiene que cumplir.
• Un assert es el chequeo: coincidencia exacta, contains, regex, is-json, validación contra un JSON schema, similitud semántica (similar) o una llm-rubric calificada por otro modelo.

Esa es toda la superficie. Todo lo demás (la integración con CI, el visor web, la generación de datasets) se apoya en ese núcleo de config-más-asserts.

02 · Por qué importa

El valor central es una suite de regresión para prompts. Una vez que tus prompts importantes tienen casos de prueba, cambiar uno deja de ser un salto al vacío. Editas, corres la suite y el diff te dice exactamente qué salidas cambiaron y si siguen pasando. Un cambio que rompió en silencio el caso de clasificar reembolsos ahora sale en rojo antes de llegar a un usuario, no después.

El segundo valor es comparar modelos en tus propias tareas. Los benchmarks públicos te dicen cómo le va a un modelo con los problemas de otra gente. No te dicen nada de los tuyos. Listar dos providers en el mismo config y correr tus casos reales te da una grilla pareja (accuracy, costo y latencia por celda) sobre el trabajo que de verdad haces. Cuando sale un modelo nuevo, volver a correr la suite es la forma honesta de decidir si te conviene cambiar.

Atrapar los fallos que se esconden

La mayoría de las regresiones de prompt no son crashes. Son una respuesta segura pero equivocada que, vista sola, parece estar bien. Un prompt que resumía limpio empieza a comerse la conclusión. Un clasificador que devolvía { "label": "urgent" } empieza a envolverlo en prosa. Ninguno lanza un error. Simplemente se degradan en silencio. Los asserts duros los atrapan de forma mecánica: verifica que la salida sea is-json, que contains el id del ticket, que cumpla un schema. El test falla en el instante en que la forma se desvía.

03 · Cuándo usarlo (y cuándo no)

Usa Promptfoo cuando:

1. Un prompt importa en producción y lo cambias más de una vez: cualquier cosa de cara al usuario, cualquier cosa en un flujo que genera ingresos.
2. Estás eligiendo entre modelos, o decidiendo si adoptar uno más nuevo, y quieres basar la decisión en tus tareas y no en un leaderboard.
3. Quieres que los cambios de prompt pasen por code review y CI como el resto de tu código, con un check que falla cuando una salida se regresa.

Usa otra cosa cuando:

• Es un prompt de usar y tirar. Un prompt que vas a correr una vez y descartar no necesita suite de regresión. No le montes andamiaje a un script.
• Necesitas tracing completo de producción, no evals antes del deploy. Promptfoo prueba prompts antes de que salgan, contra un dataset fijo. Si lo que de verdad necesitas es observar el tráfico en vivo (cada prompt, completion y tool call en producción), ese es el trabajo de una herramienta de tracing, como Langfuse, no de Promptfoo. Son complementarias: evals antes, trazas después.
• Tu set de pruebas es realmente enorme y lo comparte todo un equipo. A gran escala, con mucha gente curando datasets y revisando resultados en conjunto, la base de datos y los controles de acceso de una plataforma de evals alojada quizá valgan lo que cuestan. Para alguien que construye solo o un equipo pequeño, el flujo local de YAML-y-CLI es más liviano y más que suficiente.

04 · Quickstart

Promptfoo corre con npx, así que no hay nada que instalar de forma global. Genera un config, apúntalo a tu prompt y tus providers, y córrelo. Primero define la API key de tu modelo en el entorno. Para Anthropic es ANTHROPIC_API_KEY. Nunca la subas al repo. Tómala de tu secrets manager (en nuestro stack, vaulting estilo Infuse, no un .env subido al repo).

export ANTHROPIC_API_KEY="..."   # de tu secrets manager, no de un archivo commiteado
npx promptfoo@latest init        # genera promptfooconfig.yaml

Ahora edita el config. El ejemplo de abajo prueba un archivo de prompt contra un provider en dos casos, mezclando un assert duro con una rúbrica. Ojo: los chequeos duros (contains, is-json) no necesitan llamar al modelo para calificar, mientras que la llm-rubric levanta un segundo modelo para juzgar. Ten presente esa diferencia tanto por costo como por inestabilidad.

prompts:
  - file://prompts/classify.txt
providers:
  - anthropic:claude-opus-4-8
tests:
  - vars:
      input: "quiero un reembolso del pedido 4471"
    assert:
      - type: is-json
      - type: contains
        value: "4471"
  - vars:
      input: "¿dónde está mi paquete?"
    assert:
      - type: llm-rubric
        value: "Clasifica el mensaje como consulta de envío/estado, no de reembolso."

Corre la matriz y abre el visor para leer la grilla:

npx promptfoo@latest eval        # corre cada prompt x provider x test
npx promptfoo@latest view        # abre el visor web local

En CI, ese mismo comando eval es tu compuerta. Termina con código distinto de cero cuando un assert falla, así que un prompt regresado bloquea el merge igual que un test unitario que falla. Engánchalo al mismo workflow que corre tus demás checks y, a partir de ahí, un cambio de prompt necesita la suite en verde para entrar.

05 · Las concesiones que nadie pone en el README

Los gotchas honestos, en el orden en que suelen morder.

Los asserts calificados por LLM no son deterministas. La mayor trampa de todas. Una llm-rubric le pide a un modelo que juzgue la salida, y ese juez puede dar un veredicto distinto con la misma entrada de una corrida a otra. Si te apoyas en eso para todo, tu build parpadea en rojo sobre código que está bien, y eso entrena a todo el mundo a ignorar la suite. Ese es el peor resultado posible para un test en el que querías confiar. La solución es disciplina. Fija con asserts duros todo lo que puedas (is-json, contains, regex, schema) y reserva la rúbrica para la calidad que de verdad es subjetiva y no se puede expresar como un chequeo mecánico. Un juez inestable que falla uno de cada veinte casos es peor que no tener test en ese caso, porque te tumba la confianza en los diecinueve que sí son sólidos.

El costo escala con la matriz, sin que te des cuenta. La grilla se multiplica: prompts por providers por casos de prueba, y se duplica otra vez en cualquier fila con rúbrica. Es fácil escribir un config que se ve razonable pero cuesta plata real cada vez que CI lo corre. Vigila las dimensiones, cachea donde puedas y no corras la suite completa en cada commit trivial si la puedes acotar a los cambios de prompt.

Los asserts duros solo revisan la forma, no la verdad. Un contains o un chequeo de schema verifica que la salida tenga la forma correcta, no que la respuesta sea correcta. Un clasificador puede devolver JSON válido con la etiqueta equivocada y pasar limpio por is-json. Los asserts duros son necesarios y baratos, pero combínalos con unas pocas rúbricas o revisiones humanas bien elegidas en los casos donde lo que importa es que la respuesta sea correcta, no su formato.

Una suite en verde vale lo que valen sus casos. Promptfoo prueba exactamente lo que le dices y nada más. Si a tu dataset se le escapa un modo de fallo, la suite sigue en verde mientras ese modo se rompe en producción. Trata el set de pruebas como un artefacto vivo: cada incidente nuevo se convierte en un caso nuevo, igual que agregarías un test de regresión después de arreglar un bug en código normal.

Promptfoo es la herramienta que quiero tener lista antes de la segunda vez que toco un prompt importante, no después de que un mal cambio ya salió. Es deliberadamente poco glamoroso, un config, un runner, un diff, y ese es justo el punto. Convierte "creo que este prompt sigue bien" en "la suite está en verde". Solo úsalo con los ojos abiertos respecto al grader: los asserts duros son tu columna vertebral, las rúbricas son una herramienta filosa para un trabajo muy puntual, y cada corrida gasta plata de verdad.