Подкоманда bencher run CLI
bencher run
- самая популярная подкоманда CLI.
Она используется для запуска тестов производительности и отчетов о результатах.
Таким образом, она является одной из самых сложных подкоманд.
На этой странице будет рассказано о параметрах, флагах и аргументах, которые можно передать bencher run
.
Команда для бенчмаркинга
Первым аргументом для bencher run
является необязательная команда бенчмаркинга.
Это команда, которая будет выполнена для вызова вашего механизма бенчмаркинга.
Также её можно задать с помощью переменной окружения BENCHER_CMD
.
По умолчанию эта команда выполняется в оболочке,
которую можно настроить с помощью опций --shell
и --flag
.
Её вывод анализируется адаптером механизма бенчмаркинга,
который можно задать с помощью опции --adapter
.
Однако, если механизм бенчмаркинга выводит результаты в файл, то должна быть также использована опция --file
,
чтобы указать путь к файлу вывода.
В качестве альтернативы для отслеживания размера файла вывода (например, размера бинарного файла) вместо его содержимого,
можно использовать опцию --file-size
, чтобы указать путь к файлу вывода.
Если вы предпочитаете не выполнять команду в оболочке, вы можете использовать флаг --exec
или просто предоставить дополнительные аргументы к вашей команде как дополнительные аргументы к bencher run
.
Форма Shell:
Форма Exec:
Команду для бенчмаркинга можно выполнить несколько раз, используя опцию --iter
,
и эти результаты можно объединить в один результат с помощью опции --fold
.
Если какая-либо из итераций не удастся, то вся команда считается неудачной,
если только не установлен флаг --allow-failure
.
Если команда для бенчмаркинга не указана, но указана опция --file
,
то bencher run
просто будет читать из пути файла вывода.
Аналогичным образом, если команда для бенчмаркинга не указана, но указана опция --file-size
,
то bencher run
будет читать размер файла по указанному пути файла.
Если не указана команда для бенчмаркинга, опция --file
,
ни опция --file-size
,
то bencher run
будет читать из stdin
.
Это позволяет вам сохранить вывод другой команды в файл или перенаправить его в bencher run
.
Options
--project <PROJECT>
Вам необходимо установить либо опцию --project
, либо переменную окружения BENCHER_PROJECT
для указания ссылки или UUID уже существующего проекта.
Если оба определены, то значение опции --project
имеет приоритет перед переменной окружения BENCHER_PROJECT
.
--token <TOKEN>
Необходимо установить либо опцию --token
, либо переменную окружения BENCHER_API_TOKEN
для указания действительного API токена.
Если оба определены, то значение опции --token
имеет приоритет перед переменной окружения BENCHER_API_TOKEN
.
--branch <BRANCH>
--start-point <BRANCH>
--start-point-hash <HASH>
--start-point-max-versions <COUNT>
--start-point-clone-thresholds
--start-point-reset
См. Выбор ветки для полного обзора.
--hash <HASH>
Опционально: 40-символьный хеш SHA-1 коммита. Если два отчета имеют одинаковые ветку и хеш, они будут считаться относящимися к одному и тому же коммиту. Следовательно, у них будет один и тот же номер версии ветки.
Если не указано, Bencher CLI пытается найти текущий git hash. Начиная с поиска git-репозитория в текущем рабочем каталоге. Если поиск неудачен, он переходит к родительскому каталогу и повторяет попытки до корневого каталога. Если git-репозиторий найден, то используется git hash HEAD текущей ветки.
--no-hash
Необязательно: Не пытаться найти хеш коммита git
.
Эта опция конфликтует с --hash
и переопределяет его стандартное поведение поиска репозитория git
.
--testbed <TESTBED>
Опционально: Можно установить либо опцию --testbed
, либо переменную окружения BENCHER_TESTBED
для указания ссылки или UUID уже существующего тестового стенда.
Если оба определены, то значение опции --testbed
имеет приоритет перед переменной окружения BENCHER_TESTBED
.
Если ни один из них не определен, то в качестве тестового стенда по умолчанию используется localhost
.
--threshold-measure <MEASURE>
--threshold-test <TEST>
--threshold-min-sample-size <SAMPLE_SIZE>
--threshold-max-sample-size <SAMPLE_SIZE>
--threshold-window <WINDOW>
--threshold-lower-boundary <BOUNDARY>
--threshold-upper-boundary <BOUNDARY>
--thresholds-reset
--err
Смотрите пороги и оповещения для полного обзора.
--adapter <ADAPTER>
--average <AVERAGE>
--file <FILE>
--file-size <FILE>
Смотрите адаптеры оснастки для тестирования для полного обзора.
--iter <ITER>
Опционально: Число повторений тестирования. По умолчанию 1
.
--fold <FOLD>
Опционально: Возможность объединения нескольких результатов в один.
Требует: установки --iter
.
Возможные значения:
min
: Минимальное значениеmax
: Максимальное значениеmean
: Среднее значениеmedian
: Медианное значение
--backdate <DATETIME_SECONDS>
Опционально: Возможность отката даты отчета (секунды со времени эпохи). Внимание: Это не повлияет на порядок предыдущих отчетов! Это полезно при начальном занесении исторических данных в проект в хронологическом порядке.
--allow-failure
Опционально: Разрешить сбой теста производительности.
--format <FORMAT>
Необязательно: Формат итогового отчета.
По умолчанию используется human
.
Возможные значения:
human
: Человеко-читаемый форматjson
: Формат JSONhtml
: Формат HTML
--quiet
Необязательно: Тихий режим, выводится только окончательный отчет.
Используйте опцию --format
, чтобы изменить формат вывода.
--github-actions <GITHUB_TOKEN>
Необязательно: установите токен аутентификации GitHub API (например, --github-actions ${{ secrets.GITHUB_TOKEN }}
).
Когда эта опция установлена и bencher run
используется в GitHub Actions как часть pull request,
то результаты будут добавлены в pull request в виде комментария.
В противном случае результаты будут добавлены к коммиту в виде комментария проверки GitHub.
Самый удобный способ сделать это - использовать переменную окружения GitHub Actions GITHUB_TOKEN
.
🐰 Если вы запускаете внутри Docker-контейнера в GitHub Action, вам нужно передать следующие переменные среды и смонтировать путь, указанный в
GITHUB_EVENT_PATH
:
GITHUB_ACTIONS
GITHUB_EVENT_NAME
GITHUB_EVENT_PATH
--ci-only-thresholds
Опционально: отправлять результаты в CI только если существует пороговое значение для ветки, тестовой среды и меры.
Если пороговые значения отсутствуют, ничего отправляться не будет.
Требуется: --github-actions
--ci-only-on-alert
Опционально: начинается публикация результатов в CI только если сгенерировано предупреждение.
Если предупреждение сгенерировано, все последующие результаты также будут опубликованы, даже если они не содержат предупреждений.
Требуется: --github-actions
--ci-id <ID>
Необязательно: Пользовательский идентификатор для отправки результатов в CI. По умолчанию Bencher автоматически сегментирует результаты по комбинации: Проект, Ветка, Тестовая среда и Адаптер. Установка пользовательского идентификатора полезна, когда Bencher запускается несколько раз в том же CI-потоке для той же комбинации Проекта, Ветки, Тестовой среды и Адаптера. Требуется: --github-actions
--ci-number <NUMBER>
Необязательно: номер задачи для отправки результатов на CI.
Bencher постарается определить номер задачи CI, необходимый для отправки результатов.
Однако это не всегда доступно в сложных настройках, таких как использование workflow_run
в GitHub Actions.
Требуется: --github-actions
--shell <SHELL>
Необязательный: Путь к командному интерпретатору.
По умолчанию /bin/sh
в UNIX-подобных средах и cmd
в Windows.
--flag <FLAG>
Опционально: флаг команды оболочки.
По умолчанию: -c
в Unix-подобных средах и /C
в Windows.
--exec
Необязательно: Запускать команду как исполняемый файл, а не как команду оболочки.
По умолчанию, если количество аргументов для bencher run
больше одного.
--host <URL>
Опционально: URL-адрес сервера бэкенда. По умолчанию используется Bench Cloud: https://api.bencher.dev
--attempts <ATTEMPTS>
Необязательно: Максимальное количество попыток повторного запроса.
По умолчанию 10
попыток.
--retry-after <RETRY_AFTER_SECONDS>
Необязательно: начальное количество секунд ожидания между попытками (экспоненциальная задержка).
По умолчанию 1
секунда.
--dry-run
Опционально: Выполнить пробный запуск. Это не сохранит никаких данных в бекенд. Ни Отчет, ни Ветвь (как описано в выбор ветви), ни Тестовая среда не будут созданы.
--help
Необязательно: Вывести справку.
🐰 Поздравляем! Вы изучили основы
bencher run
! 🎉