# Тестирование

`elide test` запускает файлы `node:test` на JavaScript и TypeScript и тесты JUnit.

```bash
elide test
```

Упавший тест делает код выхода ненулевым.

<img src="/assets/demos/test.gif" alt="Обнаружение и запуск тестов JavaScript в Elide" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## JavaScript и TypeScript

Тесты используют API `node:test` и не требуют манифеста. Файл считается тестом, если он соответствует `*.test.*`,
`*.spec.*`, `*_test.*` или `*_spec.*` либо лежит в `test`, `tests` или `__tests__`. Расширения: `.js`, `.mjs`, `.cjs`,
`.ts`, `.mts`, `.cts`.

Обнаружение пропускает скрытые каталоги, каталоги зависимостей и результатов сборки. Оно останавливается на любом
вложенном проекте (каталоге с `elide.pkl`, `package.json`, `pom.xml` или `requirements.txt`), поэтому из корня
рабочего пространства тесты участников не находятся. Чтобы запустить их, укажите путь.

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

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

## Тесты JVM

Тесты JVM выполняются на JUnit Platform и требуют `elide.pkl`. `src/test` — набор исходников для тестов по умолчанию;
объявленный набор исходников типа `test` заменяет его ([Наборы исходников](/docs/toolchain/source-sets)).

- Тестовые наборы получают `testPackages` и зависимости основного набора.
- Встроенные библиотеки JUnit добавляются по умолчанию. `jvm.features.testing = false` убирает и API JUnit для
  компиляции, и встроенную среду выполнения; тогда для запуска тестов JVM нужен консольный лаунчер JUnit
  (`junit-platform-console`) в `testPackages`, иначе запуск завершается ошибкой. На запуски без тестов JVM это не
  влияет.
- `processors` применяются к тестовым исходникам.
- Тестовая JVM получает `jvm.flags` и `jvm.defs` (как `-D`).
- Зависимости `modules` тестового и основного наборов попадают в `--module-path` с `--add-modules=ALL-MODULE-PATH`.
- Настройки параллелизма в `junit-platform.properties` на тестовом classpath переопределяют `--concurrency`.

## Выбор тестов

Пути, каталоги или glob-шаблоны сужают набор тестов JavaScript и TypeScript:

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

С аргументами-путями тесты JVM пропускаются, и выводится `Path filtering unsupported for JVM tests: <paths>`. `-t`
отбирает тесты по имени в обоих средствах запуска тестов:

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

Тесты JVM принимают селекторы JUnit и выражения тегов:

```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 — селекторы JUnit в проекте на Kotlin" width="1591" height="873" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`--include-tag='slow & !flaky'` — одно выражение. Фильтры тегов применяются после селекторов.

## Вывод и отчёты

Ход выполнения выводится в stderr, итоговая сводка — в stdout:

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

Отчёты записываются в `.dev/reports/tests/<language>/<source-set>/`. `testing.reports` в `elide.pkl` включает их без
флага:

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

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

### Вывод TAP

`--reporter=tap` превращает stdout в чистый поток TAP 13:

```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>` открывает тест; строки его вывода имеют вид `# out <id>: <text>`. `# out: <text>` не относится ни к
  одному тесту.
- Тестовые точки нумеруются `1..N` в порядке завершения. Сопоставляйте точки с тестами по строке `# start`, а не по
  номеру.
- Блок YAML появляется только у падений с подробностями; `severity` — код ошибки средства запуска тестов, если он
  есть.
- Stderr не оборачивается: `elide test --reporter=tap 2>&1` не является корректным TAP.
- JVM: вывод привязывается к своему тесту, только пока выполняется ровно один тест. С `--concurrency` больше 1 или с
  `junit-platform.properties` в проекте он остаётся непривязанным.
- JavaScript: `console.log` внутри теста или на верхнем уровне после импорта `node:test` оборачивается. Вывод до этого
  импорта выводится как есть. Вывод хука относится к тесту, который хук оборачивает; `t.diagnostic` оборачивается как
  `# out`.

Задайте `ELIDE_TEST_METADATA=1` вместе с `--reporter=tap`, чтобы перед результатами выводились версионированные
JSON-комментарии `# elide-test:`. Они содержат номер результата, идентификатор запуска, движок, исходный файл, набор
тестов, статус и измеренную длительность в миллисекундах. Идентификатор запуска связывает параллельные тесты с их
перехваченным выводом, даже когда имена повторяются, а порядок завершения отличается. Обычные потребители TAP
игнорируют эти комментарии; вывод по умолчанию и отчёты по наборам тестов не меняются.

## Покрытие

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

