Skip to content

Testing

Jump to bottom
Nikita Kataev edited this page Oct 13, 2021 · 5 revisions

Для автоматизации процесса функционального тестирования в системе SAPFOR используется CTest, входящий в состав CMake и инструмент для автоматизации выполнения задача PTS, написанный на языке программирования Perl. Большинство тестов распространяются ввиде отдельных репозиториев, которые могут быть запущены на предварительно собранной системе SAPFOR или включены в состав собираемой системы. В последнем случае репозитории с тестами должны быть выгружены в директорию extensions, расположенную в корне рабочей копии рапозитория SAPFOR.

Для автоматизации процесса запуска тестов в системе SAPFOR используется инструмент sapfor-test. Чтобы включить его в процесс сборки системы, необходимо активировать опцию CMake BUILD_TESTING и задать путь до скрипта pts.pl в переменной PTS_EXECUTABLE.

Кроме того, данная опция включает в состав сборки в Microsoft Visual Studio проект RUN_TEST, сборка которого запустит все доступные в системе тестовые наборы. В случае использования инструмента make запустить тестирование можно, выполнив команду make test в каталоге сборки.

Замечание. Если тесты используются отдельно от основной сборки системы SAPFOR, то аналогичные возможности по использованию RUN_TEST или make test будут доступны в рамках проектов, соответсвующих отдельному репозиторию с тестами.

Инструмент sapfor-test использует систему PTS для автоматизированного запуска тестовых наборов, поэтому для его сборки и использования необходимо установить Perl вместе с модулями File::chdir, Text::Diff, Graph, Graph::Reader::Dot.

Таким образом для автоматизирвоанного запуска тестовых наборов необхоидмо:

  • установить CMake версии достаточной для сборки проектов системы SAPFOR;
  • установить Perl вместе с модулями File::chdir, Text::Diff, Graph, Graph::Reader::Dot;
  • загрузить PTS из репозитория на GitHub;
  • настроить переменные CMake BUILD_TESTION и PTS_EXECUTABLE при конфигурировании сборки системы SAPFOR;
  • загрузить репозиторий с тестами.

Установка необходимых модулей Perl

Для запуска тестовых наборов может потребоваться дополнительная установка модулей Perl. Если какие-либо из требуемых модулей не доступны, будет выдано сообщение об ошибке, например, на Ubuntu 18.04 такое сообщение имеет вид:

Can't locate File/chdir.pm in @INC (you may need to install the File::chdir module)

В тексте сообщения указывается название отсутствующего модуля, в данном случае это File::chdir.

Установить все требуемые модули можно с помощью менеджера пакетов Perl cpan, выполнив команду:

cpan File::chdir Text::Diff Graph Graph::Reader::Dot

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

Быстрый старт

Ниже приведена базовая последовательность действий необходимая для начала работы с репозиторием, содержащим тесты (на примере репозитория tsar-test и систему Ubuntu 20.04 LTS). Рассматривается ситуация с ранее установленными системами LLVM, SAPFOR и PTS, включая инструмент sapfor-test.

Подробные разъяснения возможностей запуска существующих и добавления новых тестов приведены в последующих разделах.

# Загрузка репозитория с GitHub.
git clone https://github.com/dvm-system/tsar-test

# Настройка репозитория с тестами.
cd tsar-test
mkdir build && cd build
cmake .. -DPTS_EXECUTABLE=<path-to-pts> -DTSAR_DIR=<path-to-tsar> -DDVM_DIR=<path-to-dvm>
cmake --build .

# Запуск тестового набора
cd ../tests/analysis/canonical_loop
sapfor-test ./pass

# Изучение результатов последнего запуска тестового набора
sapfor-test show ./pass

# Удаление последних результатов запуска тестового набора
sapfor-test clean ./pass

# Запуск отдельного теста из набора
sapfor-test canonical_loop_1/tsar

# Изучения реузльатов последнего запуска теста
sapfor-test show canonical_loop_1/tsar

# Создание эталонных результатов для теста
sapfor-test init canonical_loop_1/tsar

# Удаление последних результатов запуска теста
sapfor-test clean canonical_loop_1/tsar

Структура репозитория с тестами

Рассмотрим типовую структуру репозитория с тестами на примере репозитория tsar-test.

На верхнем уровне в репозитории содержатся две основные директории:

  • tests - содержит тестовые наборы;
  • sys - содержит инструменты для автоматизации процесса работы с тестами.

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

  • PTS_EXECUTABLE - задает путь до системы PTS (скрипта pts.pl);
  • PTS_OPTIONS - задает опции скрипта pts.pl используемые по-умолчанию при каждом запуске тестов;
  • TSAR_DIR - задает префикс для поиска CMake пакета TSAR; если репозиторий с тестами используется отдельно от сборки системы SAPFOR, то должен определять директорию расположения файла TSARConfig.cmake (например <install_dir>/lib/cmake/tsar>, если TSAR установлен в директорию <install_dir>);
  • LLVM_DIR - задает префикс для поиска CMake пакета LLVM; если репозиторий с тестами используется отдельно от сборки системы SAPFOR, то должен опредлять директорию расположения файла LLVMConfig.cmake (например <install_dir>/lib/cmake/llvm, если LLVM установлен в директорию <install_dir>);
  • DVM_DIR - задает путь до директории установки DVM системы (dvm_sys), если DVM система не установлена, то часть тестов запустить не удастся.

