Конфигурация тестов Bun

Настройте bun test через файл bunfig.toml и опции командной строки. Эта страница документирует доступные опции конфигурации для bun test.

Файл конфигурации

Вы можете настроить поведение bun test, добавив секцию [test] в ваш файл bunfig.toml:

toml

[test]
# Опции здесь

Обнаружение тестов

root

Опция root указывает корневой каталог для обнаружения тестов, переопределяя поведение по умолчанию сканирования от корня проекта.

toml

[test]
root = "src"  # Сканировать тесты только в каталоге src

Это полезно, когда вы хотите:

Ограничить обнаружение тестов конкретными каталогами
Исключить определённые части вашего проекта из сканирования тестов
Организовать тесты в конкретной подкаталогной структуре

Примеры

toml

[test]
# Запускать тесты только в каталоге src
root = "src"

# Запускать тесты в конкретном каталоге тестов
root = "tests"

# Запускать тесты в нескольких конкретных каталогах (в настоящее время не поддерживается - используйте patterns)
# root = ["src", "lib"]  # Этот синтаксис не поддерживается

Скрипты предварительной загрузки

Загружайте скрипты перед запуском тестов, используя опцию preload:

toml

[test]
preload = ["./test-setup.ts", "./global-mocks.ts"]

Это эквивалентно использованию --preload в командной строке:

bash

bun test --preload ./test-setup.ts --preload ./global-mocks.ts

Распространённые варианты использования предварительной загрузки

// Глобальная настройка теста
import { beforeAll, afterAll } from "bun:test";

beforeAll(() => {
  // Настроить тестовую базу данных
  setupTestDatabase();
});

afterAll(() => {
  // Очистка
  cleanupTestDatabase();
});

// Глобальные моки
import { mock } from "bun:test";

// Мок переменных окружения
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// Мок внешних зависимостей
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

Таймауты

Таймаут по умолчанию

Установите таймаут по умолчанию для всех тестов:

toml

[test]
timeout = 10000  # 10 секунд (по умолчанию 5000мс)

Это применяется ко всем тестам, если не переопределено индивидуальными таймаутами тестов:

// Этот тест будет использовать таймаут по умолчанию из bunfig.toml
test("uses default timeout", () => {
  // реализация теста
});

// Этот тест переопределяет таймаут по умолчанию
test("custom timeout", () => {
  // реализация теста
}, 30000); // 30 секунд

Репортёры

Репортёр JUnit

Настройте путь вывода файла репортёра JUnit непосредственно в файле конфигурации:

toml

[test.reporter]
junit = "path/to/junit.xml"  # Путь вывода для отчёта JUnit XML

Это дополняет флаги CLI --reporter=junit и --reporter-outfile:

bash

# Эквивалентная команда в командной строке
bun test --reporter=junit --reporter-outfile=./junit.xml

Несколько репортёров

Вы можете использовать несколько репортёров одновременно:

bash

# Подход через CLI
bun test --reporter=junit --reporter-outfile=./junit.xml

# Подход через файл конфигурации

toml

[test.reporter]
junit = "./reports/junit.xml"

[test]
# Также включить отчётность по покрытию
coverage = true
coverageReporter = ["text", "lcov"]

Использование памяти

Режим smol

Включите режим экономии памяти --smol специально для средства запуска тестов:

toml

[test]
smol = true  # Уменьшить использование памяти во время запуска тестов

Это эквивалентно использованию флага --smol в командной строке:

bash

bun test --smol

Режим smol уменьшает использование памяти за счёт:

Использования меньшего объёма памяти для кучи JavaScript
Более агрессивной сборки мусора
Уменьшения размеров буферов, где это возможно

Это полезно для:

Сред CI с ограниченной памятью
Больших наборов тестов, потребляющих значительную память
Сред разработки с ограничениями памяти

Выполнение тестов

concurrentTestGlob

Автоматически запускайте тестовые файлы, соответствующие glob-шаблону, с включённым параллельным выполнением тестов. Это полезно для постепенной миграции наборов тестов на параллельное выполнение или для запуска конкретных типов тестов параллельно.

toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # Запускать файлы, соответствующие этому шаблону, параллельно

Тестовые файлы, соответствующие этому шаблону, будут вести себя так, как будто был передан флаг --concurrent, запуская все тесты внутри этих файлов параллельно. Это позволяет вам:

