VTC

Слова и строки

Парсер разделяет слова, обнаруживая пробельные символы, а строка — это слово или ряд слов в одной строке, заключённые в двойные кавычки («…») или, для многострочных строк, в фигурные скобки ({…}).

Комментарии

Ведущие пробелы в строках игнорируются. Пустые строки (или строки, состоящие только из пробелов) также игнорируются, как и строки, начинающиеся с «#», которые являются комментариями.

Строки и команды

Файлы тестов содержат не более одной команды на строку, причём первое слово в строке является командой, а последующие — её аргументами. Чтобы продолжить на новой строке без разрыва строки аргумента, можно экранировать символ новой строки (\n) обратной косой чертой (\).

Встроенные макросы

${bad_backend}

Адрес сокета, который надёжно никогда не будет принимать подключения.

${bad_ip}

Невероятный IPv4-адрес.

${date}

Текущая дата и время в формате HTTP.

${listen_addr}

Адрес прослушивания по умолчанию, используемый различными компонентами, по умолчанию случайный порт на localhost.

${localhost}

Первый IP-адрес, который разрешается в «localhost».

${pwd}

Рабочий каталог, из которого был запущен varnishtest.

${string,<action>[,<args>...]}

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

${string,repeat,<uint>,<str>}

Повторить строку str uint раз.

${testdir}

Директория, содержащая сценарий VTC для текущего выполнения тестового случая.

${tmpdir}

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

${topbuild}

Присутствует только при использовании опции -i, для работы с самим Varnish вместо обычной установки.

barrier

ПРИМЕЧАНИЕ: Эта команда доступна везде, где разрешены команды.

Блокировки позволяют синхронизировать разные потоки, чтобы убедиться, что события происходят в правильном порядке. Их можно использовать даже в VCL.

Сначала необходимо объявить блокировку:

barrier bNAME TYPE NUMBER [-cyclic]

Аргументы:

bNAME

имя блокировки, используемое для её идентификации при создании точек синхронизации. Оно должно начинаться с «b».

TYPE

может быть «cond» (мьютекс) или «sock» (сокет) и устанавливает внутреннее поведение. Если вам не нужна синхронизация VCL, используйте cond.

NUMBER

количество необходимых точек синхронизации для прохождения блокировки.

-cyclic

если присутствует, блокировка сбросится и будет готова к новому раунду после прохождения.

Затем для добавления точки синхронизации:

barrier bNAME sync

Это заблокирует родительский поток до тех пор, пока количество точек синхронизации для bNAME не достигнет значения NUMBER, заданного в объявлении блокировки.

Если вам нужно синхронизировать VCL, необходимо объявить блокировку «sock». Это создаст определение макроса с именем «bNAME_sock», которое можно использовать в VCL (после импорта vmod vtc):

vtc.barrier_sync("${bNAME_sock}");

Эта функция возвращает 0, если всё прошло успешно, и эквивалентна barrier bNAME sync на верхнем уровне VTC.

client/server

Клиентские и серверные потоки — это фиктивные HTTP-сущности, используемые для тестирования вашего Varnish и VCL. Они принимают любое количество аргументов, а те, которые не распознаются, предполагая, что они не начинаются с «-», обрабатываются как спецификации, описывающие действия, которые необходимо выполнить:

client cNAME [...]
server sNAME [...]

Клиенты и серверы идентифицируются строкой, которая является первым аргументом, имена клиентов начинаются с «c», а серверов — с «s».

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

delay

ПРИМЕЧАНИЕ: Эта команда доступна везде, где доступны команды.

Ожидание в течение указанного в аргументе количества секунд. Число может включать дробную часть, например, 1,5.

feature

Проверяет, доступны ли необходимые функции для теста, и пропускает тест в противном случае; или изменяет интерпретацию теста, как описано ниже. feature принимает любое количество аргументов из этого списка:

64bit

Среда 64-битная

ipv4

127.0.0.1 работает

ipv6

[::1] работает

dns

Работают DNS-запросы

topbuild

Тест запущен с флагом «-i»

root

Тест запущен пользователем root

user_varnish

Пользователь varnish существует

user_vcache

Пользователь vcache существует

group_varnish

Группа varnish существует

cmd <command-line>

Командная строка, которая должна выполняться с нулевым кодом возврата

ignore_unknown_macro

Не завершать тест, если строка вида ${…} не распознаётся как макрос.

persistent_storage

Varnish был собран с устаревшим хранилищем persistent storage.

coverage