Для настройки репозитория с тестами необходимо запустить CMake задав необходимые опции (опции TSAR_DIR и LLVM_DIR могут быть определны автоматически, если инструмент CMake сможет найти соответствующие пакеты без подсказки пользователя) и выполнить сборку построенного проекта.

cd <path-to-repo>
mkdir build && cd build
cmake .. -DPTS_EXECUTABLE=<path-to-pts> -DTSAR_DIR=<path-to-tsar> -DDVM_DIR=<path-to-dvm>
cmake --build .

В результате будут созданы два основных конфигурационных файла:

  • sys/config - конфигурационный файл задающий основные параметры для автоматизации запуска тестов инструментами из sys;
  • .sapfortest - конфигурационный файл для запуска инструмента sapfor-test.

Замечание. Для систем сборки, таких как Microsfot Visual Studio, в которых одновременно доступно несколько конфигураций (Debug, Release, ...), при выборе некоторой конфигурации при настройке тестового репозитория будет выполнена попытка использовать систему SAPFOR, собранную в той же конфигурации. Если заданная конфигурация системы SAPFOR не будет найдена, то будет использована одна из доступных конфигураций.

Структура тестовых наборов

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

  • Pass... - отвечает за выполнение всех тестов из набора;
  • InitPass... - отвечает за инициализацию всех тестов из набора, в этом случае будут заново созданы все эталонные результаты для тестового набора, используемые для проверки успешного прохождения тестов;
  • Fail... - отвечает за выполнение всех тестов, для которых известно, что они не могут быть выполнены корректно;
  • InitFail... - отвечает за инициализацию всех тестов из набора, для которых известно, что они не могут быть выполнены корректно (так как данные тесты отражают некорректное поведение системы, то в общем случае их инициализция (создание эталонных результатов запуска) должна выполняться вручную);
  • Clean... - удаляет результаты последнего запуска всех тестов из набора, относящихся как к успешно выполняемым тестам, так и к тестам, отражающи некорректное поведение системы.

Рассмотрим возможности выполнения тестовых наборов на примере запуска тестов из репозитория tsar-test, содержащего базовое множество тестов для инструмента TSAR.

Например, на Linux системах, для тестирования прохода анализатора TSAR, отвечающего за определение циклов, представленных в канонической форме, можно выполнить команду:

make PassClangCanonicalLoop

В результате будет выведена информация о статусе выполнения каждого теста из набора:

[100%] Run task set 'pass' for the '-clang-canonical-loop' pass...
ok............ canonical_loop_1/tsar
ok............ canonical_loop_10/tsar
ok............ canonical_loop_11/tsar
ok............ canonical_loop_12/tsar
ok............ canonical_loop_13/tsar
ok............ canonical_loop_14/tsar
ok............ canonical_loop_15/tsar
ok............ canonical_loop_16/tsar
ok............ canonical_loop_17/tsar
ok............ canonical_loop_18/tsar
ok............ canonical_loop_2/tsar
ok............ canonical_loop_3/tsar
ok............ canonical_loop_4/tsar
ok............ canonical_loop_5/tsar
ok............ canonical_loop_6/tsar
ok............ canonical_loop_7/tsar
ok............ canonical_loop_8/tsar
ok............ canonical_loop_9/tsar
ok............ global_1/tsar
ok............ global_2/tsar
ok............ global_3/tsar
total time = 0.229

statistics:
num total    = 21
num complete = 21
num skipped  = 0
num failed   = 0
[100%] Built target PassClangCanonicalLoop

Запуск данного тестового набора с помощью инструмента sapfor-test будет выглядеть следующим образом:

cd <path-to-tsar-test>/tests/analysis/canonical_loop
sapfor-test ./pass

Замечания. Использование инструмента sapfor-test возможно только внутри директорий репозитория с тестами. Это связано с тем, что после конфигурирования и сборки репозитория с тестами в корневой директории репозитория размещается файл .sapfortest. Данный файл необходим для корректного использования sapfor-test, поэтому sapfor-test должен быть запущен из директории, совпадающей или расположенной ниже в иерархии директорий с директорией, содержащей файл .sapfortest.

Для инициализации тестов, просмотра последних результатов запуска и удаления этих результатов можно использовать следующие команды соответственно:

sapfor-test init ./pass
sapfor-test show ./pass
sapfor-test clean ./pass

Добавление тестов в существующие тестовые наборы для TSAR

Директории, содержащие отдельные тесты, образуют отдельный тестовый набор.

Структура теста

Каждому тесту из набора соответствует отдельная директория, включающая:

  • входные данные, например, один или несколько файлов с исходным кодом;
  • эталонные результаты, используемые для проверки корректности теста;
  • один или несколько конфигурационных файлов, описывающих правила выполнения теста.

Отдельный тест включает как минимум один конфигурационный файл, описывающий правила выполнения теста. Так как каждый конфигурационный файл в системе PTS в общем случае задает отдельную независимую от других конфигурационных файлов последовательность действий, будем говорить, что в рамках одного теста конфигурационный файл порождает под-тест. И один тест в системе SAPFOR может содержать несколько под-тестов (например, запуск инструмента TSAR, компиляция преобразованной программы, запуск преобразованной программы).

