mariadb-test Справочные файлы

Фреймворк mariadb-test использует множество других файлов, влияющих на процесс тестирования, помимо файлов тестов и результатов.

disabled.def файл

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

В файле содержатся имена тестов и комментарий (объясняющий причину отключения теста), разделенные двоеточием. Строки, начинающиеся с символа решётки (#), игнорируются. Типичный disabled.def может выглядеть так (обратите внимание, что решётка посередине строки не начинает комментарий):

# List of disabled tests
# test name : comment
rpl_redirect : Fails due to bug#49978
events_time_zone  : need to fix the timing

Во время тестирования mtr будет выводить отключённые тесты так:

...
rpl.rpl_redirect              [ disabled ]  Fails due to bug#49978
rpl.events_time_zone          [ disabled ]  need to fix the timing
...

Этот файл должен находиться в директории набора тестов.

suite.opt файл

Этот файл перечисляет параметры сервера, которые будут добавлены в командную строку mariadbd для каждого теста этого набора. Он может ссылаться на переменные окружения с помощью $NAME синтаксиса. Символы оболочки должны быть заключены в кавычки. Например

--plugin-load=$AUTH_PAM_SO
--max-connections=40 --net_read_timeout=5
"--replicate-rewrite-db=test->rewrite"

Обратите внимание, что параметры можно поместить либо в одну строку, либо на отдельные строки. Хорошей практикой является использование префикса --loose- для имени параметра, если сервер может или не может распознать параметр в зависимости от конфигурации. Неизвестный параметр в файле .opt помешает запуску сервера и тест будет прерван.

Этот файл должен находиться в директории набора тестов.

другие *.opt файлы

Для каждого файла теста или файла включения somefile.test или somefile.inc, mtr будет искать somefile.opt, somefile-master.opt и somefile-slave.opt. Эти файлы имеют точно такой же синтаксис, как suite.opt выше. Параметры из этих файлов также будут добавлены в командную строку сервера (все серверы, запущенные для этого теста, только мастер или только раб соответственно) для всех затронутых тестов, например, для всех тестов, которые включают somefile.inc напрямую или косвенно.

Типичный пример использования include/have_blackhole.inc и include/have_blackhole.opt. Последний содержит необходимые параметры командной строки для загрузки хранилища Blackhole, в то время как первый проверяет, что движок действительно был загружен. Любой тест, которому нужен движок Blackhole, должен только начинаться с source include/have_blackhole.inc; и движок будет автоматически загружен для теста.

my.cnf файл

Это не my.cnf файл, который будут использовать тесты из этого набора, а скорее шаблон для него. Позже он будет преобразован в фактический my.cnf. Если набор тестов не содержит шаблон my.cnf , будет использоваться шаблон по умолчанию — include/default_my.cnf — или suite/rpl/my.cnf если тест включает master-slave.inc (это одна из немногих частей старой магии MySQL mysql-test-run , которую мы ещё не удалили). Обычно шаблон набора тестов не будет содержать полную конфигурацию сервера, а скорее начнётся с

!include include/default_my.cnf

и затем добавит необходимые изменения.

Синтаксис шаблона my.cnf такой же, как у обычного файла my.cnf , с некоторыми расширениями и предположениями. Они следующие:

• Для любой группы с именем [mysqld.N], где N — число, mtr запустит один mysqld процесс. Обычно требуется только группа [mysqld.1] и группа [mysqld.2] для тестов репликации.

• Могут быть группы с нестандартными именами ([foo], [bar], любые), не используемые mysqld. Файлы suite.pm (см. ниже) могут использовать их каким-то образом.

• Значения могут ссылаться друг на друга с помощью синтаксиса @groupname.optionname — эти ссылки будут расширены по мере необходимости. Например,

  [mysqld.2]
  master-port= @mysqld.1.port
  

• он устанавливает значение master-port в группе [mysqld.2] в значение port в группе [mysqld.1].

• Имя параметра может начинаться с символа решётки #. В результирующем my.cnf файле это будет выглядеть как комментарий, но на него всё ещё можно ссылаться. Например:

[example]
#location = localhost:@mysqld.1.port
bar = server:@example.#location/data

• Есть группа [ENV] . Она устанавливает значения для переменных окружения. Например,

  [ENV]
  MASTER_MYPORT = @mysqld.1.port
  

• Также можно ссылаться на значения переменных окружения через эту группу:

  [mysqld.1]
  user = @ENV.LOGNAME
  

• Есть группа [OPT] . Она позволяет вызывать функции и генерировать значения. В настоящее время она содержит только один параметр — @OPT.port. Каждый раз, когда на этот параметр ссылаются в другой группе шаблона my.cnf, генерируется новое уникальное значение порта. Оно не будет совпадать ни с каким другим значением порта, используемым в этой сессии тестирования. Например,

  [ENV]
  SPHINXSEARCH_PORT = @OPT.port
  

Этот файл должен находиться в директории набора тестов.

другие *.cnf файлы

Для каждого файла теста somefile.test (но не для файлов включения), mtr будет искать файл somefile.cnf. Если такой файл существует, он будет использоваться в качестве шаблона вместо набора тестов my.cnf или шаблона по умолчанию include/default_my.cnf.

combinations файл

Файл combinations определяет несколько наборов альтернативных конфигураций, и каждый тест в этом наборе будет выполняться несколько раз — один раз для каждой конфигурации. Это можно использовать, например, для выполнения всех тестов репликации в наборе rpl для всех трёх режимов формата binlog (row, statement и mixed). Соответствующий файл combinations будет выглядеть следующим образом:

[row]
binlog-format=row

[stmt]
binlog-format=statement

[mix]
binlog-format=mixed

Он использует синтаксис файла my.cnf с группами (где имена групп определяют имена комбинаций) и параметрами. Но, несмотря на сходство, это не шаблон my.cnf , и он не может использовать расширения шаблонов. Вместо этого параметры из файла combinations добавляются в командную строку сервера. В этом отношении файл комбинаций ближе к файлу suite.opt . И также, как и он, файл комбинаций может использовать переменные окружения с помощью синтаксиса $NAME.

Не все тесты обязательно будут выполняться для всех комбинаций. Конкретный тест может потребовать выполнения только в одной определённой комбинации. Например, в репликации, если тест может выполняться только с форматом binlog row, у него будет --binlog-format=row в одном из файлов .opt . В этом случае mtr заметит, что в командной строке сервера уже есть параметр, соответствующий одной из комбинаций, и пропустит все остальные комбинации для этого конкретного теста.

Файл combinations должен находиться в директории набора тестов.

другие *.combinations файлы

Также как и с файлами *.opt, mtr будет использовать файл somefile.combinations для любого somefile.test и somefile.inc , который используется при тестировании. Эти файлы имеют точно такой же формат, что и файл набора тестов combinations.

Это может привести к множеству файлов комбинаций, влияющих на один файл теста (если тест включает два файла .inc , и у обоих есть соответствующие файлы .combinations ). В этом случае mtr выполнит тест для всех комбинаций комбинаций из обоих файлов. Например, в MariaDB 5.5, rpl_init.inc добавляет комбинации для row/statement/mixed, а have_innodb.inc добавляет комбинации для innodb/xtradb. Таким образом, любой тест репликации, использующий innodb, будет выполнен шесть раз.

suite.pm файл

Этот (необязательный) файл — модуль Perl. Он должен объявлять пакет, который наследует от My::Suite.

Этот файл должен обычно заканчиваться bless {} — то есть он должен возвращать объект этого класса. Он также может возвращать строку — в этом случае все тесты в наборе будут пропущены, а эта строка будет напечатана как причина (например, "PBXT engine wasn't compiled").

Класс набора тестов может определять следующие методы:

• config_files()
• is_default()
• list_cases()
• servers()
• skip_combinations()
• start_test()

Метод config_files() возвращает список дополнительных файлов конфигурации (помимо my.cnf), которые необходимы этому набору для создания. Для каждого файла он указывает функцию, которая создаст его, когда получит объект My::Config . Например:

sub config_files {(
    'config.ini' => \&write_ini,
    'new.conf'   => \&do_new
)}

Метод servers() возвращает список процессов, которые необходимо запустить для этого набора. Процесс задаётся как пара [regex, hash]. Регулярное выражение должно соответствовать разделу в шаблоне my.cnf (например, qr/mysqld\./ соответствует всем mysqld процессам), хэш содержит эти параметры:

sub servers {(
    qr/^foo$/ => { SORT => 200,  # start foo before mysqld
                   START => \&start_foo,
                   WAIT => \&wait_foo }
)}

См. набор sphinx для примера.

Метод list_cases() возвращает полный список тестов для этого набора. По умолчанию это будет список файлов с расширением .test, но без расширения. Этот список будет отфильтрован mtr, в зависимости от различных параметров mtr (--big-test, --start-from, и т. д.), объекту набора не нужно этого делать.

Метод start_test() запускает один процесс теста, по умолчанию он будет mariadb-test . См. набор unit для примера работы методов list_cases() и start_test().

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

sub skip_combinations {(
    'combinations' => [ 'mix', 'rpl' ],
    'inc/many.combinations' => [ 'a', 'bb', 'c' ],
    'windows.inc' => "Not on windows",
)}

Последняя строка заставит пропустить все тесты этого набора, которые включают windows.inc, по причине «Не на Windows».

Метод is_default() возвращает 1, если этот конкретный набор должен выполняться по умолчанию, когда сценарий mariadb-test-run.pl запускается без явного указания наборов тестов или тестовых случаев.

*.sh файлы

Для каждого тестового файла sometest.test mtr ищет sometest-master.sh и sometest-slave.sh. Если один из этих файлов найден, он будет запущен перед самим тестом.

*.require файлы

Эти файлы устарели. Не используйте их больше. Если вам нужно пропустить тест, используйте команду skip вместо этого.

*.rdiff файлы

Эти файлы также определяют, каким должен быть результат теста. Но в отличие от *.result файлов, они содержат патч, который должен быть применён к одному файлу результатов для создания нового файла результатов. Это очень полезно, когда результат какого-то теста в одной комбинации незначительно отличается от результата того же теста, но в другой комбинации. Или когда результат теста в наслоении отличается от результата теста в наложенном наборе.

Редактировать .rdiff файлы для обновления после изменения тестового файла довольно сложно. Но, к счастью, это никогда не требуется. Когда тест завершается неудачно, mtr создаёт файл .reject. Имея его, можно создать файл .rdiff так же просто (например)

diff -u main/foo.result main/foo.reject > main/foo,comb.rdiff
or
diff -u main/foo.result main/foo,comb.reject > main/foo,comb.rdiff

Некоторые примеры:

diff -u main/innodb_ext_key.result main/innodb_ext_key,off.reject > main/innodb_ext_key,off.rdiff

diff -u suite/sys_vars/r/sysvars_server_notembedded.result suite/sys_vars/r/sysvars_server_notembedded,32bit.reject > suite/sys_vars/r/sysvars_server_notembedded,32bit.rdiff

Примечание: Это также добавит отметку времени в файл .rdiff, поэтому, если вы отправляете патч, вы можете удалить его вручную. Если один и тот же файл .rdiff используется для нескольких комбинаций, было бы неплохо опустить в заголовке идентификатор комбинации, чтобы позволить git лучше упаковывать репозиторий. Пример:

--- testname.result
+++ testname.reject

Поскольку комбинация может быть частью имени файла .result или .rdiff, mtr должен искать результаты теста во многих разных местах. Например, рассмотрим тест foo.test в паре комбинаций aa,bb, который выполняется в наслоении rty набора qwe, другими словами, для теста, который mtr печатает как

qwe-rty.foo 'aa,bb'                     [ pass ]

Для этого теста результат может быть в

• либо .rdiff или .result файле
• либо в наслоении «rty/», либо в наложенном наборе «qwe/»
• с комбинациями в имени файла («,a», «,b», «,a,b» или без)

что означает, что любое из следующих 15 имён файлов может быть использовано:

1. rty/r/foo,aa,bb.result
2. rty/r/foo,aa,bb.rdiff
3. qwe/r/foo,aa,bb.result
4. qwe/r/foo,aa,bb.rdiff
5. rty/r/foo,aa.result
6. rty/r/foo,aa.rdiff
7. qwe/r/foo,aa.result
8. qwe/r/foo,aa.rdiff
9. rty/r/foo,bb.result
10. rty/r/foo,bb.rdiff
11. qwe/r/foo,bb.result
12. qwe/r/foo,bb.rdiff
13. rty/r/foo.result
14. rty/r/foo.rdiff
15. qwe/r/foo.result

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

Если этот найденный файл — .rdiff, mtr продолжает перебирать список, пока не найдёт первый .result файл. К этому .result файлу применяется .rdiff.

valgrind.supp файл

Этот файл определяет подавления valgrind, и он используется, когда mtr запускается с опцией --valgrind.