Varnish был собран с включённым инструментом code coverage.

asan

Varnish был собран с address sanitizer.

msan

Varnish был собран с memory sanitizer.

tsan

Varnish был собран с thread sanitizer.

ubsan

Varnish был собран с undefined behavior sanitizer.

sanitizer

Varnish был собран с sanitizer.

workspace_emulator

Varnish был собран с его эмулятором рабочей области.

abstract_uds

Создание абстрактного сокета unix domain socket прошло успешно

Имя функции может быть с префиксом «!» для пропуска теста, если функция присутствует.

Будьте осторожны с ignore_unknown_macro, так как это может привести к тому, что тест с ошибочно написанным макросом завершится неудачей без сообщения об ошибке. Вам это нужно только в том случае, если вам необходимо выполнить тест со строками вида «${…}».

filewrite

Запись строк в файл

filewrite [-a] /somefile “Hello” “ ” “Worldn”

Флаг -a открывает файл в режиме добавления.

haproxy

Определяет и взаимодействует с экземплярами haproxy.

Для определения сервера haproxy используется следующий синтаксис:

haproxy hNAME -conf-OK CONFIG
haproxy hNAME -conf-BAD ERROR CONFIG
haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]

Первое haproxy hNAME выполнение запустит мастер-процесс haproxy в фоновом режиме, ожидая, пока -start переключение фактически запустит дочерний процесс.

Аргументы:

hNAME

Идентифицирует сервер HAProxy строкой, она должна начинаться с символа ‘h’.

-conf-OK CONFIG

Запустить haproxy в режиме ‘-c’ для проверки конфигурации на корректность

stdout/stderr должны содержать строку ‘Configuration file is valid’. Код возврата должен быть 0.

-conf-BAD ERROR CONFIG

Запустить haproxy в режиме ‘-c’ для проверки конфигурации на ошибки.

Строка “ERROR” должна быть частью диагностики в stdout/stderr. Код возврата должен быть 1.

-D

Запустить HAproxy в режиме демона. Если не указан, используется режим ‘-d’.

-W

Включить режим работы HAproxy в режиме Рабочего процесса.

-S

Включить мастер-интерфейс командной строки HAproxy в режиме Рабочего процесса.

-arg STRING

Передать аргумент haproxy, например “-h simple_list”.

-cli STRING

Указать спецификацию для выполнения в командной строке (CLI).

-mcli STRING

Указать спецификацию для выполнения в командной строке (CLI) мастера-процесса.

-conf STRING

Указать конфигурацию, которую должен загрузить этот экземпляр HAProxy.

-conf+backend STRING

Указать конфигурацию, которую должен загрузить этот экземпляр HAProxy,

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

-start

Запустить этот экземпляр HAProxy.

-wait

Остановить этот экземпляр HAProxy.

-expectexit NUMBER

Ожидать завершения работы haproxy с указанным значением

logexpect

Читает VSL и ищет записи, соответствующие заданной спецификации. Он будет обрабатывать записи, пытаясь найти совпадение с первым шаблоном, и при завершении будет продолжать обработку, пытаясь найти совпадение со следующим шаблоном. Если шаблон не будет найден, тест завершится неудачей.

Потоки logexpect объявляются следующим образом:

logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
        [vsl arguments] {
                expect <skip> <vxid> <tag> <regex>
                expect <skip> <vxid> <tag> <regex>
                fail add <vxid> <tag> <regex>
                fail clear
                abort
                ...
        } [-start|-wait|-run]

И после объявления вы можете запустить их или дождаться их завершения:

logexpect lNAME <-start|-wait>

С помощью:

lNAME

Назовите поток logexpect, он должен начинаться с символа ‘l’.

-v id

Указать экземпляр varnish для использования (в большинстве случаев, id=v1).

-g <session|request|vxid|raw

Определить, как группируются записи, см. -g в man varnishlog для получения дополнительной информации.

-d <0|1>

Начать обработку записей журнала с начала журнала, а не с конца.

-q query

Фильтр записей с использованием запроса, см. man vsl-query для получения дополнительной информации. Несколько опций -q не поддерживаются.

-m

Также отображать записи журнала для пропусков (только для отладки)

-err

Инвертировать значение успешного выполнения. Обычно используется один раз, чтобы ожидать, что logexpect завершится неудачей

-start

Запустить поток logexpect в фоновом режиме.

-wait

Дождаться завершения потока logexpect

-run

Эквивалентно “-start -wait”.

