Jean Carlo Benites PorrasEnglish

Pruebas automáticas dentro de Baldur’s Gate 3

Un arnés que corre escenarios de prueba dentro del juego real, desde un solo comando, y deja todo como estaba. Lo hice para un proyecto de mods y lo publiqué como código abierto.

Periodo
2026
Rol
Autor
Licencia
MIT
Stack
TypeScript, Lua, C++, Python

Ver el código en GitHub

bg3:test · crooked.dead-aim
$ node --import tsx tools/src/bg3-test.ts --scenario crooked.dead-aim
PASS mods-loaded: Required BG3 mods are loaded in order
PASS bonus-action-cost: Casting Dead Aim spent exactly one bonus action (expected "1", actual "1.0")
PASS marked-hit-bypasses-resistance: The marked attack ignored the target's Fire resistance (expected "8", actual "8")
PASS post-consume-resistant: Resistance applied again after Dead Aim was consumed (expected "4", actual "4")
TIME crooked.dead-aim: 26165 ms
PASS crooked.dead-aim
Extracto de la salida real de una corrida, 24 de octubre de 2026: 4 de sus 23 comprobaciones, 26,2 segundos dentro del juego.

El problema

Un mod de BG3 cambia reglas del juego: cuánto cuesta un hechizo, qué resistencia se ignora, cuándo se consume un efecto. Las pruebas unitarias no dicen si el motor aplica esas reglas como se esperaba. Comprobarlo a mano es abrir el juego, cargar una partida, preparar un combate y lanzar el hechizo: varios minutos por caso, cada vez que algo cambia.

Cómo funciona

  1. Abre BG3 por Steam y apaga Steam Cloud solo durante la corrida.
  2. Carga una partida desechable exacta, verificada por hash, o empieza una campaña nueva.
  3. Le pasa el escenario a Script Extender por un canal de archivos JSON.
  4. El escenario, en Lua, crea lo que necesita, lanza hechizos con su costo real, avanza rondas por turnos y compara el estado del motor con lo esperado.
  5. Deshace en orden inverso lo que creó, cierra el juego y restaura la configuración de mods byte por byte.
Baldur’s Gate 3 entrando en modo por turnos: el personaje de prueba junto a dos lobos que creó el escenario.
El escenario crea a sus objetivos y entra en modo por turnos.
Baldur’s Gate 3 en combate: el registro confirma que el personaje de prueba usó Dead Aim sobre un lobo.
El hechizo se lanza con su costo real; la aserción lee el resultado del motor.

Las partes difíciles

No tocar tus partidas
El arnés trabaja sobre una copia desechable y bloquea la corrida para que dos procesos no se pisen. Un helper en C++ apaga Steam Cloud y lo devuelve a su estado al terminar.
Linux y Proton
Corre sobre Steam con Proton, con el juego en una pantalla sin cabeza de Hyprland. La herramienta oficial para empaquetar mods, LSLib, rechaza cualquier ruta en Linux, así que escribí un empaquetador sobre su librería.
Un crash no es un FAIL
Si el juego se cae, la corrida termina en ERROR y no en FAIL. Así un problema del entorno no se confunde con una regla mal implementada.

En números

El arnés nació dentro de un proyecto de mods privado; el repo público trae el arnés y un mod de ejemplo.

  • 439escenarios dentro del juegoproyecto de mods
  • 1.737pruebas en Vitestproyecto de mods
  • 194suites de pruebas en Luaproyecto de mods
  • 440pruebas en Vitest que no abren el juegorepo público, 24 oct. 2026
  • PASSexample.runtime-smoke dentro de BG3, antes de publicarrepo público, 20 oct. 2026

Qué queda fuera

El contenido del proyecto de mods viene de libros comerciales, así que no se publica. El repo muestra el arnés, que es la parte de ingeniería.

Siguiente caso: CLX

Escríbeme

Busco un puesto remoto full-stack o backend senior. Respondo en español o en inglés.

CV (PDF)LinkedInGitHub