В рабочем пространстве проекта Tern выберите **Test**, затем **Run with coverage**. Вкладка **Coverage** появляется,
когда запуск измерен: в ней перечислены измеренные файлы с покрытыми, частично покрытыми и непокрытыми строками, а
текущий исходный код выбранного файла показан с подсветкой каждой измеренной строки по её покрытию. Строки, которые
среда выполнения никогда не измеряет (закрывающие скобки, пустые строки, комментарии), получают более светлый оттенок,
если блок, к которому они относятся, выполнялся: ближайшая измеренная строка над ними в этом блоке покрыта, и между ними
нет непокрытых строк. В процентах они не учитываются. **Next uncovered** и **Previous uncovered** (`n` и `p`)
переходят между пробелами в покрытии, а **Open line N in Elide source** открывает файл на строке в фокусе; сохраните
изменения и выберите **Run again**, чтобы измерить обновлённый код. История запусков хранит предыдущие измерения, а
недоступные данные о ветвлениях показываются отдельно от нулевого покрытия.

Кнопки открытия в представлении Tests (**Open in Elide source** и **Open** на карточке теста) реагируют только на
щелчок. Терминальная программа, рисующая представление Tern, не может попросить Tern открыть ссылку по нажатию клавиши,
поэтому Enter не открывает выбранное; щёлкните кнопку или щёлкните с ⌘ по связанному имени файла. См.
[Покрытие в Tern](/docs/tern-coverage).

Интеграции тестов могут при запросе покрытия задать в `ELIDE_COVERAGE_REPORT` путь к файлу, уникальный для запуска.
Elide атомарно записывает версионированный JSON-артефакт с измеренными исходными файлами, покрытием исполняемых строк
и, где доступно, счётчиками ветвлений. Этот артефакт не зависит от настроенных файлов отчётов LCOV или JaCoCo.
Интеграции следует выделять новый путь для каждого запуска.

Отпечатки исходников JavaScript описывают текст, который вычислила среда выполнения, даже если файл изменился до записи
отчёта. Покрытие — это измерение именно этой версии исходника. Отсутствие отпечатка или измерения ветвлений означает
недоступные данные; оно не означает, что текущий файл совпадает или что ни одна ветвь не выполнялась. Покрытие строк
фиксирует, была ли строка покрыта, а не сколько раз она выполнялась.

Покрытие JVM записывается в `.dev/reports/coverage/jvm/<task>/` в формате HTML, XML или CSV; покрытие JavaScript и
TypeScript — в формате LCOV, в `.dev/reports/coverage/js/lcov.info` для тестов и
`.dev/reports/coverage/js/run/lcov.info` для запусков. В консоль выводится одна общая сводка. Блок `coverage` верхнего
уровня собирает покрытие без флага:

```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 }
  }
}
```

| Свойство | Значение | По умолчанию |
| --- | --- | --- |
| `enabled` | Собирать без `--coverage`. | `false` |
| `scope` | `"tests"`, `"runs"` или `"all"`; `--coverage` всегда покрывает свою задачу. | `"tests"` |
| `jvm.reports` | `Coverage.htmlReport()`, `xmlReport()`, `csvReport()`. | нет |
| `jvm.excludes` | Шаблоны классов (`*`, `?`), которые не инструментируются, например сгенерированный код. | нет |
| `jvm.minimum.line`, `jvm.minimum.branch` | Минимальная доля покрытия, от `0.0` до `1.0`. | нет |
| `js.paths` | Корни исходников для отчёта; пустой список означает весь проект. | нет |
| `js.minimum.line` | Минимальная доля покрытых строк, от `0.0` до `1.0`. | нет |

Когда запуск собирает покрытие, `elide test` завершается с ненулевым кодом, если `minimum` не достигнут, и называет
свойство, требуемую и измеренную долю. Минимум, которому нечего измерять, например при отсутствии тестов JVM или
проанализированных классов, тоже приводит к ошибке. Отчёты записываются в любом случае. Доли для JVM учитывают каждый
класс, который анализирует тестовый запуск.

С покрытием `elide run` запускает отдельный процесс JVM.

## Параметры