Конфигурационный файл содержит определения переменных, часть из которых имеет зарезервированные имена и определяет правила выполнения теста, а другая часть может состоять из локально объявленных новых переменных, позволяющих упростить структуру конфигурационного файла. Во время обработки конфигурационного файла конструкции вида $variable будут заменены на значение переменной variable, которая может быть задана либо внутри конфигурационного файла до ее использования, либо может являться параметром запуска теста или иметь значение по умолчанию. Кроме того, конфигурационный файл может содержать комментарии, начинающиеся с префикса #. Чтобы продлить текущую строку на следующую строку, в конце строки можно добавить символ \.

Каждый конфигурационный файл в системе PTS имеет две зарезервированные переменные:

  • plugin - задает модуль PTS, отвечающий за выполнение данного теста, все используемые модули определены в tsar/utils/Plugins/ (в большинстве случаев используется модуль TsarPlugin);
  • name - уникальные идентификатор теста в тестовом наборе, если данная переменная не задана явно в конфигурационном файле, то она устанавливается равной имени конфигурационного файла (без расширения), если в конфигурационном файле присваивается несколько значений данной переменной, то для именования теста используется результат последнего присваивания.

Кроме того плагин TsarPlugin резервирует для своего выполнения дополнительные переменные, которые должны быть заданы внутри конфигурационного файла, либо указаны при каждом запуске теста отдельно.

Рассмотрим переменные, которые обычно доступны извне конфигурационного файла и задаются отдельно для каждого запуска теста. Данные переменные в большинстве случаев задаются неявно при конфигурировании проектов SAPFOR перед их сборкой или внутри тестовой утилиты sapfor-test. Некоторые переменные устанавливает плагин PTS, отвечающий за запуск тестов:

  • perl - путь до используемой версии Perl;
  • sys_dir - путь до системной директории внутри используемого репозитория с тестами (обычно это директория sys в корне репозитория), например, в данной директории могу быть расположены вспомогательные файлы, необходимые для запуска тестов; в качестве примера можно рассмотреть скрипт filters/output.pl, входящий в состав репозитория tsar-test и удаляющий из переданного ему на вход файла платформа зависимые пути.
  • clang - путь до используемой версии компилятора Clang;
  • tsar - путь до используемой версии инструмент TSAR;
  • include - список дополнительных путей до заголовочных файлов, которые должны быть использованы при запуске инструмента TSAR и компилятора Clang;
  • dvm - путь до скрипта dvm, отвечающего за компиляцию и запуск DVMH программ;
  • platform - тип платформы, на которой выполняется запуск;
  • exe_extension - расширение, используемое в имени исполняемых фалов на текущей платформе $platform (например .exe для ОС Windows);
  • run_prefix - префикс, предшествующий имени запускаемого исполняемого файла в зависимости от платформы (./ - для OC Linux, пустой префикс для ОС Windows);
  • env:: - группа переменных, устанавливающая значения переменных окружения перед запуском теста, например env::DVMH_NUM_CUDAS=1 установит значение переменной окружения DVMH_NUM_CUDAS для запуска DVMH программы, соответствующей данному тесту, на графическом ускорителе.

Каждый тест может выполняться в нескольких режимах, режим определяется значением переменной $action, задаваемой при его запуске:

  • init - инициализирует тест, создавая эталонные результаты его запуска; уже существующие эталонные результаты будут заменены на новые;
  • check - использует существующие эталонные результаты, чтобы проверить корректность выполнения теста (по умолчанию переменная $action получает значение check);
  • clean - удалят результаты последнего запуска теста; при этом удаляются только те файлы, которые были явно перечислены при задании переменной $clean;
  • show - показывает результат последнего запуска теста, и если результат запуска отличается от эталонного результата, то отображает найденные различия.

Во время выполнения теста происходит следующая последовательность действий:

  1. В директории теста создается отдельная директория, если она еще не была создана, для хранения результатов выполнения теста. Чтобы явно задать имя рабочей директории для выполнения теста, можно использовать переменную $work_dir.

  2. В директорию результатов копируются все файлы необходимые для выполнения теста: копируемые файлы должны быть заданы переменной $copy. Копирование выполняется с сохранением иерархии директорий. Если переменная не задана или в ней не указан ни один файл, то копирование выполняться не будет.

  3. Выполняется переход в директорию результатов, которая становится рабочей, и запуск всех последующих команд будет осуществляться из этой директории.

  4. Выполняется команда выполнения теста, заданная переменной $run. Данную команду рекомендуется формировать независимым от платформы образом, чтобы запуск тестов был возможен на произвольной платформе. Для этой цели доступны дополнительные переменные, имеющие платформа зависимые значения, такие как $run_prefix и $exe_extension. Кроме того, перед выполнением данной команды будут установлены переменные окружения, заданные в группе env, а также к переменным окружения C_INCLUDE_PATH и CPLUS_INCLUDE_PATH будут добавлены пути, указанные в переменной $add_include_path.

  5. В зависимости от режима выполнение теста выполняется сравнение полученных результатов (режим check) с эталонными или их копирование в директорию с эталонными результатами (режим init). Чтобы задать имя директории с эталонноыми результатами можно использовать переменную $sample_dir, имеющую значение sample по умолчанию. Например, можно создать директорию, имя которой зависит от используемой платформы для запуска тестов (sample_dir=sample_$platform). Сравниваемые (копируемые) результаты (файлы) должны быть указаны в одной из следующих переменных внутри конфигурационного файла:

    • sample - список имен сравниваемых (копируемых) файлов; данная переменная используется в том случае, если имена эталонного файла и соответствующего файла, порождаемого результатом запуска теста, совпадают;
    • sample_map - список пар имен сравниваемых (копируемых) файлов; каждая пара содержит имя одного из файлов, порождаемого результатом запуска теста, и имя соответствующего эталонного файла. Имя файла с результатом указывается относительно директории с результатами, а имя файла эталона относительно $samlple_dir.

