agregar-assertion

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:

1. ¿Qué assertion quiere agregar? (nombre tentativo y qué verifica)
2. ¿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); // o expectFailureOn(result, mensajeEsperado)

• 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.