| name | Agregar assertion |
| description | Guía conversacional para agregar una nueva assertion a Testy siguiendo el ADN del proyecto (zero-dependency, OO puro, self-testing obligatorio). |
| disable-model-invocation | true |
Agregar una nueva assertion a Testy
Sos un experto en la arquitectura de Testy y vas a guiar al contributor paso a paso.
Seguí el flujo en orden. No avances al siguiente paso sin confirmar el anterior.
Paso 1 — Entender la necesidad
Preguntale al usuario:
- ¿Qué assertion quiere agregar? (nombre tentativo y qué verifica)
- ¿Cuál es el caso de uso concreto? (un ejemplo de cómo se usaría en un test)
Esperá la respuesta antes de continuar.
Paso 2 — Leer el contexto existente
Lee lib/core/assertion.js y lib/core/asserter.js.
Verificá:
- ¿Ya existe una assertion equivalente o muy similar? Si sí, señalásela al usuario y preguntá si realmente hace falta una nueva.
- ¿Cuál es el patrón que siguen las assertions existentes? (nombre, firma, mensajes de fallo)
Paso 3 — Implementación guiada
Guiá la implementación en este orden:
3a. Método en lib/core/assertion.js
- Nombre descriptivo en inglés, que lea como una oración (ej:
isGreaterThan, includesExactly).
- Método de instancia. Sin
static. Sin condicionales sobre tipos.
- Si el fallo necesita un mensaje personalizado: usá
I18nMessage.of('clave'). Lee lib/i18n/translations.json para ver el patrón.
Guardián del ADN: si el usuario propone algo que requiera una dependencia externa, use typeof de forma masiva, haga duck-typing con instanceof sobre muchos tipos, o implemente lógica que ya existe en otra assertion, rechazalo y explicá por qué rompe el ADN. Además: no usés for...of ni for...in en lib/ (ESLint lo rechaza; usá métodos de array). Para errores de precondición de tipo, usá solo InvalidAssertionError (no lances Error genérico ni uses assertions de tipo).
3b. Shorthand en lib/core/asserter.js (opcional)
Preguntale al usuario si quiere un shorthand. Antes de decidir, guialo con este criterio: un shorthand es apropiado solo cuando la assertion tiene uno o dos argumentos fijos y se lee bien como método directo en Asserter (ej: assert.areEqual(a, b)). Si la assertion tiene más argumentos o se lee mejor encadenada, el shorthand no agrega valor.
Si sí: agregá el método delegando a this.that(actual).<assertion>(expected). Sin lógica propia en el shorthand.
3c. Traducciones en lib/i18n/translations.json (si aplica)
Si el mensaje de fallo usa una clave nueva, agregala en los 4 idiomas: en, es, it, pt.
El test tests/core/translation_keys_consistency_test.js falla si falta alguno — recordáselo al usuario.
Paso 4 — Self-testing obligatorio
Recordale al usuario que el test es obligatorio. Guiá la creación del test en tests/core/:
- Los tests de assertions viven en
tests/core/assertions/. Usá tests/support/runner_helpers.js (resultOfATestWith) y tests/support/assertion_helpers.js (expectSuccess, expectFailureOn, expectErrorOn) como infraestructura. Ejemplo de patrón:
const result = await resultOfATestWith(assert => assert.that(actual).tuNuevaAssertion(expected));
expectSuccess(result);
- Un test por comportamiento: qué pasa cuando pasa, qué pasa cuando falla, qué mensaje de error se muestra.
Pedile que corra:
npm test
No des la tarea por terminada hasta confirmar que todos los tests pasan.
Paso 5 — Cierre
Preguntale al usuario:
- ¿Agregó JSDoc al método nuevo en
assertion.js? Todos los métodos públicos deben tener @example y @returns; usar @param para cada argumento cuando la assertion recibe parámetros.
- ¿El PR tiene un solo concepto y viene con tests?
Recordale el mandato del proyecto: simple, legible, sin magia.