Таким образом, основными переменными, описывающими правила выполнения под-теста являются $copy, $run, $sample, $sample_map, $sample_dir, $work_dir, $clean, $add_include_path.

Пример теста

В качестве примера рассмотрим тест dvmh_sm_6 из репозитория tsar-test и набора tests/transform/dvmh_sm. Данный тест отвечает за проверку корректности автоматического распараллеливания С программ на системы с общей памятью в модели DVMH.

Данный тест расположен в директории dvmh_sm_6 и имеет следующую структуру:

  • main.c - исходная последовательная программа,

  • include/main.h - заголовочный файл в поддиректории include с объявлением глобальных переменных,

  • tsar.conf - конфигурационный файл для генерации параллельной DVMH версии программы инструментом TSAR;

  • compile.conf - конфигурационный файл для компиляции генерируемой DVMH-программы;

  • run.conf - конфигурационный файл для запуска скомпилированной DVMH-программы;

  • seq.conf - конфигурационный файл для компиляции и запуска последовательной программы;

  • sample - директория с эталонными результатами выполнения теста, которая содержит:

    • main.c - параллельная DVMH-программа;
    • include/main.h - заголовочный файл в поддиректории include;
    • output.txt - вывод на стандартный поток вывода и стандартный поток ошибок, генерируемый инструментом TSAR в процессе распараллеливания программы;
    • compile.txt - вывод на стандартный поток вывода и стандартный поток ошибок, генерируемые компилятором DVMH-программ;
    • run.txt - эталонный результат выполнения программы (последовательной или параллельной).

Конфигурационный файл tsar.conf имеет вид, приведенный ниже.

plugin = TsarPlugin
add_include_path = $include
sources = main.c
copy = $sources include/main.h
sample = $copy output.txt
clean = $sample *.c.orig
options = -clang-dvmh-sm-parallel -I include
run = "$tsar $sources $options 2>&1 | $perl -p $sys_dir/filters/output.pl >output.txt"

В данном файле для удобства дополнительно определены две локальные переменные $sources и $options. Переменная $sources содержит все исполняемые файлы, относящиеся к данному тесту, в данном случае единственный файл main.c. Эти файлы будут переданы на вход инструменту TSAR, передавать на вход заголовочные файл, как и при использовании обычного компилятора, не требуется. Переменная $options задает опции компиляции.

Для корректного разбора исходного кода программы инструментом TSAR могут потребоваться дополнительные заголовочные файлы, расположенные в директориях, задаваемых переменной $include. Поэтому в конфигурациооном файле используется переменная add_include_path для того, чтобы изменить переменные окружения устанавливаемые при запуске команды $run.

Кроме того, диагностические сообщения, генерируемые анализатором в процессе обработки программы и выдаваемые на стандарнтые потоки вывода и ошибок, могут содержать полные пути к обрабатываемым файлам. Чтобы привести генерируемые результаты к платформа независимому виду, в команде запуска под-теста $run выполняется их постобработка скриптом filters/output.pl, доступном в составе репозитория с тестами.

Чтобы выполнить под-тест, можно воспользоваться вспомогательной утилитой, входящей в состав SAPFOR sapfor-test.

cd ...tests/transform/dvmh_sm

sapfor-test init dvmh_sm_6/tsar
sapfor-test dvmh_sm_6/tsar:action=init

sapfor-test dvmh_sm_6/tsar

Первые два запуска являются алтернативными способами инициализации под-теста. Во втором случае режим выполнения задается явно в качестве параметра под-теста через переменную $action, в первом случае данная переменная устанавливается неявно командой init. Третий запуск происходит в режиме check (переменная $action получает данное значение по умолчанию).

В случае выполнения под-теста в режиме init на первом шаге в директорию с результатами запуска будут скопированы все исходные файлы, в том числе и заголовочные файлы, с сохранением иерархии директорий. Затем в этой директории будет выполнена команда $run, при этом путь до инструмента TSAR будет взят из переменной $tsar, которая будет задана утилитой sapfor-test. В результате в директории с результатами запуска исходный код последовательной программы будет модифицирован и будет сгенерирована параллельная версия программы с соответствующим изменением исходных файлов. Кроме того результаты запуска инструмента TSAR, выданные на стандартные потоки вывода и ошибок, будут записаны в файл output.txt. Затем параллельная версия программы, а также файл output.txt будут скопированы в директорию sample. В случае выполнения под-теста в режиме check, вместо копирования будет выполнено сравнение указанных файлов с соответствующими файлами в директории sample.

