тестовый запуск

В этом содержимом описывается последний выпуск CodeQL CLI. Дополнительные сведения об этом выпуске см. в разделе https://github.com/github/codeql-cli-binaries/releases.

Чтобы просмотреть сведения о параметрах, доступных для этой команды в более раннем выпуске, выполните команду с параметром в терминале --help .

Краткий обзор

Shell

codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

Описание

Выполнение модульных тестов для запросов QL.

Основные параметры

`<test|dir>...`

Каждый аргумент является одним из следующих:

Файл .ql или .qlref , определяющий тест для выполнения.
Каталог, в котором будет выполняться рекурсивный поиск тестов.

[Дополнительно] Задайте код выхода для создания при возникновении каких-либо сбоев. Обычно 1, но инструменты, которые анализирует выходные данные, могут оказаться полезными установить для него значение 0.

`--format=<fmt>`

Выберите формат выходных данных. Возможные варианты:

text(по умолчанию): удобочитаемая текстовая отрисовка.

json: потоковый массив JSON объектов результатов теста.

betterjson: потоковый массив JSON объектов событий.

jsonz: поток объектов результатов теста JSON, завершаемых с нуля.

betterjsonz: поток объектов событий JSON, завершаемых с нуля.

betterjson Для форматов и betterjsonz каждое событие имеет type свойство , указывающее тип события. В будущем могут быть добавлены новые типы событий, поэтому потребители должны игнорировать любое событие с нераспознанным kind свойством.

`--[no-]keep-databases`

[Дополнительно] Сохраните базы данных, извлеченные для выполнения тестовых запросов, даже если все тесты в каталоге пройдены. (База данных всегда будет присутствовать при сбое тестов.)

`--[no-]fast-compilation`

[Не рекомендуется] [Дополнительно] Пропускать особенно медленные шаги оптимизации при компиляции тестовых запросов.

`--[no-]learn`

[Дополнительно] Когда тест создает непредвиденные выходные данные, вместо того, чтобы завершить его сбоем, обновите его .expected файл в соответствии с фактическими выходными данными, чтобы он прошел успешно. Тесты по-прежнему могут завершиться ошибкой в этом режиме, например, если создание тестовой базы данных для запроса не завершается успешно.

`--consistency-queries=<dir>`

[Дополнительно] Каталог с запросами согласованности, которые будут выполняться для каждой тестовой базы данных. Эти запросы не должны выдавать никаких выходных данных (за исключением случаев, когда они обнаруживают проблему), если каталог тестов не содержит CONSISTENCY подкаталог с файлом .expected . Это в основном полезно для тестирования средств извлечения.

`--[no-]check-databases`

[Дополнительно] Запустите набор данных codeql проверка по каждой созданной тестовой базе данных и сообщите о сбое при обнаружении несоответствий. Это полезно при тестировании средств извлечения. Если ожидается, что проверка (временно!) завершится сбоем для конкретной базы данных, поместите DB-CHECK.expected файл в каталог тестов.

`--[no-]show-extractor-output`

[Дополнительно] Отображение выходных данных скриптов средства извлечения, которые создают тестовые базы данных. Это может быть полезно при разработке или редактировании тестовых случаев. Помните, что это может привести к дублированию или неправильному формату выходных данных, если вы используете его с несколькими потоками.

`-M, --ram=<MB>`

Задайте общий объем ОЗУ, который должно быть разрешено использовать средству выполнения тестов.

`--slice=<N/M>`

[Дополнительно] Разделите тестовые случаи на срезы M примерно одинакового размера и обработайте только _N_th из них. Это можно использовать для параллелизации процесса тестирования вручную.

`--[no-]strict-test-discovery`

