# Pruebas

`elide test` ejecuta archivos `node:test` de JavaScript y TypeScript y pruebas JUnit.

```bash
elide test
```

Una prueba que falla hace que el código de salida sea distinto de cero.

<img src="/assets/demos/test.gif" alt="Descubrimiento y ejecución de pruebas de JavaScript con Elide" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## JavaScript y TypeScript

Las pruebas usan la API `node:test` y no necesitan manifiesto. Un archivo es una prueba si coincide con `*.test.*`,
`*.spec.*`, `*_test.*` o `*_spec.*`, o si está dentro de `test`, `tests` o `__tests__`. Extensiones: `.js`, `.mjs`,
`.cjs`, `.ts`, `.mts`, `.cts`.

El descubrimiento omite los directorios ocultos, los de dependencias y los de salida de compilación. Se detiene en
cualquier proyecto anidado (un directorio con `elide.pkl`, `package.json`, `pom.xml` o `requirements.txt`), así que la
raíz de un espacio de trabajo no encuentra las pruebas de sus miembros. Indique una ruta para ejecutarlas.

```js
import test from "node:test";
import assert from "node:assert";

test("adds two values", () => {
  assert.equal(1 + 1, 2);
});
```

## Pruebas JVM

Las pruebas JVM se ejecutan en JUnit Platform y necesitan un `elide.pkl`. `src/test` es el conjunto de fuentes de
pruebas predeterminado; un conjunto de fuentes declarado de tipo `test` lo sustituye
([Conjuntos de fuentes](/docs/toolchain/source-sets)).

- Los conjuntos de pruebas reciben `testPackages` más las dependencias del conjunto principal.
- Las bibliotecas JUnit incluidas se añaden por defecto. `jvm.features.testing = false` elimina tanto las API de
  compilación de JUnit como el entorno de ejecución incluido; entonces una ejecución de pruebas JVM necesita un
  lanzador de consola de JUnit (`junit-platform-console`) en `testPackages` y, si no lo hay, falla con un error. Las
  ejecuciones sin pruebas JVM no se ven afectadas.
- Los `processors` se ejecutan sobre las fuentes de prueba.
- La JVM de pruebas recibe `jvm.flags` y `jvm.defs` (como `-D`).
- Las dependencias `modules` de los conjuntos de pruebas y principal van en `--module-path` con
  `--add-modules=ALL-MODULE-PATH`.
- La configuración de paralelismo de un `junit-platform.properties` en el classpath de pruebas tiene prioridad sobre
  `--concurrency`.

## Seleccionar pruebas

Las rutas, los directorios o los globs acotan las pruebas de JavaScript y TypeScript:

```bash
elide test src/api
elide test src/api/client.test.ts
```

Los argumentos de ruta omiten las pruebas JVM e imprimen `Path filtering unsupported for JVM tests: <paths>`. `-t`
filtra por nombre de prueba en ambos ejecutores:

```bash
elide test -t 'parses .+ headers'
```

Las pruebas JVM admiten selectores de JUnit y expresiones de etiquetas:

```bash
elide test --select=class:com.example.ParserTest
elide test --select=method:com.example.ParserTest#parsesHeaders
elide test --select=package:com.example.parser   # the package and its subpackages
elide test com.example.parser                     # a dotted bare token is a package selector
elide test --include-tag=fast --include-tag=unit  # fast OR unit
elide test --exclude-tag=slow --exclude-tag=flaky # neither slow nor flaky
elide build test --select=class:com.example.ParserTest
```

<img src="/assets/demos/jvm-test.gif" alt="elide test — selectores de JUnit en un proyecto Kotlin" width="1591" height="873" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`--include-tag='slow & !flaky'` es una sola expresión. Los filtros de etiquetas se aplican después de los selectores.

## Salida e informes

El progreso va a stderr; el recuento final, a stdout:

```bash
elide test > summary.txt
elide test 2> progress.txt
```

Los informes se escriben en `.dev/reports/tests/<language>/<source-set>/`. `testing.reports` en `elide.pkl` los activa
sin ninguna opción:

```pkl
import "elide:Testing.pkl" as Testing

testing {
  reports { Testing.xmlReport() }
}
```

### Salida TAP

`--reporter=tap` convierte stdout en un flujo TAP 13 puro:

```text
TAP version 13
# start 1: suite A > t1
# out 1: printed from inside a test
ok 1 - suite A > t1
# start 2: broken
not ok 2 - broken
  ---
  message: "expected 1 to equal 2"
  severity: "ERR_ASSERTION"
  ...
1..2
```

