---
type: JS Module
title: test-helpers.mjs
resource: npm/scripts/utils/test-helpers.mjs
docgen:
  crc: afeeed1b
---

## Огляд

Допоміжні функції для тестів скриптів пакета `@nitra/cursor`: ізольовані тимчасові каталоги, запис JSON за абсолютним шляхом і керування видимістю зовнішніх бінарників через `PATH`. Жодна з функцій не мутує `process.cwd()` — тест явно будує шляхи через `join(dir, …)` і передає `cwd` дочірнім процесам (контракт перевіряється правилом `no-process-chdir`).

## Публічний API

- `withTmpDir(fn)` — створює тимчасовий каталог, передає його абсолютний шлях у `fn`, після завершення видаляє каталог (з повторами на випадок гонки з паралельними git-hook-записами всередині каталогу).
- `writeJson(path, data)` — записує JSON з відступами й завершальним переносом рядка; шлях має бути абсолютним, інакше кидає помилку.
- `ensureDir(path)` — створює вкладені каталоги за абсолютним шляхом; відносний шлях — помилка.
- `withBinStubInPath(bin, fn)` — створює тимчасовий каталог зі стабом `<bin>` (`<bin>.exe` на Windows), що завершується з кодом 0, додає каталог на початок `PATH` на час `fn`, потім відновлює `PATH` і прибирає стаб. Реальний бінарник не запускається: і машини без інструмента, і повільні мережево-залежні інструменти (наприклад, `kubescape`, який на старті тягне артефакти з хмарних API десятки секунд) отримують детермінований швидкий прогін.
- `withShellcheckStubInPath(fn)` — спеціалізація `withBinStubInPath` для `shellcheck` (перевірки `check ga` на машинах без реального shellcheck).
- `withBinRemovedFromPath(bin, fn)` — виконує `fn` із `PATH`, з якого прибрані всі каталоги з виконуваним `<bin>`; решта `PATH` (git, bun) лишається. На час `fn` виставляє `N_CURSOR_NO_AUTO_INSTALL=1`, щоб `ensureTool` не запускав реальний brew/scoop/curl-install. Для негативних тестів «fail, коли інструмента нема».

## Гарантії поведінки

- `PATH` і `N_CURSOR_NO_AUTO_INSTALL` завжди відновлюються до початкових значень навіть при винятку в `fn` (`finally`).
- Тимчасові каталоги (`withTmpDir`, стаби) прибираються після завершення `fn`.
- Функції запису (`writeJson`, `ensureDir`) відхиляють відносні шляхи — захист від залежності тестів від `process.cwd()`.

## Де використовується

Інтеграційні тести `npm/tests/*` та тести правил (`rules/ga/workflows`, `rules/k8s` тощо), що спавнять зовнішні інструменти або працюють із тимчасовими деревами.
