Типичные имена скриптов в package.json и то, как я их запускаю

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

• Названия скриптов

• Запуск и тестирование

• CI-скрипт 

• Быстрый запуск

  • Стоп точка (Stop dot)

Имена скриптов #

Обычно приложение нужно собрать, обслужить или запустить. Например, в веб-приложении bahmutov/cypress-example-forms у нас есть эти три скрипта на старте:

{
  "scripts": {
    "format": "prettier --write 'cypress/**/*.js'",
    "start": "parcel serve index.html",
    "build": "parcel build index.html"
  }
}

Если вы находитесь в папке проекта, то сможете увидеть все доступные скрипты, выполнив команду npm run

$ npm run
Lifecycle scripts included in cypress-example-forms:
  start
    parcel serve index.html

available via `npm run-script`:
  format
    prettier --write 'cypress/**/*.js'
  build
    parcel build index.html

Если мы хотим отформатировать наш код, можно использовать

$ npm run-script format

У run-script есть псевдоним run, поэтому мы можем выполнять скрипты, просто запустив npm run <script name>:

$ npm run format
## the start command is special, you can skip the "run" word
$ npm start

При использовании Yarn мы обычно можем пропустить даже команду "run":

$ yarn run build
## is the same as
$ yarn build

Позже мы добавим сквозные тесты Cypress, и поэтому нам потребуется еще два скрипта для запуска Cypress в интерактивном режиме и на CI.

{
  "scripts": {
    "format": "prettier --write 'cypress/**/*.js'",
    "start": "parcel serve index.html",
    "build": "parcel build index.html",
    "cy:open": "cypress open",
    "cy:run": "cypress run"
  }
}

Совет: для своих личных проектов я предпочитаю короткие имена сценариев "cy:open" и "cy:run". При совместном использовании проектов с другими людьми я предпочитаю очевидные имена сценариев "cypress:open" и "cypress:run".

Посмотрите видео об организации скриптов ниже:

Запуск и тестирование #

Сейчас для работы над тестами Cypress нам нужно запустить приложение, а затем с помощью второго терминала выполнить команду npm run cy:open. Когда мы закончим тестирование, мы закроем Cypress Test Runner, переключимся обратно на первый терминал и остановим приложение.

Мы можем сделать все это с помощью одной команды, используя утилиту start-server-and-test. Установите ее как dev-зависимость с помощью npm i -D start-server-and-test или yarn add -D start-server-and-test, а затем добавьте новый скрипт. Например, я хочу разработать приложение, что означает запустить его и запустить Cypress. Таким образом, я добавлю скрипт dev:

{
  "scripts": {
    "format": "prettier --write 'cypress/**/*.js'",
    "start": "parcel serve index.html",
    "build": "parcel build index.html",
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "dev": "start-test-and-test start 1234 cy:open"
  }
}

Поэтому я могу просто использовать npm run dev для локальной разработки. Сам скрипт ссылается на другие скрипты NPM: он запускает npm start в фоновом режиме для запуска приложения. 1234 в скрипте означает номер порта - утилита start-server-and-test ожидает ответа от этого локального порта. Как только localhost:1234 отвечает, она запускает npm run cy:open. Когда я закрываю Cypress, утилита автоматически останавливает мое приложение.

Утилита регистрирует в папке node_modules/.bin: два псевдонима start-test-and-test и start-test. Таким образом, я могу использовать более короткие имена команд:

"dev": "start-test start 1234 cy:open"

Поскольку команда npm start является очень распространенной, start-test понимает, что она может применяться по умолчанию, поэтому мы можем ее пропустить:

"dev": "start-test 1234 cy:open"

Совет: по поводу всех опций обратитесь к README start-server-and-test.

Если имя скрипта dev недоступно, я использую что-то вроде e2e. Например, Next.js обычно устанавливает скрипт dev для запуска команды next , поэтому мои скрипты в bahmutov/next-and-cypress-example используют e2e:

{
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start",
    "e2e": "start-test dev 3000 cy:open",
    "cy:open": "cypress open",
    "pree2e": "rm -rf .nyc_output coverage .next || true",
    "check-coverage-limits": "check-total --min 100"
  }
}

Скрипт CI #

Иногда мы хотим просто запустить все тесты, не открывая Cypress. Поэтому обычно у меня второй скрипт используется для выполнения cy:run через npm test или npm t:

{
  "scripts": {
    "format": "prettier --write 'cypress/**/*.js'",
    "start": "parcel serve index.html",
    "build": "parcel build index.html",
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "dev": "start-test 1234 cy:open",
    "test": "start-test 1234 cy:run"
  }
}

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

npm it
## equivalent to
npm install
npm test

Мы можем использовать файл package-lock.json при инсталляции

npm cit
## equivalent to
npm ci
npm test

Посмотрите "запуск сервера и тестирование" в действии на этом видео.

Быстрый запуск #

Для больших проектов количество скриптов растет, а средняя длина имени скрипта приближается к названию исландского вулкана. Иногда мы получаем вариации скрипта cypress run: один для записи результатов тестирования, другой для запуска в браузере Chrome и т.д.

{
  "scripts": {
    "format": "prettier --write 'cypress/**/*.js'",
    "start": "parcel serve index.html",
    "build": "parcel build index.html",
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "cy:run:record": "cypress run --record",
    "cy:run:chrome": "cypress run --browser chrome",
    "cy:run:record:chrome": "cypress run --record --browser chrome",
    "dev": "start-test 1234 cy:open",
    "test": "start-test 1234 cy:run"
  }
}

Для быстрого запуска нужного скрипта я предлагаю использовать мою утилиту npm-quick-run. Инсталлируйте ее глобально с помощью npm i -g npm-quick-run, а затем используйте nr alias для быстрого запуска скрипта по его префиксу:

nr d
## same as
npm run dev

Если существует несколько скриптов, начинающихся с заданного префикса, npm-quick-run покажет их списком и завершит работу.

$ nr cy
running command with prefix "cy"
Several scripts start with "cy"
cy:open, cy:run, cy:run:record, cy:run:chrome, cy:run:record:chrome

Обратите внимание, что в наших скриптах используется несколько слов, разделенных символом : (знак - тоже подходит). Можно задать префикс для нескольких слов, чтобы найти нужный скрипт. Используйте : или - при вызове nr. Я лично предпочитаю использовать -, так как могу набрать его без нажатия клавиши Shift.

Для примера, давайте откроем Cypress

$ nr c-o
## finds the script "cy:open" and runs it

Давайте запустим тесты в Chrome

$ nr c-r-c
## finds the script "cy:run:chrome" and runs it

Утилита npm-quick-run также передает аргументы найденному скрипту. Например, мы можем сохранить наш оригинальный скрипт cypress run и просто передавать CLI-аргументы, когда это необходимо:

{
  "scripts": {
    "format": "prettier --write 'cypress/**/*.js'",
    "start": "parcel serve index.html",
    "build": "parcel build index.html",
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "dev": "start-test 1234 cy:open",
    "test": "start-test 1234 cy:run"
  }
}

## record tests
nr c-r --record
## record tests in Chrome
nr c-r --record --browser chrome

Посмотрите быстрый запуск NPM в действии на видео ниже

Стоп точка (Stop dot)

В npm-quick-run есть небольшая утилита для работы с определенным количеством слов. Если вы поместите символ точки . в конце префикса, то он будет соответствовать только этому количеству слов. Рассмотрим следующий файл package.json:

{
  "scripts": {
    "cypress": "cypress -help",
    "cypress:open": "cypress open",
    "cypress:run": "cypress run",
    "cypress:run:record": "cypress run --record"
  }
}

Для запуска скрипта "cypress" используйте префикс с "." в конце:

# same as "npm run cypress"
$ nr c. # finds the script with a single word starting with "c"

# same as "npm run cypress:open"
$ nr c-o.

# same as "npm run cypress:run"
$ nr c-r.

# these commands are equivalent
$ npm run cypress:run:record
$ yarn cypress:run:record
$ nr c-r-r
$ nr c-r-r.

Почему я обычно использую символы - и . для разделения слов и прерывания их совпадения? Потому что я могу набирать их без нажатия клавиши Shift.

Перевод статьи подготовлен в рамках курса "Node.js Developer". Всех желающих приглашаем на открытый демо-урок «TypeScript в Node.js для server-side приложений». На занятии рассмотрим:
- как использовать TypeScript в Node.js;
- как работает ts-node и другие технологии;
- движок deno — новый Node.js с TypeScript.