Аргументы VSL (аналогичны параметрам varnishlog):

-C

Использовать регистронезависимое регулярное выражение

-i <taglist>

Включить теги

-I <[taglist:]regex>

Включить по регулярному выражению

-T <seconds>

Таймаут завершения транзакции

Спецификация expect:

skip: [uint|*|?]

Максимальное количество записей для пропуска

vxid: [uint|*|=]

vxid для сопоставления

tag: [tagname|*|=]

Тег для сопоставления

regex:

регулярное выражение для сопоставления (необязательно)

Для skip, vxid и tag, ‘*’ сопоставляет все, ‘=’ ожидает значения предыдущей сопоставленной записи. Маркер ‘?’ эквивалентен нулю, ожидая совпадения в следующей записи. Различие заключается в том, что ‘?’ можно использовать, когда порядок отдельных последовательных логов не детерминирован. Другими словами, строки из блока альтернатив, помеченных ‘?’, могут быть сопоставлены в любом порядке, но все они должны быть сопоставлены в конечном итоге.

Спецификация fail:

add: Добавить в список ошибок

Аргументы эквивалентны expect, за исключением пропущенного skip.

clear: Очистить список ошибок

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

Для успешного завершения logexpect не должно быть спецификаций в списке ошибок, поэтому logexpect всегда должен завершаться

expect <skip> <vxid> <tag> <условие_завершения> fail clear

Спецификация abort:

abort(3) varnishtest, предназначена для отладки самой библиотеки клиента VSL.

loop

loop NUMBER STRING

Обработать STRING как спецификацию NUMBER раз.

Это работает внутри всех строк спецификаций

process

Запустить процесс со stdin+stdout на псевдотерминале и stderr в pipe.

Вывод с псевдотерминала копируется дословно в ${pNAME_out}, а флаги -log/-dump/-hexdump также помещают его в vtc-log.

Псевдотерминал не находится в режиме ECHO, но если запущенные программы устанавливают его в режим ECHO (“stty sane”), любой ввод, отправленный процессу, также отобразится в этом потоке из-за ECHO.

Вывод из stderr-pipe копируется дословно в ${pNAME_err} и всегда включается в vtc_log.

process pNAME SPEC [-allow-core] [-expect-exit N] [-expect-signal N]

[-dump] [-hexdump] [-log] [-run] [-close] [-kill SIGNAL] [-start] [-stop] [-wait] [-write STRING] [-writeln STRING] [-writehex HEXSTRING] [-need-bytes [+]NUMBER] [-screen-dump] [-winsz LINES COLUMNSS] [-ansi-response] [-expect-cursor LINE COLUMN] [-expect-text LINE COLUMN TEXT] [-match-text LINE COLUMN REGEXP]

pNAME

Имя процесса. Оно должно начинаться с ‘p’.

SPEC

Команда(ы) для выполнения в этом процессе.

-hexdump

Логировать вывод с использованием vtc_hexdump(). Должно быть указано до -start/-run.

-dump

Логировать вывод с использованием vtc_dump(). Должно быть указано до -start/-run.

-log

Логировать вывод с использованием VLU/vtc_log(). Должно быть указано до -start/-run.

-start

Запустить процесс.

-expect-exit N

Ожидать код возврата N

-expect-signal N

Ожидать сигнал в коде возврата N

-allow-core

Сброс ядра при выходе — OK

-wait

Дождаться завершения процесса.

-run

Сокращение для -start -wait.

В большинстве случаев, если вам нужно просто запустить процесс и дождаться его завершения, вы можете использовать вместо него команду shell. Следующие команды эквивалентны:

shell "do --something"

process p1 "do --something" -run

Однако, вы можете использовать вариант process, чтобы удобно собирать стандартный ввод и вывод, не занимаясь перенаправлением оболочки самостоятельно. Команда shell также может ожидать выражение из вывода, рассмотрите её использование, если вам нужно только сопоставить одно.

-key KEYSYM

Отправить эмулированное нажатие клавиши. KEYSYM может быть одним из (NPAGE, PPAGE, HOME, END)

-kill SIGNAL

Отправить сигнал процессу. Аргументом может быть строка “TERM”, “INT” или “KILL” для сигналов SIGTERM, SIGINT или SIGKILL соответственно, или дефис (-) с номером сигнала.

Если вам нужно использовать другие имена сигналов, вы можете использовать команду kill(1) напрямую:

shell "kill -USR1 ${pNAME_pid}"

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

-stop