| Параметр | Действие |
| --- | --- |
| `-t REGEX` | Отбирать по имени теста или объемлющего набора тестов. |
| `--where CEL` | JavaScript: запускать тесты, для которых истинно выражение [CEL](/docs/api-cel) над `name`, `parents` и `file`. |
| `--select=SELECTOR` | JVM: селектор `class:`, `method:` или `package:`; можно повторять. |
| `--include-tag=EXPR` | JVM: запускать тесты с подходящими тегами; повторы объединяются через ИЛИ. |
| `--exclude-tag=EXPR` | JVM: пропускать тесты с подходящими тегами; повторы объединяются через И. |
| `--bail[=N]` | Остановиться после `N` падений (по умолчанию 1). |
| `--test-timeout=MS` | Тайм-аут одного теста по умолчанию. |
| `--timeout DURATION` | Ограничение времени на весь вызов (глобальный параметр). |
| `--only` | Запускать только тесты, помеченные `.only`. |
| `--concurrency=N` | Запускать файлы или классы JVM параллельно. По умолчанию `1`; `0` недопустимо. |
| `--coverage` | Собирать покрытие; см. [Покрытие](#coverage). |
| `--reporter=junit` | Писать отчёты JUnit XML. |
| `--reporter=tap` | Писать TAP 13 в stdout (и в `--reporter-outfile`). |
| `--reporter-outfile=DIR` | Каталог отчётов. |
| `--debugger[=MODE\|ADDRESS]` | Подключить отладчик; см. ниже. |
| `--debugger-host=HOST`, `--debugger-port=PORT` | Адрес отладчика JavaScript (DAP: 4711; CDP: 1337). |

| Форма `--debugger` | Что отлаживает |
| --- | --- |
| без значения | Тесты JVM через JDWP на `127.0.0.1:5005` и тесты JavaScript. |
| `=5005`, `=host:5005` | Только тесты JVM (JDWP). |
| `=dap`, `=cdp` | Только тесты JavaScript. |

Синтаксис: [Отладка](/docs/debugging). Неизвестный параметр или пропущенное значение приводит к ошибке до начала запуска
([Задачи сборки](/docs/toolchain/build-tasks#options)).

## Ограничения

- Обнаружения тестов Python нет; запускайте unittest или pytest ([Тесты Python](/docs/python-testing)).
- Тестам JVM нужен манифест.
- Не реализовано: снапшоты `node:test`, `mock.module`, режим наблюдения, программный `run()`, `node:test/reporters`.

Поддерживаемый API: [API тестов Node](/docs/api-node-test).

## Примеры

- [Тесты на TypeScript](/docs/code-samples#typescript-tests)
- [Тесты на Kotlin](/docs/code-samples#kotlin-tests)
- [Фильтрация тестов с CEL](/docs/code-samples#filter-tests-with-cel)
- [JUnit XML в CI](/docs/code-samples#junit-xml-in-ci)

Начните с шаблона:

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

## Общие тестовые контейнеры

Объявите временные сервисы в `testing.testcontainers`. Elide запускает их перед выбранными средствами запуска тестов
JavaScript, TypeScript и JUnit проекта, ждёт их готовности и останавливает по завершении тестового запуска. Все
средства запуска в этом проекте получают одинаковые параметры подключения. Это работает независимо от Micronaut или
любого другого фреймворка приложений.

```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"
    }
  }
}
```

Читайте эти значения через `process.env` в JavaScript/TypeScript или `System.getenv` в Java/Kotlin. Привязки
переопределяют унаследованные переменные окружения только для средств запуска тестов. Привязка может содержать
`${name.host}`, `${name.port.CONTAINER_PORT}` или `${name.id}`; неизвестные ссылки приводят к ошибке до запуска.
Порты — это TCP-порты внутри контейнера. Testcontainers назначает свободные порты хоста, поэтому параллельным запускам
не нужно резервировать фиксированные порты. У участников рабочего пространства независимые наборы контейнеров.

Каждый контейнер поддерживает `image`, необязательный список аргументов `command`, `environment`, `ports` и `wait`:

| Стратегия ожидания | Обязательные настройки | Поведение |
| --- | --- | --- |
| `"port"` (по умолчанию) | Непустой `ports` | Ждёт, пока открытые порты начнут принимать соединения |
| `"http"` | `wait.port` с открытым портом | GET к `wait.path` (по умолчанию `/`) с ожиданием `wait.status` (по умолчанию `200`) |
| `"log"` | `wait.pattern` | Ждёт совпадения регулярного выражения Java в логах контейнера |

`wait.timeoutSeconds` по умолчанию равен 60. Общий `startupTimeoutSeconds` по умолчанию равен 300 и включает загрузку
образов и все проверки готовности. Ошибки запуска приводят к провалу тестового запуска. Аргументы команды контейнера
передаются напрямую; при необходимости используйте явную команду оболочки внутри контейнера.

Нужны Docker-совместимый демон и JDK 17 или новее с поддержкой запуска исходных файлов. Elide использует настроенный
инструментарий JVM и при первом использовании разрешает Testcontainers отдельно от зависимостей приложения. Параметры
подключения к Docker, например `DOCKER_HOST`, наследуются. Этот путь использует и нативный CLI Elide; Testcontainers
работает во вспомогательной JVM. В JAR вашего приложения и в Native Image ничего не добавляется.

`elide install` и компиляция не запускают контейнеры. `elide test` сохраняет обычный выбор тестов, отчёты и покрытие;
`elide build test` тоже поддерживает контейнеры для задач тестов JVM. Очистка выполняется после успеха, ошибки или
отмены. Вспомогательный процесс следит за соединением с родительским процессом, а resource reaper Testcontainers
убирает осиротевшие ресурсы Docker. Не отключайте resource reaper в CI.

Файлы сессии хранятся в `.dev/testcontainers/`. Запросы со значениями окружения контейнеров удаляются после того, как
вспомогательный процесс их прочитал, и ещё раз во время очистки. Логи вспомогательного процесса остаются там для
диагностики; в них может быть вывод библиотеки контейнеров. В POSIX-системах каталоги сессий закрыты для других
пользователей.

Пример проекта `testcontainers` содержит тесты JavaScript и JUnit, работающие с одним общим HTTP-контейнером.
Запустите его через `elide test`.