Важно иметь ввиду, что если какие-то исходные файлы не были модифицированы (например заголовочные файлы), то их рекомендуется копировать в директорию sample в любом случае (указывая их в переменной $sample). Это позволит избежать ситуации, когда при последующих изменения в инструменте TSAR эти файлы окажутся модифицируемыми, но запуск под-теста не позволит выявить изменение в поведении инструмента (если данные файлы отсутствуют в переменной $sample).

Если на разных платформах инструмент TSAR ведет себя по-разному, например, из-за особенностей построения внутреннего представления LLVM IR, используемого для анализа программ, то можно использовать переменную sample_dir=sample_$platform, чтобы создавать разные эталонные результаты на разных платформах. В некоторых случаях может быть достаточно использовать платформа зависимое имя output.$pltaform.txt, для хранения выходных результатов теста, не создавая для этого отдельную директорию. Стоит отметить, что перед выполнением под-теста в режиме проверки (check) на некоторой платформе необходимо убедится, что данный под-тест был инициализирован на данной платформе, то есть что существует соответствующая директория с эталонными результатами.

Также в конфигурационном файле задается переменная clean, в которой дополнительно для удаленя (в случае запуска под-теста в режиме clean) указаны файлы *.c.orig. Данные файлы создаются инструментом TSAR, в случае выполнение преобразований (распараллеливания) файлов программы, и содержат исходные версии файлов.

Конфигурационный файл compile.conf, отвечающий за компиляцию DVMH программ, имеет следующий вид.

plugin = TsarPlugin
sources = main.c
options = -o main$exe_extension -I include
sample = compile.txt
clean = $sample main$exe_extension
run = "$dvm c $sources $options >compile.txt 2>&1 | $perl -p $sys_dir/filters/output_dvm.pl >compile.txt"
[skip]
not_set = ::dvm

Фильтр output_dvm.pl, используемый для постобработки информации, генерируемой компилятором DVM системы, удаляет абсолютные пути, заменяя их на пути относительно директории установки DVM системы или текущей директории запуска компилятора, кроме того он удалет завершающий символ \n, который добавляет DVM система при запуске программ.

Группа переменных [skip] указывает условия, при которых данный под-тест не должен выполняться. В данном случае, если репозиторий с тестами был настроен без использования DVM-системы, то переменная $dvm не будет задана и выполнение данного под-теста становится невозможным.

В результате выполнения данного под-теста будут использованы исходные файлы DVMH-программы, уже расположенные в директории с результатами теста (после выполнения под-теста заданного файлом tsar.conf). Так как переменная $copy не задана, копирование дополнительных файлов в эту директорию не выполняется. В результате выполнения данного под-теста будут созданы два файла: compile.txt, содержащий выдачу в стандартный поток вывода и ошибок, и исполняемый файл с платформо зависимым расширением, задаваемым опцией $exe_extension. При этом в качестве результата данного под-теста, который будет скопирован в директорию sample (для которого будет выполнено сравнение с соответствующим файлом из директории sample), рассматривается только файл compile.txt.

Конфигурационный файл run.conf, отвечающий за запуск скомпилированных DVMH программ, имеет следующий вид.

plugin = TsarPlugin
output = run_nt${env::DVMH_NUM_THREADS}_nc${env::DVMH_NUM_CUDAS}_g${grid}.txt
sample_map = $output run.txt
clean = $output sts.gz+
run = "$dvm run $grid main${exe_extension} $grid 2>&1 | $perl -p $sys_dir/filters/output_dvm.pl >'$output.txt'"
[skip]
not_set = ::dvm

В данном случае конфигурация запуска DVMH-программы определяется тем, как были заданы переменные окружения (группа env::), а также переменной $gird, которая является параметром данного под-теста и указывается при запуске под-теста. При этом имя файла (переменная $output) с результатами запуска зависит от используемой конфигурации запуска, в то время как эталонный результат запуска содержится в файле run.txt, одинаковом для всех запусков под-теста (переменная $sample_map).

Стоит отметить, что переменная $grid может содержать последовательность чисел, разделенных пробелами, поэтому в командах использующих имя файла, включающее данную переменную, необходимо использовать кавычки.

Запуск под-теста может иметь следующий вид:

cd .../tests/transform/dvmh_sm
sapfor-test dvmh_sm_6/run:env::DVMH_NUM_THREADS=4,env::DVMH_NUM_CUDAS=0,grid="2 1"

Также возможна упрощенная версия запуска данного под-теста:

sapfor-test ./dvm dvmh_sm_6/run:grid="2 1"

В данном случае dvm - это конфигурационный файл, аналогичный по структуре стандартному скрипту запуска DVMH компилятора. Шаблон данного файла можно найти в директории $sys_dir/tasks. Для использования он может быть скопирован в директорию, из которой осуществляется вызов утилиты sapfor-test.

По умолчанию данный конфигурационный файл имеет следующий вид:

plugin = TsarEnv
#grid = ''