Сокращение для -kill TERM.

-close

Псевдоним для “-kill HUP”

-winsz LINES COLUMNS

Изменить размер окна терминала на LIN строк и COL столбцов.

-write STRING

Записать строку в стандартный ввод процесса.

-writeln STRING

То же, что -write, за которым следует символ новой строки (\n).

-writehex HEXSTRING

То же, что -write, но интерпретируется как шестнадцатеричные байты.

-need-bytes [+]NUMBER

Подождать, пока не будет получено как минимум NUMBER байтов в сумме. Если ‘+’ предваряет NUMBER, нужно получить NUMBER новых байтов.

-ansi-response

Отвечать на последовательности ответа терминала

-expect-cursor LINE COLUMN

Ожидать расположения курсора

-expect-text LINE COLUMNS TEXT

Дождаться появления TEXT в позиции LIN,COL на виртуальном экране. Строки и столбцы нумеруются от 1 до N. LIN==0 означает “в любой строке”, COL==0 означает “в любом месте строки”

-match-text LINE COLUMN REGEXP

Дождаться, пока REGEXP сопоставится с текстом в позиции LIN,COL на виртуальном экране. Строки и столбцы нумеруются от 1 до N. LIN==0 означает “в любой строке”, COL==0 означает “в любом месте строки”

-screen-dump

Сделать дамп виртуального экрана в vtc_log

setenv

Установить или изменить переменную среды:

setenv FOO "bar baz"

Вышеуказанное действие установит переменную среды $FOO в указанное значение. Также есть аргумент -ifunset, который установит значение только в том случае, если переменная среды ещё не существует:

setenv -ifunset FOO quux

shell

ПРИМЕЧАНИЕ: Эта команда доступна везде, где доступны команды.

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

shell {
        echo begin
        cat /etc/fstab
        echo end
}

По умолчанию ожидается код возврата 0, в противном случае vtc завершится неудачей.

Обратите внимание, что строка команды предваряется “exec 2>&1;” для объединения stderr и stdout обратно в тестовый процесс.

Необязательные аргументы:

-err

Ожидать код возврата, отличный от нуля.

-exit N

Ожидать код возврата N вместо нуля.

-expect STRING

Ожидать, что строка будет найдена в stdout+err.

-match REGEXP

Ожидать, что regexp будет сопоставлен с выводом stdout+err.

Поток

(примечание: этот раздел находится на верхнем уровне для удобства навигации, но он является частью спецификации клиент/сервер)

Потоки примерно соответствуют запросу в HTTP/2. Запрос отправляется по потоку N, ответ тоже, затем поток удаляется. Основное исключение — первый поток 0, который служит координатором.

Синтаксис потока следует за синтаксисом клиент/сервер:

stream ID [SPEC] [ACTION]

ID — это номер потока HTTP/2, а SPEC описывает, что будет сделано в этом потоке.

Обратите внимание, что при обработке действия потока, если приложение не работает в режиме HTTP/2, эта спецификация выполняется до:

txpri/rxpri # client/server
stream 0 {
    txsettings
    rxsettings
    txsettings -ack
    rxsettings
    expect settings.ack == true
} -run

И режим HTTP/2 активируется перед обработкой спецификации.

sendhex "00 00 08 00 0900       8d"

syslog

Определение и взаимодействие с экземплярами syslog (для использования с haproxy).

Для определения сервера syslog используется следующий синтаксис:

syslog SNAME

Аргументы:

SNAME

Идентификатор сервера syslog строкой, которая должна начинаться с 'S'.

-level STRING

Установите уровень приоритета syslog по умолчанию, используемый любым последующим командным «recv». Любой syslog-dgram с другим уровнем будет пропущен командой «recv». Это значение уровня по умолчанию может быть заменено командой «recv», если она указана в качестве первого аргумента: «recv <level>».

-start

Запустите поток сервера syslog в фоновом режиме.

-repeat

Вместо обработки спецификации только один раз, обработайте ее

NUMBER раз.

-bind

Свяжите сокет syslog с локальным адресом.

-wait

Подождите завершения этого потока.

-stop

Остановите поток сервера syslog.

tunnel

Цель туннеля — помочь контролировать передачу данных между двумя сторонами, например, для запуска тайм-аутов сокета в середине кадров протокола, без необходимости изменения реализации обеих сторон.

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

tunnel t1 {
    barrier b1 sync
    pause
    delay 1
    send 42
    barrier b2 sync
    resume
} -start

varnish

