Модулі та npm: import/export, package.json

Що таке модуль у JavaScript і навіщо код узагалі ділять на файли?

Модуль (module) — це окремий файл із власною областю видимості: те, що в ньому оголошено, за замовчуванням зовні не видно. Щоб віддати сутність назовні, її треба явно export, а на приймальному боці — import. Без цього механізму весь код жив би в одному глобальному просторі імен, де змінна page з одного тесту мовчки затирала б однойменну з іншого. Для AQA це щоденний інструмент: Page Object описується один раз у файлі, експортується й підтягується в десятки тестів одним рядком, а правка локатора робиться в єдиному місці. По суті це та сама ізоляція й перевикористання, що й інкапсуляція в ООП, тільки на рівні файлів.

Чим CommonJS відрізняється від ES Modules?

Це дві різні системи модулів, а не два стилі одного й того самого. CommonJS (CJS) — історична система Node.js: імпорт через require(), експорт через module.exports; вона синхронна й динамічна, бо require — це звичайний виклик функції під час виконання, тож шлях можна навіть зібрати рядком на льоту. ES Modules (ESM) — стандарт самої мови з ES2015: import / export; вона статична, всі імпорти аналізуються ще до виконання, тому шлях мусить бути літералом. Плата за статичність окупається: інструменти будують граф залежностей наперед і вирізають невикористане (tree-shaking), а ESM підтримує верхньорівневий await. На співбесіді цінують саме розуміння, що це різні механізми з різними правилами резолву, а не питання смаку.

Як Node розуміє, який файл трактувати як CommonJS, а який як ESM?

Вирішує розширення файлу та поле "type" у найближчому package.json. Файл .mjs завжди ESM, .cjs завжди CommonJS — тут двозначності немає. Файл .js трактується за полем "type": без нього діє історичний дефолт CommonJS, а з "type": "module" той самий .js стає ESM. TypeScript-файли .ts Node напряму не виконує — що з них вийде, вирішує компілятор чи ранер за налаштуваннями tsconfig. Практичний наслідок: помилку про модульну систему майже ніколи не правлять у самому тесті — вона про неузгодженість між кодом і оточенням, а не про синтаксис.

Named export чи default export — що обереш у тестовому коді і чому?

У більшості випадків named, і аргумент тут інженерний, а не «як звик». Named export віддає сутність під конкретним іменем, і під тим самим іменем її імпортують у фігурних дужках; default — один на модуль, імпортується без дужок і під будь-яким іменем. Через фіксоване ім'я named краще дружить з рефакторингом і автодоповненням: один клас не назветься LoginPage в одному файлі й Login у сусідньому, а перейменування підхоплюється по всьому проєкту. Named-імпорт за потреби перейменовують через as, а кілька named-експортів зручно збирати у barrel-файл. Не випадково сам Playwright віддає API саме named-експортами — import { test, expect } from '@playwright/test'.

Що таке barrel-файл і навіщо він потрібен?

Barrel-файл (зазвичай index.ts) — це модуль, який нічого не оголошує сам, а лише реекспортує сутності з інших файлів теки, наприклад export * from './LoginPage'. Сенс — дати одну «вхідну точку» до групи модулів: замість кількох імпортів з різних шляхів споживач бере все з однієї теки. Для набору Page Object це означає, що тести імпортують сторінки з pages, не знаючи внутрішньої розкладки файлів, і при перенесенні файлу правиться лише barrel. Мінус — надто великий barrel може тягнути в граф зайве й шкодити tree-shaking, тож у бібліотеках його застосовують обачно.

Які поля package.json важливі для тестового проєкту?