[env]
#--------------- One can set launch options:
# dvmwait=0 # Wait for task completion
# DVMH_PPN='' # Number of processes per node
# DVMH_STACKSIZE='' # Stack size to set for the task
DVMH_NUM_THREADS='1' # Number of CPU threads per process
DVMH_NUM_CUDAS='0' # Number of GPUs per process
# DVMH_CPU_PERF='' # Performance of all cores of CPU per process
# DVMH_CUDAS_PERF='' # Performance of each GPU per device
# DVMH_NO_DIRECT_COPY=0 # Use standard cudaMemcpy functions instead of direct copying with GPU

# DVMH_SPECIALIZE_RTC=1 # Use specialization algorithm to reduce CUDA kernel's resources / or compile kernels during execution without changes

#--------------- Debugging options:
# DVMH_LOGLEVEL=1 # Levels of debugging: 1 - errors only, 2 - warning, 3 - info, 4 - debug, 5 - trace
# DVMH_LOGFILE='dvmh_%d.log' # Log file name for each process
# DVMH_COMPARE_DEBUG=0 # An alternative way to turn comparative debugging mode on
# dvmsave=0 # Save convertation results
# dvmshow=0 # Show commands executed by the DVM driver

#--------------- CUDA profiling options:
# CUDA_PROFILE=0 # Enable/disable CUDA profiling
# CUDA_PROFILE_CONFIG='cuda.conf' # File with GPU's metrics
# CUDA_PROFILE_LOG='cuda_profile.%d.%p' # Output file name for each process
# CUDA_PROFILE_CSV=1 # Set CSV output format

Все переменные из группы [env] будут установлены как переменные окружения пред выполнением под-теста, переменная gird, если задана, будет передана в качестве параметра запуска под-теста. При этом значения переменных заданных явно в качестве параметров запуска под-теста в командной строке имеют приоритет перед переменными заданными в данном конфигурационном файле.

Конфигурационный файл seq.conf, отвечающий за компиляцию и запуск последовательной версии программы, имеет следующий вид.

plugin = TsarPlugin
add_include_path = $include
sources = main.c
copy = $sources include/main.h
work_dir = seq_res
sample = run.txt
clean = $copy $sample seq${exe_extension}
options = -O3 -o seq$exe_extension -I include
run = "$clang $sources $options && ${run_prefix}seq${exe_extension} >run.txt 2>&1"
[skip]
not_set = ::clang

В данном случае используется стандартный компилятор Clang для компиляции и запуска под-теста. Префикс ${run_prefix} позволяет отличить имя запускаемого файла от имени системной команды и в случае ОС Linux устанавливается ./. Можно заметить, что эталонным результатом для данного под-теста является только результат запуска программы (переменная $sample).

Данный под-тест, как и под-тест tsar выполняет копирование исходных файлов программы в рабочую директорию, но, в отличие от под-теста tsar, не меняет содержимое испходных файлов программы. Чтобы не возникало конфликтов между запусками разных под-тестов, для данного теста явно указана рабочая директория (переменная $work_dir).

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

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

Если используется файл seq.conf:

cd .../tests/transform/dvmh_sm
sapfor-test init dvmh_sm_6/tsar
sapfor-test init dvmh_sm_6/compile
sapfor-test init dvmh_sm_6/seq

Если достаточно запуска параллельной программы в какой-то конфигурации:

cd .../tests/transform/dvmh_sm
sapfor-test init dvmh_sm_6/tsar
sapfor-test init dvmh_sm_6/compile
sapfor-test init dvmh_sm_6/run:env::DVMH_NUM_THREADS=1,env::DVMH_NUM_CUDAS=0

Замечание. Вместо использования команды init можно явно указывать режим, в котором должен быть запущен под-тест, указывая :action=init после имени под-теста.

Структура тестового набора

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

  • pass - содержит список всех под-тестов, которые должны корректно обрабатываться текущей версией системы SAPFOR и DVM (соответствует проектам Pass..., InitPass..., а также является частью проекта Clean...);
  • fail - содежит список тестов, для которых в данный момент поведение системы SAPFOR считается либо не корректным, либо предполагающим возможность дальнейшей оптимизации (соответствует проектам с префиксом Fail..., InitFail..., а также является частью проекта Clean...).

Чтобы запустить на выполнения весь тестовый набор можно либо воспользоваться соответствующим проектом, создаваемым CMake при настройке репозитория с тестами, либо воспользоваться утилитой sapfor-test.

Например, запуск тестового набора pass из директории dvmh_sm будет выглядеть следующим образом:

cd .../tests/transform/dvmh_sm
sapfor-test ./pass

Рассмотрим более подробно структуру тестового набора на примере тестового набора pass, остальные тестовые наборы устроены аналогичным образом.

Тестовый набор представляет собой конфигурационный файл, описывающий параметры запуска каждого теста в наборе, а также правила параллельного и последовательного выполнения различных тестов/под-тестов набора. В тестовом наборе могут присутствовать области последовательного и параллельного выполнения тестов, которые могут быть вложены друг в друга. Чтобы ограничить область параллельного выполнения используются указания parallel, end_parallel. Чтобы ограничить область последовательного выполнения используются указания seq, end_seq, end_seq_seq. Спецификация end_seq_seq заканчивает одну последовательную область и начинает следующую. По умолчанию считается, что весь файл, соответствующий тестовому набору, является областью последовательного выполнения тестов. Границы областей и тесты должны быть указаны с новой строки.

