Подкоманда 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
.
Опции
--project <PROJECT>
Вам необходимо установить либо опцию --project
, либо переменную окружения BENCHER_PROJECT
для указания ссылки или UUID уже существующего проекта.
Если оба определены, то значение опции --project
имеет приоритет перед переменной окружения BENCHER_PROJECT
.
--token <TOKEN>
Необходимо установить либо опцию --token
, либо переменную окружения BENCHER_API_TOKEN
для указания действительного API токена.
Если оба определены, то значение опции --token
имеет приоритет перед переменной окружения BENCHER_API_TOKEN
.
--branch <BRANCH>
--branch-start-point <BRANCH>
--branch-start-point-hash <HASH>
--branch-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
.
--adapter <ADAPTER>
--average <AVERAGE>
--file <FILE>
--file-size <FILE>
Смотрите адаптеры оснастки для тестирования для полного обзора.
--iter <ITER>
Опционально: Число повторений тестирования. По умолчанию 1
.
--fold <FOLD>
Опционально: Возможность объединения нескольких результатов в один.
Требует: установки --iter
.
Возможные значения:
min
: Минимальное значениеmax
: Максимальное значениеmean
: Среднее значениеmedian
: Медианное значение
--backdate <DATETIME_SECONDS>
Опционально: Возможность отката даты отчета (секунды со времени эпохи). Внимание: Это не повлияет на порядок предыдущих отчетов! Это полезно при начальном занесении исторических данных в проект в хронологическом порядке.
--allow-failure
Опционально: Разрешить сбой теста производительности.
--err
Опционально: Вывести ошибку при генерации оповещения. Смотрите изменения и оповещения для полного обзора.
--format <FORMAT>
Необязательно: Формат итогового отчета.
По умолчанию используется human
.
Возможные значения:
human
: Человеко-читаемый форматjson
: Формат JSONhtml
: Формат HTML
--quiet
Необязательно: Тихий режим, выводится только окончательный отчет.
Используйте опцию --format
, чтобы изменить формат вывода.
--github-actions <GITHUB_TOKEN>
Опционально: Установить токен аутентификации GitHub API (например, --github-actions ${{ secrets.GITHUB_TOKEN }}
).
Когда этот параметр установлен и bencher run
используется в GitHub Actions в рамках запроса на вытягивание,
то результаты будут добавлены к запросу на вытягивание в виде комментария.
Самый удобный способ это сделать - это переменная среды GITHUB_TOKEN
GitHub Actions.
🐰 Если вы работаете в контейнере 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 будет автоматически интерпретировать результаты в зависимости от комбинации: Проект, Ветка, Тестовый стенд и Адаптер.
Установка пользовательского ID полезна, когда Bencher запускается несколько раз в одном и том же CI рабочем процессе для одной и той же комбинации Проект, Ветка, Тестовый стенд и Адаптер.
Требует: --github-actions
--ci-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 бэкенд-хоста. По умолчанию - https://api.bencher.dev.
--attempts <ATTEMPTS>
Опционально: Максимальное количество попыток повторения запроса. По умолчанию - 10
.
--retry-after <RETRY_AFTER_SECONDS>
Опционально: Повторить запрос через указанное количество секунд (экспоненциальное отставание). По умолчанию - 1
.
--dry-run
Опционально: Выполнить пробный запуск. Это не сохранит никаких данных в бэкенде. Отчет или Ветка, как указано в выборе ветки, не будут созданы.
-h
--help
Опционально: Вывести справку.
🐰 Поздравляем! Вы изучили основы
bencher run
! 🎉