[Дополнительно. Используйте только запросы, которые можно идентифицировать как тесты. Этот режим пытается различать .ql файлы, определяющие модульные тесты, и .ql файлы, предназначенные для полезных запросов. Этот параметр используется средствами, такими как среды разработки, которые должны определять все модульные тесты в дереве каталогов, не зависят от предыдущих знаний о том, как упорядочены файлы в нем.

В пакете QL, который qlpack.yml объявляет tests каталог, все .ql файлы в этом каталоге считаются тестами, а .ql файлы за его пределами игнорируются. В пакете QL, который не объявляет tests каталог, .ql файл определяется как тест, только если в нем есть соответствующий .expected файл.

Для обеспечения согласованности файлы ограничены теми же правилами, что и .ql файлы, .qlref даже если .qlref файл не может быть не тестируемым.

Параметры для поиска библиотек и средств извлечения, используемых в тестах

`--search-path=<dir>[:<dir>...]`

Список каталогов, в которых можно найти пакеты QL. Каждый каталог может быть либо пакетом QL (или пакетом пакетов, содержащим файл в корневом .codeqlmanifest.json каталоге), либо непосредственным родительским элементом одного или нескольких таких каталогов.

Если путь содержит несколько каталогов, их порядок определяет приоритет между ними: если имя пакета, которое необходимо разрешить, совпадает в нескольких деревьях каталогов, то первое из них выигрывает.

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

Если вы извлекли репозиторий CodeQL как одноуровневый элемент распакованой цепочки инструментов CodeQL, вам не нужно предоставлять этот параметр. В таких каталогах всегда будет выполняться поиск пакетов QL, которые невозможно найти в противном случае. (Если это значение по умолчанию не работает, настоятельно рекомендуется выполнить настройку --search-path раз и навсегда в файле конфигурации для каждого пользователя.

(Примечание. В Windows разделитель пути — ).;

`--additional-packs=<dir>[:<dir>...]`

Если указан этот список каталогов, в них будет выполняться поиск пакетов перед теми, которые в --search-path. Порядок между ними не имеет значения; Это ошибка, если имя пакета найдено в двух разных местах в этом списке.

Это полезно, если вы временно разрабатываете новую версию пакета, которая также отображается в пути по умолчанию. С другой стороны, не рекомендуется переопределять этот параметр в файле конфигурации; некоторые внутренние действия добавляют этот параметр на лету, переопределяя любое настроенное значение.

(Примечание. В Windows разделитель пути — ).;

`--library-path=<dir>[:<dir>...]`

[Дополнительно] Необязательный список каталогов, которые будут добавлены в путь поиска необработанного импорта для библиотек QL. Его следует использовать только в том случае, если вы используете библиотеки QL, которые не были упакованы как пакеты QL.

(Примечание. В Windows разделитель пути — ).;

`--dbscheme=<file>`

[Дополнительно] Явным образом определяет, для каких запросов dbscheme следует компилироваться. Это должно быть дано только абонентами, которые очень уверены в том, что они делают.

`--compilation-cache=<dir>`

[Дополнительно] Укажите дополнительный каталог для использования в качестве кэша компиляции.

`--no-default-compilation-cache`

[Дополнительно. Не используйте кэши компиляции в стандартных расположениях, таких как пакет QL, содержащий запрос, или в каталоге цепочки инструментов CodeQL.

Параметры настройки диспетчера пакетов CodeQL

`--registries-auth-stdin`

Проверка подлинности в реестрах контейнеров GitHub Enterprise Server путем передачи разделенного запятыми списка \<registry_url>=\ пар.

Например, можно передать https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 для проверки подлинности в двух экземплярах GitHub Enterprise Server.

Это переопределяет переменные среды AUTH CODEQL_REGISTRIES_и токена GITHUB_. Если вам нужно пройти проверку подлинности только в реестре контейнеров github.com, можно использовать более простой --github-auth-stdin вариант.

`--github-auth-stdin`

Проверка подлинности в реестре контейнеров github.com путем передачи маркера github.com GitHub Apps или личного маркера доступа через стандартные входные данные.

Для проверки подлинности в реестрах контейнеров GitHub Enterprise Server передайте --registries-auth-stdin или используйте переменную среды CODEQL_REGISTRIES_AUTH.

Это переопределяет переменную среды GITHUB_TOKEN.

Параметры управления компиляцией запросов

`--no-release-compatibility`

[Дополнительно. Используйте новейшие функции компилятора за счет переносимости.

Время от времени новые функции языка QL и оптимизации средства оценки будут поддерживаться оценщиком QL в нескольких выпусках, прежде чем они будут включены по умолчанию в компиляторе QL. Это помогает гарантировать, что производительность, которую вы будете использовать при разработке запросов в последнем выпуске CodeQL, может соответствовать немного более старым выпускам, которые могут по-прежнему использоваться для сканирования кода или интеграции CI.

Если вы не заботитесь о том, чтобы ваши запросы были совместимы с другими (более ранними или более поздними) выпусками CodeQL, иногда можно достичь небольшой дополнительной производительности с помощью этого флага, чтобы включить последние улучшения в компиляторе на ранних этапах.

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

Доступно начиная с v2.11.1.

Параметры, управляющие оценкой тестовых запросов

`--[no-]tuple-counting`

[Дополнительно] Отображение счетчиков кортежей для каждого этапа оценки в журналах средства оценки запросов. --evaluator-log Если этот параметр указан, счетчики кортежей будут включены в текстовые и структурированные журналы JSON, созданные командой . (Это может быть полезно для оптимизации производительности сложного кода QL.)

`--timeout=<seconds>`

[Дополнительно] Установите время ожидания для оценки запроса в секундах.

Функция времени ожидания предназначена для перехвата случаев, когда для оценки сложного запроса потребуется "навсегда". Это не эффективный способ ограничить общее время, которое может занять вычисление запроса. Оценка будет продолжаться до тех пор, пока каждая отдельная часть вычисления по времени завершается в течение времени ожидания. В настоящее время эти отдельные временные части являются уровнями RA оптимизированного запроса, но в будущем они могут измениться.

Если время ожидания не указано или равно 0, время ожидания не устанавливается (за исключением тестового запуска codeql, где время ожидания по умолчанию составляет 5 минут).

`-j, --threads=<num>`

Используйте это количество потоков для оценки запросов.

По умолчанию равен 1. Вы можете передать 0, чтобы использовать один поток на каждом ядре на компьютере, или -N , чтобы оставить N ядер неиспользуемых (за исключением того, что по-прежнему используется хотя бы один поток).

Параметры управления выходными данными структурированных журналов средства оценки

`--evaluator-log=<file>`

[Дополнительно] Вывод структурированных журналов о производительности средства оценки в указанный файл. Формат этого файла журнала может быть изменен без уведомления, но будет потоком объектов JSON, разделенных двумя символами новой строки (по умолчанию) или одним, если --evaluator-log-minify параметр передан. Используйте для codeql generate log-summary <file> создания более стабильной сводки по этому файлу и избегайте непосредственного анализа файла. Файл будет перезаписан, если он уже существует.

В этой статье