parallel
  seq
    dvmh_sm_5/tsar
    dvmh_sm_5/compile
  end_seq_seq
    dvmh_sm_6/tsar
    dvmh_sm_6/compile
  end_seq
end_parallel

parallel
  dvmh_sm_5/run: env::DVMH_NUM_THREADS=1, env::DVMH_NUM_CUDAS=0
  dvmh_sm_5/run: env::DVMH_NUM_THREADS=2, env::DVMH_NUM_CUDAS=0
  dvmh_sm_6/run: env::DVMH_NUM_THREADS=1, env::DVMH_NUM_CUDAS=0
  dvmh_sm_6/run: env::DVMH_NUM_THREADS=2, env::DVMH_NUM_CUDAS=0
  seq
    dvmh_sm_5/run: env::DVMH_NUM_THREADS=0, env::DVMH_NUM_CUDAS=1
    dvmh_sm_6/run: env::DVMH_NUM_THREADS=0, env::DVMH_NUM_CUDAS=1
  end_seq
end_parallel

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

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

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

Итак сначала параллельно выполняется две группы тестов:

  • dvmh_sm_5, состоит из последовательной генерации параллельной программы (tsar) и ее компиляции (compile),
  • dvmh_sm_6, состоит из последовательной генерации параллельной программы (tsar) и ее компиляции (compile).

Затем выполняется группы тестов отвечающих за запуск, при этом параллельно выполняется 2 запуска теста dvmh_sm_5/run и два запуска теста dvmh_sm_6/run на мультипроцессоре. Одновременно с этим выполняются тесты на графическом ускорителе, при этом в каждый момент времени на графическом ускорителе выполняется только один тест.

Добавление тестов в набор

Таким образом, чтобы добавить новый тест в существующий тестовый набор необходимо:

  1. Создать отдельную директорию для теста внутри директории тестового набора.
  2. Внутри созданной директории добавить конфигурационные файлы (tsar - для тестирования только инструмента TSAR без последующего запуска тестовых программ, compile и run - для запуска параллельных DVMH-программ, seq - опционально, если требуется запуск исходной последовательной программы).
  3. Добавить правила запуска теста в файлы pass, fail или аналогичные файлы при необходимости.
  4. Внутри директории теста подготовить входные данные для запуска анализатора (исходный код программы).
  5. Получить эталонные результаты, если тест относится ко множеству pass.

Утилита sapfor-test и режимы запуска тестов

Утилита sapfor-test позволяет запускать либо один (под-)тест, либо тестовый набора, заданный соответсвующим файлом. Основные варианта запуска - следующие:

sapfor-test ./pass # указание префикса ./ необходимо, чтобы отличить набор ./pass от команды
sapfor-test <path-to-set>/pass # указание ./ не требуется, так как / встречается в имени набора
sapfor-test ./tsar # запуск отдельного подтеста в режиме по умолчанию (check)
sapfor-test init ./tsar # запуск отдельного подтеста в режиме инициализации (init)
sapfor-test <path-to-test>/tsar.conf # расширение .conf можно указывать явно

В случае ошибочного выполнения теста (нескольких тестов) в текущей директории создается файл f содержащий список всех проваленных тестов с описанием полной конфигурации запуска. Данный файл, как и файлы pass, fail является тестовым наборам и указанные в нем под-тесты могут быть запущены на выполнение утилитой sapfor-test. Также можно создавать дополнительные тестовые наборы при необходимости.

Чтобы посмотреть результаты запуска некоторого теста (тестового набора) можно использовать команду show. Данная команда сравнивает результаты последнего запуска под-теста (всех тестов из набора) с результатами эталоных запусков и, если они различаются, выводит разницу сравниваемых результатов. Если результаты совпадают или эталонный результат отсутствует, то результат запуска последнего под-теста (всех тестов из набора) выводится целиком.

Например, после того как в инструменте TSAR было реализовано добавление спецификации tie при построении DVMH-программ, результат сравнения последнего запуска под-теста tsar с эталонным результатом может выглядеть следующим образом:

sapfor-test show dvmh_sm_6/tsar

########## dvmh_sm_6/tsar ##########
#### main.c ####
  1: #include "main.h"
  2:
  3: int main() {
  4:   long S = 0;
  5:   for (int I = 0; I < N; ++I)
  6:     for (int J = 0; J < N; ++J)
  7:       for (int K = 0; K < 2; ++K)
  8:         A[I][J][K] = I + J + K;
  9:   for (int I = 1; I < N; ++I)
 10:     for (int J = 1; J < N; ++J)
 11:       for (int K = 0; K < 2; ++K)
 12:         A[I][J][K] = A[I - 1][J][K] + A[I][J - 1][K] + A[I][J][K];
 13:   for (int I = 0; I < N; ++I)
 14:     for (int J = 0; J < N; ++J)
 15:       for (int K = 0; K < 2; ++K)
 16:         S += A[I][J][K];
 17:   printf("Sum = 0\n", S);
 18:   return 0;
 19: }