package.json — це паспорт проєкту: name і version ідентифікують його, "type" задає модульну систему для .js, scripts описує команди запуску, а блоки залежностей перелічують, що і якої версії потрібно. Для набору тестів найчастіше живуть devDependencies — Playwright, TypeScript, @types/* — бо самі тести нікуди не постачаються. scripts перетворює довгі команди на короткі імена, які запускають через npm run. Це той файл, який відкривають першим, коли хочуть зрозуміти, як зібрати й прогнати чужий проєкт.

Що таке scripts і чому npm test працює, а npm smoke — ні?

scripts у package.json — це словник іменованих команд: ліворуч ім'я, праворуч те, що виконається. Запускають їх через npm run <ім'я>, наприклад npm run test:smoke. Кілька зарезервованих імен — test, start, stop — мають скорочення без run (npm test), а всі інші, як-от smoke чи report, працюють лише з повним npm run. Усередині скриптів тека node_modules/.bin уже додана в PATH, тому там пишуть просто playwright test, без npx. Це зручно й для читабельності CI-конфігу: одна назва інкапсулює довгий рядок прапорців.

Чим dependencies відрізняються від devDependencies і де в тестовому наборі що?

dependencies — те, без чого продукт не працює в проді; devDependencies — те, що потрібне лише під час розробки й тестування. У тестовому проєкті майже все потрапляє в devDependencies, бо набір тестів — це інструмент, а не продукт, який кудись «постачається»: Playwright, TypeScript, типи @types/node нікому не їдуть у рантайм застосунку. Є ще peerDependencies — вимога до того, хто ставить пакет, уже мати певну залежність потрібної версії; вона потрібна авторам плагінів, а не типовому набору тестів. Плутати цю вісь із private/публічністю пакета не варто: це різні речі — одна про момент, коли залежність потрібна, інша про те, чи публікується пакет.

Що таке semver і що обіцяє кожна частина у 1.48.0?

Semver (semantic versioning) — домовленість про сенс номера у форматі MAJOR.MINOR.PATCH, де кожна частина щось гарантує споживачеві. Зростання MAJOR (1.x.x → 2.0.0) сигналить про ламальні зміни: старий код може перестати працювати. MINOR (1.48.x → 1.49.0) додає нову функціональність, зберігаючи зворотну сумісність. PATCH (1.48.0 → 1.48.1) — виправлення без зміни поведінки. Сенс домовленості в тому, що за номером можна передбачити ризик оновлення, не читаючи весь changelog; на цьому й будуються версійні діапазони в package.json.

Що означає запис ^1.48.0 у package.json і чим він відрізняється від ~1.48.0?

Значок перед версією — це не сама версія, а дозволений діапазон оновлень. Caret ^1.48.0 дозволяє мінор і патч у межах одного мажора, тобто розгортається в >=1.48.0 <2.0.0. Tilde ~1.48.0 вужчий — лише патчі в межах одного мінора, тобто >=1.48.0 <1.49.0. Практичний наслідок для тестів: ^ на всіх залежностях означає, що завтрашня установка може мовчки підтягнути свіжий мінор, і тест «раптом» почервоніє без жодної зміни у твоєму коді. Саме тому одного package.json для відтворюваності замало — потрібен лок-файл, що фіксує конкретику.

Чому для версій 0.x caret поводиться інакше, ніж зазвичай?

Для 0.x caret звужується до поведінки tilde: ^0.2.3 пускає лише патчі й розгортається в >=0.2.3 <0.3.0, а не до наступного мажора. Логіка в тому, що за semver реліз 0.x вважається ще нестабільним, тож кожен мінор до 1.0.0 трактується як потенційно ламальний — і caret обережно тримається в межах поточного мінора. Це класична пастка: інженер очікує, що ^0.2.3 пустить 0.3.0, а він не пускає. На співбесіді знання цього окремого випадку — бонус, що відрізняє поверхневе розуміння діапазонів від справжнього.

Навіщо потрібен package-lock.json і чи треба його комітити?

Комітити треба обов'язково — це і є гарантія відтворюваності. Діапазони ^ і ~ роблять package.json неточним: дві установки з різницею в тиждень легко дадуть різні фактичні версії. Лок-файл закриває цю дірку, фіксуючи повне дерево залежностей — точну версію кожного пакета, і прямого, і транзитивного (залежності залежності), — разом із хешами цілісності й адресами джерел. Це знімок «що саме встановилося», який роблять один раз і кладуть у git. Без нього виникає класика «локально зелено, у CI червоно», де винна не логіка тесту, а те, що агент поставив трохи інші версії.

У чому різниця між npm install і npm ci?

Це майже гарантоване питання, і воно прямо про детермінізм. npm install орієнтується на package.json, розрулює діапазони, за потреби оновлює лок-файл і доставляє відсутнє в node_modules, не чіпаючи вже наявного — це команда для розробки. npm ci (clean install) читає лише package-lock.json, вимагає його наявності й узгодженості з package.json (інакше падає з помилкою, а не «лагодить» тишком), стирає node_modules перед установкою й ставить дерево рівно за локом, ніколи не записуючи лок назад. Через це npm ci детермінований і швидший — тому це стандарт для CI. Коротке правило: локально install, у пайплайні ci.

Що робить npx і чому в npm-скриптах він не потрібен?

npx запускає виконуваний файл (бінарник) пакета: спершу шукає його в локальному node_modules/.bin, а якщо не знаходить — може тимчасово завантажити пакет, виконати й не лишати в системі. Сенс — не засмічувати машину глобальними установками й гарантовано запускати саме ту версію інструмента, що прописана в проєкті, наприклад npx playwright test чи npx playwright install. Усередині scripts він зайвий, бо node_modules/.bin там уже в PATH — тому в маніфесті пишуть просто playwright test, а npx набирають руками в терміналі поза скриптами. Плутанина зазвичай саме тут: люди дублюють npx у скриптах, де він нічого не додає.

Тест зелений локально, а в CI червоний. Як модулі й npm можуть бути причиною?

Перша підозра новачка — флак, але дуже часто винне оточення, а не логіка тесту. Найтиповіший сценарій: лок-файл не закомічений або зігнорований, CI зробив npm install замість npm ci — і поставив трохи інші версії залежностей, на яких поведінка змінилась. Другий варіант — неузгодженість модульних систем: код на ESM запускається там, де ранер чекав CommonJS, і падає ще до тестової логіки. Діагностика йде від оточення до коду: чи закомічений лок, чи стоїть у CI npm ci, чи збігаються версії Node і залежностей. Хто розуміє цей рівень, той не витрачає півдня, «полюючи за примарою» у власному коді тесту.

Помилка «Cannot use import statement outside a module» — де її насправді лікують?

Не в самому тесті — це не синтаксична помилка, а неузгодженість модульних систем. Вона означає, що ESM-синтаксис (import/export) виконується в оточенні, яке очікувало CommonJS: розширення файлу, відсутнє "type": "module" або поле module у tsconfig не збігаються з тим, як написаний код. Тому шукати причину треба в конфігурації — tsconfig.json, ранер, поле "type" у package.json, — а не переписувати імпорти в тесті. Це гарний приклад загального принципу: повідомлення виглядає як помилка коду, а насправді вказує на розбіжність між кодом і середовищем виконання.

Чому node_modules не комітять у git, а package-lock.json — комітять?

Бо лок-файл — це компактний рецепт, а node_modules — громіздкий і непереносний результат. package-lock.json фіксує точні версії й хеші, за якими npm ci детерміновано відновить node_modules на будь-якій машині, тож його тримають у репозиторії. Саму теку node_modules кладуть у .gitignore: це сотні мегабайтів згенерованих файлів, частина яких ще й скомпільована під конкретну ОС — нативні модулі, зібрані на macOS, можуть просто не запуститися на Linux-агенті. Тому закомічений node_modules не додає надійності, а лише роздуває репозиторій і створює хибне відчуття відтворюваності. Відтворюваність дає саме пара «закомічений лок + npm ci».

Три кейси, де модулі й npm вирішують, зелений тест чи «полювання за примарою»: читання чужого package.json рядок за рядком і рішення за версійними діапазонами, діагностика «локально зелено, у CI червоно» через лок-файл, і практичний розклад named-експортів із barrel-файлом у наборі Page Object.

Кейс 1. Читаємо package.json тестового проєкту

Ти клонував незнайомий репозиторій. Перше, що дає цілісну картину, — маніфест. Розберемо його по полях, бо кожен рядок відповідає на конкретне питання «як це зібрати й прогнати».

{
  "name": "e2e-tests",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "playwright test",
    "test:smoke": "playwright test --grep @smoke",
    "report": "playwright show-report"
  },
  "devDependencies": {
    "@playwright/test": "^1.48.0",
    "typescript": "~5.6.0",
    "@types/node": "^22.7.0"
  }
}

Що читати і чому:

• "type": "module" — усі файли .js у цьому проєкті трактуються як ESM. Тобто якщо десь виконається CommonJS-код без явного .cjs, він упаде на модульній системі, а не на логіці.
• scripts — npm test запуститься скорочено, а от test:smoke і report тільки через npm run test:smoke / npm run report. Усередині цих рядків немає npx, бо node_modules/.bin уже в PATH.
• Усе в devDependencies — сигнал, що це набір тестів, а не продукт: Playwright, TypeScript і типи потрібні для розробки й прогону, нікуди не «постачаються». Порожній dependencies тут — норма, а не недогляд.
• Значки перед версіями — це діапазони, а не версії. ^1.48.0 пустить мінор і патч у межах 1.x (від 1.48.0), ~5.6.0 — лише патчі 5.6.x. Що саме встановиться, вирішує не цей файл, а лок.

Швидка таблиця, як читати діапазон і що він реально дозволяє:

Практичний висновок: ^ на всіх залежностях без закоміченого лок-файлу — це запрошення до тихого minor-бампу, після якого тест червоніє «сам по собі». Побачив таке в чужому проєкті — перевір, чи є поруч package-lock.json у git.

Кейс 2. «Локально зелено, у CI червоно»: винен лок, а не логіка

Класична картина: у себе на машині весь набір зелений, а пайплайн стабільно валить кілька тестів у тому самому місці. Перша підозра новачка — флак; насправді часто винна розбіжність фактичних версій залежностей.

Швидкий чек-лист діагностики, від оточення до коду:

# 1) Чи закомічений лок-файл узагалі?
git ls-files package-lock.json          # порожньо = його немає в git, це і є діра

# 2) Що робить CI — install чи ci?
grep -R "npm install\|npm ci" .github/  # у пайплайні має бути npm ci, не install

# 3) Локально відтворюємо СЕРЕДОВИЩЕ CI, а не свій node_modules
rm -rf node_modules
npm ci                                   # ставить рівно за локом; впаде, якщо лок неузгоджений
npm test

Що дивитися і чому:

• npm ci падає з помилкою про розбіжність — це діагноз, а не перешкода. Він вимагає, щоб лок був узгоджений із package.json; якщо ні — значить, хтось правив маніфест і не оновив лок. Саме цю неузгодженість CI і ловить, а npm install мовчки «полагодив» би її іншими версіями.
• npm install у пайплайні — червоний прапор. Він розрулює діапазони заново, тож агент легко візьме свіжий мінор, якого не було в тебе локально. Заміна на npm ci часто прибирає «флак» одним рядком.
• Незакомічений лок = кожна машина ставить своє. Локально в тебе давнє дерево, на чистому агенті — найновіше в межах ^. Рецепт: закомітити package-lock.json і скрізь ставити через npm ci.
• Відтворюй CI локально стиранням node_modules. Поки ти ганяєш тести по своєму давньому node_modules, різницю не побачиш. rm -rf node_modules && npm ci ставить те саме дерево, що й агент, — і червоне відтворюється у тебе.

Кейс 3. Named-експорти й barrel-файл у наборі Page Object

Тут видно, чому named-експорти дружніші до тестового коду. Опишемо сторінку named-експортом класу, зберемо теку через barrel-файл і підтягнемо в тест однією точкою входу.

// pages/LoginPage.ts — named export класу (не default)
import { Page, expect } from '@playwright/test';

export class LoginPage {
  constructor(private readonly page: Page) {}

  async openLoginForm(): Promise<void> {
    await this.page.goto('/login');
  }

  async clickOnSubmit(email: string, password: string): Promise<void> {
    await this.page.getByTestId('email').fill(email);
    await this.page.getByTestId('password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }

  async checkThatErrorIsVisible(text: string): Promise<void> {
    await expect(this.page.getByRole('alert')).toHaveText(text);
  }
}

// pages/index.ts — barrel: сам нічого не оголошує, лише реекспортує
export * from './LoginPage';
export * from './DashboardPage';

// tests/login.spec.ts — імпорт з однієї точки входу, а не з кожного файлу
import { test } from '@playwright/test';
import { LoginPage, DashboardPage } from '../pages';

test('невірний пароль показує помилку', async ({ page }) => {
  const loginPage = new LoginPage(page);
  await loginPage.openLoginForm();
  await loginPage.clickOnSubmit('qa@example.com', 'wrong');
  await loginPage.checkThatErrorIsVisible('Invalid credentials');
});

Що дивитися і чому:

• Named-експорт тримає ім'я фіксованим. LoginPage не перетвориться на Login у сусідньому файлі, тож автодоповнення й перейменування по проєкту працюють точно. З default-експортом кожен імпорт міг би назвати клас по-своєму — і рефакторинг це не підхопить.
• Barrel-файл ховає розкладку тек. Тест бере сторінки з ../pages, не знаючи, у якому файлі кожна лежить; перенесення LoginPage.ts в іншу підтеку правиться лише в index.ts, а не в десятках тестів.
• Імпорт із самого Playwright — теж named. import { test } from '@playwright/test' — не випадковість: бібліотека свідомо віддає API named-експортами саме заради стабільних імен і автодоповнення.
• Не зловживай barrel'ом. Надто великий реекспорт тягне в граф зайве й шкодить tree-shaking; для набору Page Object це прийнятно, але в бібліотеці, що публікується, barrel застосовують обачно.

Модулі та import/export

• Можу пояснити, що модуль — це файл із власною областю видимості, і назовні видно лише те, що явно export.
• Знаю різницю між named і default export: named — під фіксованим іменем у фігурних дужках, default — один на модуль і під будь-яким іменем.
• Розумію, чому в тестовому коді зазвичай віддають перевагу named (рефакторинг, автодоповнення, фіксовані імена), і що Playwright віддає API саме так.
• Можу перейменувати named-імпорт через as і знаю, навіщо потрібен barrel-файл (index.ts, що реекспортує решту).

CommonJS проти ES Modules

• Знаю, що це дві РІЗНІ системи модулів, а не стилі: require/module.exports проти import/export.
• Можу пояснити, що CommonJS синхронний і динамічний (шлях можна зібрати рядком), а ESM статичний (шлях — літерал, зате можливий tree-shaking і top-level await).
• Розумію, як Node обирає систему: .mjs завжди ESM, .cjs завжди CJS, .js — за полем "type", а .ts вирішує компілятор/ранер.

package.json і scripts

• Розумію, що package.json — маніфест проєкту: name, version, "type", scripts, блоки залежностей.
• Знаю різницю dependencies vs devDependencies і чому в тестовому наборі майже все — devDependencies (плюс що таке peerDependencies).
• Розумію, чому npm test працює скорочено, а власне ім'я запускають лише через npm run <ім'я>, і що всередині скриптів node_modules/.bin уже в PATH.

Semver і діапазони версій

• Можу розкласти версію на MAJOR.MINOR.PATCH і сказати, що обіцяє зростання кожної частини.
• Знаю різницю ^ vs ~: caret пускає мінор+патч (>=1.48.0 <2.0.0), tilde — лише патч (>=1.48.0 <1.49.0).
• Пам'ятаю особливий випадок ^0.x: для нульового мажора caret звужується до патчів, як tilde.
• Розумію практичний ризик ^ на всьому: тихий minor-бамп залежності ламає тести без зміни мого коду.

Лок-файл і відтворюваність

• Можу пояснити, чому ^/~ роблять package.json неточним і що саме цю дірку закриває package-lock.json.
• Знаю, що лок фіксує повне дерево — точні версії прямих і транзитивних залежностей плюс хеші цілісності.
• Знаю різницю npm install vs npm ci: перший оновлює лок і доповнює node_modules (розробка), другий читає лише лок, стирає node_modules, падає при розбіжності й тому детермінований (CI).

npx і структура проєкту

• Можу пояснити, що npx запускає бінарник із node_modules/.bin (або тимчасово тягне пакет) і чому в scripts він зайвий.
• Знаю, що package-lock.json комітять, а node_modules — ні, і чому (рецепт проти громіздкого нативного результату), плюс звідки береться «локально зелено, у CI червоно».
• Можу з голови накидати кістяк проєкту: package.json, лок, node_modules (в ignore), конфіг ранера, tsconfig, теки tests/, pages/, fixtures/.