Постепенно мигрировать ваш набор тестов на параллельное выполнение
Запускать интеграционные тесты параллельно, сохраняя модульные тесты последовательными
Разделять быстрые параллельные тесты от тестов, требующих последовательного выполнения

Флаг CLI --concurrent переопределит эту настройку при указании, заставляя все тесты выполняться параллельно независимо от glob-шаблона.

randomize

Запускайте тесты в случайном порядке для выявления тестов со скрытыми зависимостями:

toml

[test]
randomize = true

seed

Укажите сид для воспроизводимого случайного порядка тестов. Требуется randomize = true:

toml

[test]
randomize = true
seed = 2444615283

rerunEach

Повторно запускайте каждый тестовый файл несколько раз для выявления нестабильных тестов:

toml

[test]
rerunEach = 3

Опции покрытия

Базовые настройки покрытия

toml

[test]
# Включить покрытие по умолчанию
coverage = true

# Установить репортёр покрытия
coverageReporter = ["text", "lcov"]

# Установить каталог вывода покрытия
coverageDir = "./coverage"

Пропуск тестовых файлов из покрытия

Исключите файлы, соответствующие шаблонам тестов (например, *.test.ts), из отчёта о покрытии:

toml

[test]
coverageSkipTestFiles = true  # Исключить тестовые файлы из отчётов о покрытии

Пороги покрытия

Порог покрытия может быть указан либо как число, либо как объект с конкретными порогами:

toml

[test]
# Простой порог - применяется к строкам, функциям и утверждениям
coverageThreshold = 0.8

# Подробные пороги
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }

Установка любого из них включает fail_on_low_coverage, вызывая неудачу запуска теста, если покрытие ниже порога.

Примеры порогов

toml

[test]
# Требовать 90% покрытия повсеместно
coverageThreshold = 0.9

# Различные требования для различных метрик
coverageThreshold = {
  lines = 0.85,      # 85% покрытия строк
  functions = 0.90,  # 90% покрытия функций
  statements = 0.80  # 80% покрытия утверждений
}

Шаблоны игнорирования путей покрытия

Исключите конкретные файлы или шаблоны файлов из отчётов о покрытии, используя glob-шаблоны:

toml

[test]
# Одиночный шаблон
coveragePathIgnorePatterns = "**/*.spec.ts"

# Несколько шаблонов
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

Файлы, соответствующие любому из этих шаблонов, будут исключены из расчёта покрытия и отчётности. См. документацию по покрытию для получения дополнительных деталей и примеров.

Распространённые шаблоны игнорирования

toml

[test]
coveragePathIgnorePatterns = [
  # Тестовые файлы
  "**/*.test.ts",
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Файлы конфигурации
  "*.config.js",
  "*.config.ts",
  "webpack.config.*",
  "vite.config.*",

  # Вывод сборки
  "dist/**",
  "build/**",
  ".next/**",

  # Сгенерированный код
  "generated/**",
  "**/*.generated.ts",

  # Vendor/third-party
  "vendor/**",
  "third-party/**",

  # Утилиты, не требующие тестирования
  "src/utils/constants.ts",
  "src/types/**"
]

Обработка sourcemap

Внутренне Bun транспилирует каждый файл. Это означает, что покрытие кода также должен проходить через sourcemaps, прежде чем они смогут быть отчитаны. Мы предоставляем это как флаг, чтобы позволить вам отказаться от этого поведения, но это будет запутанным, потому что во время процесса транспиляции Bun может перемещать код и изменять имена переменных. Эта опция в основном полезна для отладки проблем с покрытием.

toml

[test]
coverageIgnoreSourcemaps = true  # Не использовать sourcemaps для анализа покрытия

Наследование настроек установки

Команда bun test наследует соответствующие сетевые и установочные конфигурации (registry, cafile, prefer, exact и т.д.) из секции [install] файла bunfig.toml. Это важно, если тестам нужно взаимодействовать с приватными реестрами или требуются конкретные поведения установки, запускаемые во время выполнения теста.

toml

[install]
# Эти настройки наследуются bun test
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# Конфигурация специфичная для тестов
coverage = true
timeout = 10000

Переменные окружения

Вы также можете установить переменные окружения в вашей конфигурации, которые влияют на поведение тестов:

toml

[env]
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
LOG_LEVEL = "error"

[test]
coverage = true

Полный пример конфигурации

Вот комплексный пример, показывающий все доступные опции конфигурации тестов:

toml

[install]
# Настройки установки, наследуемые тестами
registry = "https://registry.npmjs.org/"
exact = true

[env]
# Переменные окружения для тестов
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
API_URL = "http://localhost:3001"
LOG_LEVEL = "error"

[test]
# Обнаружение тестов
root = "src"
preload = ["./test-setup.ts", "./global-mocks.ts"]

# Настройки выполнения
timeout = 10000
smol = true

# Конфигурация покрытия
coverage = true
coverageReporter = ["text", "lcov"]
coverageDir = "./coverage"
coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**"
]

# Продвинутые настройки покрытия
coverageIgnoreSourcemaps = false

# Конфигурация репортёра
[test.reporter]
junit = "./reports/junit.xml"

Поведение переопределения CLI

Опции командной строки всегда переопределяют настройки файла конфигурации:

toml

[test]
timeout = 5000
coverage = false

bash

# Эти флаги CLI переопределяют файл конфигурации
bun test --timeout 10000 --coverage
# timeout будет 10000мс и покрытие будет включено

Условная конфигурация

Вы можете использовать различные конфигурации для различных сред:

toml

[test]
# Конфигурация тестов по умолчанию
coverage = false
timeout = 5000

# Переопределение для среды CI
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000

Затем в CI:

bash

# Использовать настройки специфичные для CI
bun test --config=ci

Валидация и устранение неполадок

Неверная конфигурация

Bun предупредит о неверных опциях конфигурации:

toml

[test]
invalidOption = true  # Это создаст предупреждение

Распространённые проблемы конфигурации

Разрешение путей: Относительные пути в конфигурации разрешаются относительно расположения файла конфигурации
Сопоставление шаблонов: Glob-шаблоны используют стандартный синтаксис glob
Несоответствия типов: Убедитесь, что числовые значения не заключены в кавычки, если они не должны быть строками

toml

[test]
# Правильно
timeout = 10000

# Неправильно - будет обработано как строка
timeout = "10000"

Отладка конфигурации

Чтобы увидеть, какая конфигурация используется:

bash

# Показать эффективную конфигурацию
bun test --dry-run

# Подробный вывод для просмотра загрузки конфигурации
bun test --verbose

Файл конфигурации ​

Обнаружение тестов ​

root ​

Примеры ​

Скрипты предварительной загрузки ​

Распространённые варианты использования предварительной загрузки ​

Таймауты ​

Таймаут по умолчанию ​

Репортёры ​

Репортёр JUnit ​

Несколько репортёров ​

Использование памяти ​

Режим smol ​

Выполнение тестов ​

concurrentTestGlob ​

randomize ​

seed ​

rerunEach ​

Опции покрытия ​

Базовые настройки покрытия ​

Пропуск тестовых файлов из покрытия ​

Пороги покрытия ​

Примеры порогов ​

Шаблоны игнорирования путей покрытия ​

Распространённые шаблоны игнорирования ​

Обработка sourcemap ​

Наследование настроек установки ​

Переменные окружения ​

Полный пример конфигурации ​

Поведение переопределения CLI ​

Условная конфигурация ​

Валидация и устранение неполадок ​

Неверная конфигурация ​

Распространённые проблемы конфигурации ​

Отладка конфигурации ​

Файл конфигурации

Обнаружение тестов

root

Примеры

Скрипты предварительной загрузки

Распространённые варианты использования предварительной загрузки

Таймауты

Таймаут по умолчанию

Репортёры

Репортёр JUnit

Несколько репортёров

Использование памяти

Режим smol

Выполнение тестов

concurrentTestGlob

randomize

seed

rerunEach

Опции покрытия

Базовые настройки покрытия

Пропуск тестовых файлов из покрытия

Пороги покрытия

Примеры порогов

Шаблоны игнорирования путей покрытия

Распространённые шаблоны игнорирования

Обработка sourcemap

Наследование настроек установки

Переменные окружения

Полный пример конфигурации

Поведение переопределения CLI

Условная конфигурация

Валидация и устранение неполадок

Неверная конфигурация

Распространённые проблемы конфигурации

Отладка конфигурации