Node modules и npm для QA-инженеров: что нужно знать

Когда клонируешь репозиторий с тестами Playwright и получаешь Cannot find module '@playwright/test', причина одна: забыл запустить npm install. Папка node_modules никогда не коммитится в репозиторий, потому что весит несколько сотен мегабайт, а npm install пересоздаёт её из package.json за секунды. Вторая частая ошибка, Executable doesn't exist at /home/user/.cache/ms-playwright/chromium-XXX, означает что бинарники браузеров устарели и нужен npx playwright install. Гайд объясняет что контролируют package.json, package-lock.json и node_modules, какие команды запускать регулярно, и что означают префиксы ^ и ~ перед версиями пакетов.

Что такое npm

Когда разработчик пишет полезный код, он публикует его как пакет на npm. Остальные устанавливают этот пакет вместо того чтобы писать то же самое с нуля.

Playwright, TypeScript, ESLint, Faker.js, dotenv: всё это npm-пакеты которые составляют типичный стек автоматизации тестирования.

Файл package.json

В каждом Node.js-проекте есть package.json. Это дескриптор проекта: что это за проект, что ему нужно и как его запускать.

Типичный package.json Playwright-проекта выглядит так:

{
  "name": "my-playwright-tests",
  "version": "1.0.0",
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:ui": "npx playwright test --ui"
  },
  "devDependencies": {
    "@playwright/test": "^1.44.0",
    "typescript": "^5.4.5"
  }
}

Основные секции

• name: название проекта
• scripts: команды которые запускаются через npm run
• devDependencies: пакеты нужные только в разработке (тест-инструменты, линтеры)
• dependencies: пакеты нужные в продакшне (в проектах только с тестами не используется)

dependencies и devDependencies

| | dependencies | devDependencies |

|-|----------------|------------------|

| Когда нужны | В продакшне (запуск приложения) | Только в разработке (сборка, тесты, линтинг) |

| Примеры | express, react, axios | playwright, typescript, eslint |

| Флаг установки | npm install package-name | npm install -D package-name |

В QA-репозиториях почти всё идёт в devDependencies. Ты строишь инструментарий для тестирования, не продакшн-приложение.

Папка node_modules

Когда запускаешь npm install, npm:

1. Читает package.json

2. Скачивает все указанные пакеты из реестра

3. Кладёт их в node_modules/

4. Устанавливает ВСЕ ЗАВИСИМОСТИ этих пакетов (и их зависимостей...)

Поэтому node_modules содержит тысячи файлов даже если в проекте всего три прямые зависимости. Playwright, например, тянет за собой десятки пакетов которые использует внутри.

Файлы внутри node_modules не трогай напрямую: ими управляет npm.

В git папку тоже не коммить. Она весит сотни мегабайт. В репозиторий идут package.json и package-lock.json, а клонировавший проект запускает npm install чтобы восстановить node_modules.

Проверь .gitignore:

node_modules/

Эта строка должна там быть. Если нет, добавь.

package-lock.json

При установке пакетов npm создаёт или обновляет package-lock.json. В нём записаны точные версии каждого установленного пакета, включая транзитивные зависимости.

Основные npm-команды

# Установить все зависимости из package.json
npm install

# Установить пакет и добавить в devDependencies
npm install -D @faker-js/faker

# Установить пакет и добавить в dependencies
npm install dotenv

# Удалить пакет
npm uninstall @faker-js/faker

# Обновить все пакеты до последних совместимых версий
npm update

# Проверить пакеты на известные уязвимости
npm audit

# Исправить уязвимости автоматически (где возможно)
npm audit fix

# Запустить скрипт из package.json
npm run test
npm run test:headed

# Список всех установленных пакетов
npm list --depth=0

# Версия конкретного пакета
npm list playwright

Команда npx

# Запустить тест-раннер Playwright (использует локальную версию из node_modules)
npx playwright test

# Установить браузеры Playwright
npx playwright install

# Открыть UI-режим Playwright
npx playwright test --ui

# Запустить codegen
npx playwright codegen https://lab.becomeqa.com

Когда запускаешь npx playwright test, команда находит Playwright в локальной папке node_modules/.bin/ и запускает именно его. Так ты используешь версию проекта, а не глобально установленную.

Настройка нового Playwright-проекта с нуля

# Создать директорию и войти в неё
mkdir my-test-project && cd my-test-project

# Инициализировать npm-проект (создаёт package.json)
npm init -y

# Установить Playwright
npm init playwright@latest

# Готово — Playwright устанавливает себя и зависимости

Если добавляешь Playwright в существующий проект:

npm install -D @playwright/test
npx playwright install

Частые ошибки и способы исправления

Ошибка "Cannot find module"

Error: Cannot find module '@playwright/test'

Запусти npm install. Скорее всего клонировал репозиторий и забыл установить зависимости.

Устаревшие браузеры Playwright

Error: Executable doesn't exist at /home/user/.cache/ms-playwright/chromium-XXX

Запусти npx playwright install. Бинарники браузеров нужно обновить.

Уязвимости безопасности

found 3 vulnerabilities (1 moderate, 2 high)

Запусти npm audit fix. Посмотри что обновляется. Для неисправимых уязвимостей проверь: они в devDependencies? Для тестового кода риск ниже.

Конфликты node_modules после git pull

Если кто-то обновил зависимости, твои локальные node_modules могут устареть:

rm -rf node_modules
npm install

Радикально, но всегда работает.

Префиксы версий ^ и ~

В package.json:

"@playwright/test": "^1.44.0"

| Символ | Значение | Пример |

|--------|----------|--------|

| ^1.44.0 | Совместимо с 1.44.0 (обновляет minor и patch) | Принимает 1.45.0, 1.50.0, но не 2.0.0 |

| ~1.44.0 | Примерно 1.44.0 (обновляет только patch) | Принимает 1.44.1, 1.44.9, но не 1.45.0 |

| 1.44.0 | Ровно 1.44.0 | Обновлений нет |

В проектах с тестами стандарт: ^ (каретка). Держит актуальными minor-улучшения и защищает от мажорных ломающих изменений.

Что QA-инженеру нужно знать

Нужно понимать

• Что делает npm install и когда запускать (всегда после клонирования, после обновления package.json)
• Что содержит package.json и как его читать
• Разницу между dependencies и devDependencies
• Как работает npm run test (запускает скрипт test из package.json)
• Почему node_modules не коммитится в git

Не нужно знать

Как публиковать пакеты на npm, как работает реестр пакетов изнутри, и про Yarn или pnpm (альтернативные пакетные менеджеры): они делают то же самое, Playwright работает с любым.

Этого достаточно чтобы настраивать проекты, устанавливать зависимости, запускать тесты и разбираться с типичными проблемами настройки.