Определите и взаимодействуйте с экземплярами varnish.

Чтобы определить сервер Varnish, используйте такой синтаксис:

varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
        [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]

Первое varnish vNAME вызов запустит мастер-процесс varnishd в фоновом режиме, ожидая переключения -start, чтобы фактически запустить дочерний процесс.

Типы, используемые в описании ниже:

PATTERN

— шаблон в стиле «glob» (например, fnmatch(3)), как используется в расширении имен файлов оболочки.

Аргументы:

vNAME

Идентифицирует сервер Varnish строкой, она должна начинаться с «v».

-arg STRING

Передайте аргумент varnishd, например, «-h simple_list».

Если определены макросы ${varnishd_args_prepend} или ${varnishd_args_append}, они расширяются и вставляются перед / добавляются к командной строке varnishd, как построено varnishtest, перед расширением самой командной строки. Это позволяет вносить изменения в командную строку varnishd без редактирования тестовых случаев. Эти макросы можно определить, используя опцию -D для varnishtest.

-vcl STRING

Укажите VCL для загрузки в этом экземпляре Varnish. Вероятно, вы захотите использовать многострочные строки для этого ({…}).

-vcl+backend STRING

Делает то же самое, что и -vcl, но добавляет блок определения известных бэкэндов (т. е. уже определенных).

-errvcl STRING1 STRING2

Загрузить STRING2 как VCL, ожидая его сбоя и отправки Varnish строки ошибки, соответствующей STRING1.

-jail STRING

Посмотрите man varnishd (-j) для получения дополнительной информации.

-proto PROXY

Используйте протокол проксирования Varnish. Обратите внимание, что PROXY здесь — это фактическая строка.

Вы можете выбрать запуск экземпляра Varnish и/или ожидание нескольких событий:

varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]

-start

Запустить дочерний процесс.

После успешного запуска следующие макросы доступны для стандартного адреса прослушивания: ${vNAME_addr}, ${vNAME_port} и ${vNAME_sock}. Дополнительные макросы доступны, включая имя адреса прослушивания для каждого адреса, к которому слушает vNAME, например: ${vNAME_a0_addr}.

-stop

Остановить дочерний процесс.

-syntax

Установите уровень синтаксиса VCL для этой команды (по умолчанию: 4.1)

-wait

Подождите завершения этого экземпляра.

-wait-running

Подождите запуска дочернего процесса Varnish.

-wait-stopped

Подождите остановки дочернего процесса Varnish.

-cleanup

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

-expectexit NUMBER

Ожидайте завершения работы varnishd с этим значением.

После запуска Varnish вы можете взаимодействовать с ним (как вы бы делали через varnishadm) с помощью этих дополнительных переключателей:

varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
              [-clijson STRING]

-cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP STRING

Все четыре из них отправят STRING в командную строку, единственное различие заключается в том, чего они ожидают в результате. -cli ничего не ожидает, -cliok ожидает 200, -clierr ожидает STATUS, а -cliexpect ожидает, что REGEXP соответствует возвращенному ответу.

-clijson STRING

Отправить STRING в командную строку, ожидать успеха (CLIS_OK/200) и проверить, что ответ является разборчивым JSON.

Также возможно взаимодействовать с его общей памятью (как вы бы делали с помощью инструментов вроде varnishstat) с помощью дополнительных переключателей:

-expect !PATTERN|PATTERN OP NUMBER|PATTERN OP PATTERN

Посмотрите в VSM и убедитесь, что у первого счетчика VSC, идентифицированного PATTERN, правильное значение. OP может быть ==, >, >=, <, <=. Например:

varnish v1 -expect SM?.s1.g_space > 1000000
varnish v1 -expect cache_hit >= cache_hit_grace

В форме ! тест терпит неудачу, если счетчик соответствует PATTERN.

Пространство имен MAIN. можно опустить из PATTERN.

Тест занимает до 5 секунд до истечения времени ожидания.

-vsc PATTERN

Вывести счетчики VSC, соответствующие PATTERN.

-vsl_catchup

Подождите, пока поток журналирования не будет простаивать, чтобы убедиться, что все сгенерированные журналы были выгружены.

varnishtest

Альтернативное имя для ‘vtest’, см. выше.

vtest

Эта команда должна быть первой в вашем vtc, так как она идентифицирует тестовый случай короткой, но описательной фразой. Она принимает ровно один аргумент, строку, например:

vtest "Check that vtest is actually a valid command"

Она также выведет эту строку в журнале.