- `# start <id>` abre una prueba; sus líneas de salida son `# out <id>: <text>`. `# out: <text>` no pertenece a
  ninguna prueba.
- Los puntos de prueba se numeran `1..N` en orden de finalización. Asocie los puntos a las pruebas por la línea
  `# start`, no por el número.
- Un bloque YAML solo aparece en fallos con detalles; `severity` es el código de error del ejecutor, si lo hay.
- Stderr no se encapsula: `elide test --reporter=tap 2>&1` no es TAP válido.
- JVM: la salida se asocia a su prueba solo mientras se ejecuta exactamente una prueba. Con `--concurrency` mayor que 1
  o un `junit-platform.properties` en el proyecto, queda sin asociar.
- JavaScript: `console.log` dentro de una prueba, o en el nivel superior después de importar `node:test`, se encapsula.
  La salida anterior a esa importación sale tal cual. La salida de un hook pertenece a la prueba que el hook envuelve;
  `t.diagnostic` se encapsula como `# out`.

Defina `ELIDE_TEST_METADATA=1` con `--reporter=tap` para incluir comentarios JSON versionados `# elide-test:`
antes de los resultados. Contienen el número de resultado, la identidad de inicio, el motor, el archivo fuente, la
suite, el estado y la duración medida en milisegundos. La identidad de inicio relaciona las pruebas concurrentes con su
salida capturada, aunque los nombres se repitan y el orden de finalización difiera. Los consumidores de TAP habituales
ignoran estos comentarios; la salida predeterminada y los informes por suite no cambian.

## Cobertura

```bash
elide test --coverage
elide run --coverage
```

En un espacio de trabajo de proyecto de Tern, elija **Test** y luego **Run with coverage**. La pestaña **Coverage**
aparece cuando la ejecución se ha medido: enumera los archivos medidos con sus líneas cubiertas, parcialmente cubiertas
y sin cubrir, y muestra el código fuente actual del archivo seleccionado con cada línea medida coloreada según su
cobertura. Las líneas que el entorno de ejecución nunca mide (llaves de cierre, líneas en blanco, comentarios) reciben
un tono más claro cuando el bloque al que pertenecen se ejecutó: la línea medida más cercana por encima de ellas en ese
bloque estaba cubierta y no hay ninguna línea sin cubrir entre ambas. No cuentan en los porcentajes.
**Next uncovered** y **Previous uncovered** (`n` y `p`) saltan entre huecos, y **Open line N in Elide source** abre el
archivo en la línea enfocada; guarde los cambios y elija **Run again** para medir el código actualizado. El historial de
ejecuciones conserva las mediciones anteriores, y los datos de ramas no disponibles se muestran aparte de una cobertura
nula.

Los botones de apertura de la vista Tests (**Open in Elide source** y **Open** en la tarjeta de una prueba) solo
responden a un clic. Un programa de terminal que dibuja una vista de Tern no puede pedir a Tern que abra un enlace desde
una tecla, así que Enter no abre la selección; haga clic en el botón o ⌘-clic en un nombre de archivo enlazado.
Consulte [Cobertura en Tern](/docs/tern-coverage).

Las integraciones de pruebas pueden definir `ELIDE_COVERAGE_REPORT` con una ruta de archivo propia de la ejecución al
solicitar cobertura. Elide escribe de forma atómica un artefacto JSON versionado con los archivos fuente medidos, la
cobertura de líneas ejecutables y los contadores de ramas cuando están disponibles. Este artefacto es independiente de
los informes LCOV o JaCoCo configurados. Una integración debe asignar un destino nuevo para cada ejecución.

Las huellas de los archivos fuente de JavaScript describen el texto que evaluó el entorno de ejecución, aunque el archivo
cambie antes de escribirse el informe. La cobertura es una medición de esa versión del código fuente. Una huella o una
medición de ramas ausente significa que el dato no está disponible; no significa que el archivo actual coincida ni que
no se ejecutara ninguna rama. La cobertura de líneas registra si una línea se cubrió, no cuántas veces se ejecutó.

La cobertura JVM va a `.dev/reports/coverage/jvm/<task>/` en HTML, XML o CSV; la de JavaScript y TypeScript es LCOV,
en `.dev/reports/coverage/js/lcov.info` para las pruebas y `.dev/reports/coverage/js/run/lcov.info` para las
ejecuciones. La consola imprime un único resumen combinado. El bloque `coverage` de nivel superior recopila sin la
opción:

```pkl
import "elide:Coverage.pkl" as Coverage

coverage {
  enabled = true
  scope = "tests"
  jvm {
    excludes { "org.example.generated.*" }
    reports {
      Coverage.xmlReport()
      Coverage.htmlReport()
    }
    minimum {
      line = 0.85
      branch = 0.70
    }
  }
  js {
    paths { "src" }
    minimum { line = 0.80 }
  }
}
```

| Propiedad | Significado | Valor predeterminado |
| --- | --- | --- |
| `enabled` | Recopilar sin `--coverage`. | `false` |
| `scope` | `"tests"`, `"runs"` o `"all"`; `--coverage` siempre cubre su propia tarea. | `"tests"` |
| `jvm.reports` | `Coverage.htmlReport()`, `xmlReport()`, `csvReport()`. | ninguno |
| `jvm.excludes` | Patrones de clase (`*`, `?`) que no se instrumentan, como el código generado. | ninguno |
| `jvm.minimum.line`, `jvm.minimum.branch` | Proporción mínima cubierta, de `0.0` a `1.0`. | ninguno |
| `js.paths` | Raíces de fuentes que se incluyen en el informe; vacío significa todo el proyecto. | ninguno |
| `js.minimum.line` | Proporción mínima de líneas cubiertas, de `0.0` a `1.0`. | ninguno |

Cuando una ejecución recoge cobertura, `elide test` termina con un código distinto de cero si no se alcanza un `minimum`,
indicando la propiedad, la proporción exigida y la medida. Un mínimo sin nada que medir, como la ausencia de pruebas JVM
o de clases analizadas, también falla. Los informes se escriben en ambos casos. Las proporciones de la JVM cuentan
todas las clases que analiza la ejecución de pruebas.

Con cobertura, `elide run` inicia un proceso JVM aparte.

## Opciones