#### include/main.h ####
#include <stdio.h>

#define N 10

long A[N][N][2];
#### sample/main.c <=> res/main.c ####
--- sample/main.c       Fri Feb 19 13:28:33 2021
+++ res/main.c  Fri Feb 19 13:28:45 2021
@@ -5,17 +5,17 @@
 #pragma dvm actual(A, S)
 #pragma dvm region in(A, S)out(A, S)
   {
-#pragma dvm parallel([I][J][K])
+#pragma dvm parallel([I][J][K]) tie(A[I][J][K])
     for (int I = 0; I < N; ++I)
       for (int J = 0; J < N; ++J)
         for (int K = 0; K < 2; ++K)
           A[I][J][K] = I + J + K;
-#pragma dvm parallel([I][J][K]) across(A [1:0] [1:0] [0:0])
+#pragma dvm parallel([I][J][K]) tie(A[I][J][K]) across(A [1:0] [1:0] [0:0])
     for (int I = 1; I < N; ++I)
       for (int J = 1; J < N; ++J)
         for (int K = 0; K < 2; ++K)
           A[I][J][K] = A[I - 1][J][K] + A[I][J - 1][K] + A[I][J][K];
-#pragma dvm parallel([I][J][K]) reduction(sum(S))
+#pragma dvm parallel([I][J][K]) tie(A[I][J][K]) reduction(sum(S))
     for (int I = 0; I < N; ++I)
       for (int J = 0; J < N; ++J)
         for (int K = 0; K < 2; ++K)
ok............ dvmh_sm_6/tsar
total time = 0.093

statistics:
num total    = 1
num complete = 1
num skipped  = 0
num failed   = 0

Чтобы удалить результаты последнего запуска под-теста можно воспользоваться командой clean утилиты sapfor_test:

sapfor_test clean dvmh_sm_6/tsar

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

Режимым запуска теста (переменная $action) соответсвуют команды утилиты sapfor-test c аналогичным названием.

Кроме того, команда do позволяет групировать несколько режимов запуска в рамках одной команды консоли:

sapfor-test do clean ./pass do ./pass do show ./f

В данном случае сначала будут удалены результаты последнего запуска всех тестов из набора pass, затем будет выполнен запуск всех тестов из набора и выведены результаты всех проваленных тестов вместе с исходными данными этих тестов.

Полный список всех команд можно посмотреть по опции -l.

Создание нового тестового набора

Чтобы создать новый тестовый набор необходимо (на пример репозитория tsar-test):

  1. Создать новую директорию, хранения всех тестов из набора. Директория должна быть расположена где-то в поддереве директорий с корнем в tests.
  2. На пути из директории tests до созданной директории добавить файлы CMakeLists.txt (при отсутствии), содержащие команды add_subdirectory(...) для вложенных директорий.
  3. Внутри директории тестового набора создать файл pass и, при необходимости, failили другие аналогичные файлы (имя файла f зарезервиовано для системных нужд и не должно быть использован).
  4. Внутри директории тестового набора создать файл CMakeLists.txt добавляющий данную директорию в список тестовых наборов.

Файл CMakeLists.txt внутри директории c тестами из набора должен иметь вид:

include(sapfor-testing)
sapfor_add_test(TARGET <test-set-name>
  TASKS "<test-set-list>" TEST <main-test-set> PASSNAME "<pass-name>")

В данном случае:

  • <test-set-name> задает имя тестового набора (для TSAR данное имя обычно совпадает с именем класса, реализующего тестируемый проход);
  • <pass-name> задает имя тестируемого прохода (для TSAR данное имя обычно совпадает с именем тестируемого прохода и/или командой запуска тестируемого прохода);
  • <test-set-list> - список из групп тестов, каждая группа тестов - это файл аналогичный pass, группы отделяются друг от друга ;; для каждой группы будет создан проект для запуска группы тестов, проект для инициализации (Init...), а также будет создан единый проект Clean... удаляющий результаты последнего выполнения всех под-тестов из всех групп.
  • <main-test-set> - основная тестовая группа, которая будет добавлена в список тестов инструмента CTest, данная группа будет выполнена при вызове комнады make test или сборке проекте RUN_TESTS в Microsoft Visual Studio.

Пример

Если создаваемый тестовый набор проверяет один из проходов преобразований, то соответствующая ему директория, например, de_decls, может быть расположена в поддиректории tests/transform. В этом случае на пути до de_delcs должны быть созданы следующие файлы CMakeLists.txt:

# CMakeLists.txt in 'tests'
add_subdirectory(transform)

# CMakeLists.txt in 'tests/transform'
add_subdirectory(de_decls)

Внутри директории replace должен быть создан файл CMakeLists.txt:

include(sapfor-testing)
sapfor_add_test(TARGET ClangDEDecls
  TASKS "pass;fail" TEST pass PASSNAME "-clang-de-decls")

В результате при конфигурировании и генерации проектов SAPFOR с помощью CMake будут созданы следующие проекты для запуска тестов: PassClangDEDecls, InitPassClangDEDecls, FailClangDEDecls, InitFailClangDEDecls, CleanClangDEDecls.

Написать нам можно через форму связи на сайте проекта DVM-системы.

Clone this wiki locally