| Opción | Efecto |
| --- | --- |
| `-t REGEX` | Filtra por nombre de prueba o de la suite que la contiene. |
| `--where CEL` | JavaScript: ejecuta las pruebas para las que una expresión [CEL](/docs/api-cel) sobre `name`, `parents` y `file` es verdadera. |
| `--select=SELECTOR` | JVM: selector `class:`, `method:` o `package:`; repetible. |
| `--include-tag=EXPR` | JVM: ejecuta las pruebas cuyas etiquetas coinciden; las repeticiones se combinan con OR. |
| `--exclude-tag=EXPR` | JVM: omite las pruebas cuyas etiquetas coinciden; las repeticiones se combinan con AND. |
| `--bail[=N]` | Se detiene tras `N` fallos (1 por defecto). |
| `--test-timeout=MS` | Tiempo límite predeterminado por prueba. |
| `--timeout DURATION` | Tiempo límite de toda la invocación (global). |
| `--only` | Ejecuta solo las pruebas marcadas con `.only`. |
| `--concurrency=N` | Ejecuta archivos o clases JVM en paralelo. Por defecto `1`; `0` no es válido. |
| `--coverage` | Recopila la cobertura; consulte [Cobertura](#coverage). |
| `--reporter=junit` | Escribe informes JUnit XML. |
| `--reporter=tap` | Escribe TAP 13 en stdout (y en `--reporter-outfile`). |
| `--reporter-outfile=DIR` | Directorio de informes. |
| `--debugger[=MODE\|ADDRESS]` | Conecta un depurador; consulte más abajo. |
| `--debugger-host=HOST`, `--debugger-port=PORT` | Dirección del depurador de JavaScript (DAP: 4711; CDP: 1337). |

| Forma de `--debugger` | Depura |
| --- | --- |
| sin valor | Las pruebas JVM por JDWP en `127.0.0.1:5005` y las pruebas de JavaScript. |
| `=5005`, `=host:5005` | Solo las pruebas JVM (JDWP). |
| `=dap`, `=cdp` | Solo las pruebas de JavaScript. |

Sintaxis: [Depuración](/docs/debugging). Una opción desconocida o un valor ausente falla antes de que se ejecute nada
([Tareas de compilación](/docs/toolchain/build-tasks#options)).

## Límites

- No hay descubrimiento de pruebas de Python; ejecute unittest o pytest en su lugar
  ([Pruebas de Python](/docs/python-testing)).
- Las pruebas JVM necesitan un manifiesto.
- Sin implementar: instantáneas de `node:test`, `mock.module`, modo de observación, `run()` programático,
  `node:test/reporters`.

API compatible: [API de pruebas de Node](/docs/api-node-test).

## Ejemplos

- [Pruebas de TypeScript](/docs/code-samples#typescript-tests)
- [Pruebas de Kotlin](/docs/code-samples#kotlin-tests)
- [Filtrar pruebas con CEL](/docs/code-samples#filter-tests-with-cel)
- [JUnit XML en CI](/docs/code-samples#junit-xml-in-ci)

Empiece con una plantilla:

```bash
elide init --template java        # Java app with a JUnit test
elide init --template ktjvm       # Kotlin app with a test
```

## Contenedores de prueba compartidos

Declare servicios desechables en `testing.testcontainers`. Elide los inicia antes de los ejecutores de pruebas de
JavaScript, TypeScript y JUnit seleccionados del proyecto, espera a que estén listos y los detiene al terminar la
ejecución de pruebas. Todos los ejecutores de ese proyecto reciben los mismos valores de conexión. Funciona con
independencia de Micronaut o de cualquier otro framework de aplicaciones.

```pkl
amends "elide:project.pkl"
name = "database-tests"

testing {
  testcontainers {
    containers {
      ["postgres"] {
        image = "postgres:17-alpine"
        environment {
          ["POSTGRES_USER"] = "test"
          ["POSTGRES_PASSWORD"] = "test"
          ["POSTGRES_DB"] = "app"
        }
        ports { 5432 }
        wait { timeoutSeconds = 90 }
      }
    }
    environment {
      ["DATABASE_HOST"] = "${postgres.host}"
      ["DATABASE_PORT"] = "${postgres.port.5432}"
      ["JDBC_URL"] = "jdbc:postgresql://${postgres.host}:${postgres.port.5432}/app"
    }
  }
}
```

Lea estos valores con `process.env` en JavaScript/TypeScript o con `System.getenv` en Java/Kotlin. Los enlaces
reemplazan las variables de entorno heredadas solo para los ejecutores de pruebas. Un enlace puede incluir
`${name.host}`, `${name.port.CONTAINER_PORT}` o `${name.id}`; las referencias desconocidas fallan antes del arranque.
Los puertos son puertos TCP dentro del contenedor. Testcontainers asigna puertos libres del host, así que las
ejecuciones concurrentes no necesitan reservar puertos fijos. Los miembros de un espacio de trabajo tienen conjuntos de
contenedores independientes.

Cada contenedor admite `image`, una lista opcional de argumentos `command`, `environment`, `ports` y `wait`:

| Estrategia de espera | Ajustes obligatorios | Comportamiento |
| --- | --- | --- |
| `"port"` (predeterminada) | `ports` no vacío | Espera a que los puertos expuestos escuchen |
| `"http"` | `wait.port` con un puerto expuesto | GET a `wait.path` (predeterminado `/`), esperando `wait.status` (predeterminado `200`) |
| `"log"` | `wait.pattern` | Espera una coincidencia de la expresión regular de Java en los registros del contenedor |

`wait.timeoutSeconds` vale 60 por defecto. El `startupTimeoutSeconds` global vale 300 por defecto e incluye las
descargas de imágenes y todas las comprobaciones de disponibilidad. Los fallos de arranque hacen fallar la ejecución de
pruebas. Los argumentos del comando del contenedor se pasan tal cual; use un comando de shell explícito dentro del
contenedor si lo necesita.

Se necesitan un daemon compatible con Docker y un JDK 17 o posterior que admita lanzar archivos fuente. Elide usa su
cadena de herramientas JVM configurada y resuelve Testcontainers por separado de las dependencias de la aplicación en el
primer uso. Se heredan los ajustes de conexión de Docker como `DOCKER_HOST`. La CLI nativa de Elide también usa esta
vía; Testcontainers se ejecuta en una JVM auxiliar. No añade nada al JAR de su aplicación ni a su Native Image.

`elide install` y la compilación no inician contenedores. `elide test` mantiene la selección de pruebas, los informes y
la cobertura habituales; `elide build test` también admite contenedores en las tareas de prueba JVM. La limpieza se
ejecuta tras un éxito, un fallo o una cancelación. El proceso auxiliar vigila la conexión con su padre, y el resource
reaper de Testcontainers se ocupa de los recursos de Docker huérfanos. Mantenga el resource reaper activado en CI.

Los archivos de sesión están en `.dev/testcontainers/`. Las peticiones que contienen valores de entorno de los
contenedores se eliminan después de que el proceso auxiliar las lea y de nuevo durante la limpieza. Los registros del
proceso auxiliar se conservan allí para el diagnóstico; pueden contener salida de la biblioteca de contenedores. En
sistemas POSIX, los directorios de sesión son privados.

El ejemplo de proyecto `testcontainers` contiene pruebas de JavaScript y JUnit contra un único contenedor HTTP
compartido. Ejecútelo con `elide test`.
