AndreyAkinshin / Russian-Phd-LaTeX-Dissertation-Template

LaTeX-template for russian Phd thesis

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Внедрение юнит-тестирования шаблона

petRUShka opened this issue · comments

Во избежание проблем и регрессий (a la #362) возможно стоит использовать gstest (или какой-то другой инструмент для юнит-тестирования в latex) + что-то типа скрипта, запускающего тесты через разные docker-образы (непрерывная интеграция).

Есть несколько веток на SE, как раз на тему тестирования latex.

Например в этой ветке одно из решений: генерировать pdf, дальше проверять его с помощью pdf-parser и очень удобного фреймворка rspec на языке Ruby.

Вот ещё обсуждение полезное: https://tex.stackexchange.com/questions/42328/testing-framework-api-for-latex

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

Полезное чтиво по истории вопроса в применении к шаблону.
#152

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

возможно, для этих счётчиков очень было бы уместно юнит-тестирование (см. #364).

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

@Lenchik, если это правильно сделать и прикрутить непрерывную интеграцию (Travis мб), то, например, будет видно, что пул-реквест что-то ломает, и попросить потенциального контрибьютора учесть это.

Ну да. Именно так.

если это правильно сделать

связано с

написание и отлаживание всех тестов, а также слежение за написанием тестов (повышение порога входа) для новых элементов, если они появятся. И это вообще с непонятными сроками.

===============

прикрутить непрерывную интеграцию (Travis мб)

Это связано с

сделать без ключей от owner проекта.

А @AndreyAkinshin не поддерживает проект более? Мб форк тогда?

@Lenchik а подойдут ли Deploy Keys? Они намного лучше с точки зрения безопасности, т.к. по ним доступ есть только к одному репозиторию, в отличии от Personal access tokens, которые дают доступ сразу ко всему аккаунту. Вроде бы люди успешно настраивают Travis с использованием Deploy Keys (см. "Deploy to GitHub Pages using Travis CI and deploy keys", "How to push to github from Travis CI").

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

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

@Lenchik, готов написать тест (rspec + pdf-parser), который будет проверять. Но не уверен, что будет возможность разобраться с автоматическим созданием N pdf для каждой из поддерживаемых версий tex (образов docker). Если бы кто-то сделал эту часть -- готов взять тесты на себя.

@seregaxvm Посмотрите, пожалуйста, это обсуждение.
@petRUShka

автоматическим созданием N pdf для каждой из поддерживаемых версий

Без этого тесты бесполезны?

На каком этапе понадобятся deploy keys репозитория?

Но не уверен, что будет возможность разобраться с автоматическим созданием N pdf для каждой из поддерживаемых версий tex (образов docker).

Этой командой можно собрать примеры для texlive vanilla на основе debian 10.

docker run --rm -v $(pwd):/data matsievskiysv/rus_phd:2019.10.10 examples

Можно ещё таких образов наклепать, но надо определиться с версиями и дистрибутивами, для которых требуется проверка.

если это правильно сделать и прикрутить непрерывную интеграцию (Travis мб)

Похожее обсуждение в #152

Без этого тесты бесполезны?

Подходов к тестированию latex много. Я предлагаю использовать следующий.

Для каждого элемента списка версий tex (docker-образов) делать следующее:

  1. Генерить pdf, в котором демонстрируется та или иная возможность (например, явно выводятся значения счётчиков или наличиствуют два списка библиографии и т.п.)
  2. Далее воспользоваться следующим подходом: с помощью мощного и удобного фреймворка тестирования RSpec (язык Ruby) писать тесты, которые, в сущности, парсят с помощью ruby-библиотеки pdf-reader полученный pdf и сравнивают его содержимое с эталонным. Если оно не соответствуют эталонному -- тест падает. Если соответствует -- всё чики-поки.

Пример конфига для Travis (система непрерывной интеграции). Пример теста (Ruby знать не обязательно, там всё читается и так).

На каком этапе понадобятся deploy keys репозитория?

Думаю, на этапе интеграции Travis.

Таким образом, я бы считал, что нам необходимы следующие этапы:

  1. Выписать список всех нужных версий tex (docker-образов).
  2. Для каждого из них написать скрипт, который генерирует pdf, подлежащие тестированию.
  3. После этого прогнать серию тестов, которая проверяет каждый из pdf-файлов на предмет выполнения нужных нам условий (travis + rspec).

Собственно, я готов подключиться на этапе №3 (rspec к сгенерённым pdf).

Для каждого из них написать скрипт, который генерирует pdf, подлежащие тестированию.

Что для данного пункта нужно помимо уже реализованного скрипта make examples?

Не хватает:

  1. Списка docker-образов для тестирования.
  2. Скрипта, который выполняет указанные make_examples для каждого из docker-образов.

Видимо, во втором случае следует распихать pdf-ники полученные по папочкам (названным в честь docker-образов).

  1. Конфига travis, который приводит запуску скрипта, и генерации pdf для разных версий tex.

Сборка docker образов:

> docker build --tag=diser:2019 --file=texlive:2019.dockerfile .
> docker build --tag=diser:vanilla --file=texlivevanilla.dockerfile .

Сборка примеров:

> bash script.sh

Файл texlive:2019.dockerfile:

FROM debian:buster AS base

# tex source directory shell be mounted here
WORKDIR /data
VOLUME /data

# set UTF encoding
ENV LANG=C.UTF-8 LC_ALL=C.UTF-8 TERM=xterm

# install fonts and basic programs
RUN echo 'deb http://deb.debian.org/debian/ buster contrib' >> /etc/apt/sources.list.d/msfonts.list \
    && echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections \
    && apt-get update -q \
    && DEBIAN_FRONTEND=noninteractive \
                      apt-get install -qy --no-install-recommends \
                      make \
                      wget \
                      unzip \
                      perl \
                      fonts-liberation \
                      fontconfig \
                      texlive-full \
                      ca-certificates \
    && DEBIAN_FRONTEND=noninteractive \
                      apt-get install -qy --no-install-recommends ttf-mscorefonts-installer \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && luaotfload-tool --update --force \
    && fc-cache -f -v \
    && tlmgr init-usertree

FROM base AS pscyr

# # cannot use installer with sh
RUN wget https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/raw/master/PSCyr/pscyr0.4d.zip -O pscyr.zip \
    && unzip pscyr.zip \
    && cd pscyr \
    && TEXMF=$(kpsewhich -expand-var='$TEXMFMAIN') \
    && mkdir -p $TEXMF/dvips \
    && mv -t $TEXMF/dvips dvips/* \
    && mkdir -p $TEXMF/tex/latex/pscyr \
    && mv -t $TEXMF/tex/latex/pscyr tex/latex/pscyr/* \
    && mkdir -p $TEXMF/fonts/tfm/public/pscyr \
    && mv -t $TEXMF/fonts/tfm/public/pscyr fonts/tfm/public/pscyr/* \
    && mkdir -p $TEXMF/fonts/vf/public/pscyr \
    && mv -t $TEXMF/fonts/vf/public/pscyr fonts/vf/public/pscyr/* \
    && mkdir -p $TEXMF/fonts/type1/public/pscyr \
    && mv -t $TEXMF/fonts/type1/public/pscyr fonts/type1/public/pscyr/* \
    && mkdir -p $TEXMF/fonts/afm/public/pscyr \
    && mv -t $TEXMF/fonts/afm/public/pscyr fonts/afm/public/pscyr/* \
    && mkdir -p $TEXMF/doc/fonts/pscyr \
    && mv -t $TEXMF/doc/fonts/pscyr LICENSE doc/README.koi doc/PROBLEMS \
    && VARTEXFONTS=$(kpsewhich -expand-var='$VARTEXFONTS') \
    && rm -f $VARTEXFONTS/pk/modeless/public/pscyr/* \
    && mktexlsr \
    && rm -rf *

# USER 1000:1000 # does not work with lualatex
ENTRYPOINT ["make"]

Файл texlivevanilla.dockerfile:

FROM debian:buster AS base

# tex source directory shell be mounted here
WORKDIR /data
VOLUME /data

# set UTF encoding
ENV LANG=C.UTF-8 LC_ALL=C.UTF-8 TERM=xterm

# install fonts and basic programs
RUN echo 'deb http://deb.debian.org/debian/ buster contrib' >> /etc/apt/sources.list.d/msfonts.list \
    && echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections \
    && apt-get update -q \
    && DEBIAN_FRONTEND=noninteractive \
		      apt-get install -qy --no-install-recommends \
		      make \
		      wget \
		      unzip \
		      perl \
		      fonts-liberation \
		      fontconfig \
		      ca-certificates \
    && DEBIAN_FRONTEND=noninteractive \
    		      apt-get install -qy --no-install-recommends ttf-mscorefonts-installer \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && fc-cache -f -v


FROM base AS vanilla

# configure and run install-tl
# echo 'O\nL\n\n\n\nR\nS\ne\nR\nI\n' for minimal installation
RUN wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz -O install.tar.gz \
    && tar -xf install.tar.gz \
    && find . -maxdepth 1 -iname "install-tl-*" -type d -exec mv {} installer \; \
    && cd installer \
    && echo -n 'O\nL\n\n\n\nR\nI\n' | ./install-tl \
    && luaotfload-tool --update --force \
    && fc-cache -f -v \
    && cd .. \
    && rm -rf installer install.tar.gz \
    && tlmgr init-usertree

# FROM vanilla AS pscyr

# cannot use installer with sh
RUN wget https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/raw/master/PSCyr/pscyr0.4d.zip -O pscyr.zip \
    && unzip pscyr.zip \
    && cd pscyr \
    && TEXMF=$(kpsewhich -expand-var='$TEXMFMAIN') \
    && mkdir -p $TEXMF/dvips \
    && mv -t $TEXMF/dvips dvips/* \
    && mkdir -p $TEXMF/tex/latex/pscyr \
    && mv -t $TEXMF/tex/latex/pscyr tex/latex/pscyr/* \
    && mkdir -p $TEXMF/fonts/tfm/public/pscyr \
    && mv -t $TEXMF/fonts/tfm/public/pscyr fonts/tfm/public/pscyr/* \
    && mkdir -p $TEXMF/fonts/vf/public/pscyr \
    && mv -t $TEXMF/fonts/vf/public/pscyr fonts/vf/public/pscyr/* \
    && mkdir -p $TEXMF/fonts/type1/public/pscyr \
    && mv -t $TEXMF/fonts/type1/public/pscyr fonts/type1/public/pscyr/* \
    && mkdir -p $TEXMF/fonts/afm/public/pscyr \
    && mv -t $TEXMF/fonts/afm/public/pscyr fonts/afm/public/pscyr/* \
    && mkdir -p $TEXMF/doc/fonts/pscyr \
    && mv -t $TEXMF/doc/fonts/pscyr LICENSE doc/README.koi doc/PROBLEMS \
    && VARTEXFONTS=$(kpsewhich -expand-var='$VARTEXFONTS') \
    && rm -f $VARTEXFONTS/pk/modeless/public/pscyr/* \
    && mktexlsr \
    && rm -rf *

# USER 1000:1000 # does not work with lualatex
ENTRYPOINT ["make"]

Файл script.sh:

#!/bin/bash

RED='\033[0;31m'
NC='\033[0m'
DOCKER_IMAGES=('diser:2019' 'diser:vanilla')
BUILD=build

for i in "${DOCKER_IMAGES[@]}"; do
    echo -e "$RED"Processing "$i$NC"
    docker run --rm -v "$(pwd)":/data "$i" examples || continue
    mkdir -p "$BUILD/$i"
    mv -t "$BUILD/$i" *.pdf
done

Хорошо бы иметь ещё docker-образы с windows (https://hub.docker.com/_/microsoft-windows-base-os-images). MS шрифты с виндой идут немного другие, нежели могут устанавливаться в убунту, и отдельные результаты вёрстки работают по-разному (помню, что в Приложении по-разному отрабатывалась раскраска текста в длинных таблицах).

Хотелось бы иметь докеры для заглядывания в ещё более старые версии texlive (вплоть до TL2016 или какой там в ubuntu 16.04LTS) — чтобы можно было сравнить насколько всё плохо в старых версиях и для каких комбинаций настроек.

А можно в результате теста такого иметь табличку, где строки это варианты запуска, а в столбцах — системы на которых тест запускали (на пересечении прохождение теста. конечно)?

Думаю, на этапе интеграции Travis.

То есть можно попросить ключи и интегрировать Travis уже сейчас? Как вообще этот процесс интеграции должен происходить?

UPDATE:
Как должен отрабатываться юзкейс:

  • человек дописывает слайд с примером, исправляет опечатку в тексте или, опять же, дописывает какой-то блок с иллюстрацией (wrapfig в автореферате, как пример, когда-нибудь будет, надеюсь).

Все же пдф-примеры не соответствуют состоянию "эталона" даже если всё сработает наотлично? Или это учитывается?

Хорошо бы иметь ещё docker-образы с windows (https://hub.docker.com/_/microsoft-windows-base-os-images). MS шрифты с виндой идут немного другие, нежели могут устанавливаться в убунту, и отдельные результаты вёрстки работают по-разному (помню, что в Приложении по-разному отрабатывалась раскраска текста в длинных таблицах).

Насколько я понимаю запуск docker-образа с Windows невозможен из-под linux. См. дискуссию:

Q: Can Windows containers run on Linux?

A: No. They cannot. Containers are using the underlying Operating System resources and drivers, so Windows containers can run on Windows only, and Linux containers can run on Linux only.

То есть тут, кажется, не выйдет, если хочется виндовое протетсить нужно что-то хитрее типа vagrant (полноценная виртуализация), либо надо понять, умеет ли travis docker с windows из-под windows.

Хотелось бы иметь докеры для заглядывания в ещё более старые версии texlive (вплоть до TL2016 или какой там в ubuntu 16.04LTS) — чтобы можно было сравнить насколько всё плохо в старых версиях и для каких комбинаций настроек.

Поддерживаю!

А можно в результате теста такого иметь табличку, где строки это варианты запуска, а в столбцах — системы на которых тест запускали (на пересечении прохождение теста. конечно)?

Вот так выглядит пример, как это может выглядеть: https://travis-ci.org/simkimsia/UtilityBehaviors

Думаю, на этапе интеграции Travis.

То есть можно попросить ключи и интегрировать Travis уже сейчас? Как вообще этот процесс интеграции должен происходить?

Насколько я понимаю, в корень проекта добавляется .travis.yml типа такого, и дальше github сам всё запускает. Мб ещё где-то надо включить галочку.

UPDATE:
Как должен отрабатываться юзкейс:

человек дописывает слайд с примером, исправляет опечатку в тексте или, опять же, дописывает какой-то блок с иллюстрацией (wrapfig в автореферате, как пример, когда-нибудь будет, надеюсь).

Все же пдф-примеры не соответствуют состоянию "эталона" даже если всё сработает наотлично? Или это учитывается?

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

Я предлагаю сравнивать с эталоном по некоторым конкретным критериям (тест-кейсам, так называемым). Набор проверок будет пополняться. Примеры:

  1. Значение таких-то счётчиков равно тому-то (счётчики явно выведены как текст в pdf-файл).
  2. Размеры полей такие-то (для соответствия ГОСТ и т.п.).
  3. Библиографий 3 штуки отображаются на такой-то странице.

Т.е. система тестирования убеждается в успешном выполненнии ряда проверок.

Счётчики, по-моему, проще проверять по логу.

Кроме того, можно использовать что-то типа pdfminer.

pdf2txt.py file.pdf > /tmp/parsed.txt

Данная команда преобразовывает pdf в текстовый файл.
Например, parsed.txt.
В этом файле можно искать какие-нибудь ключевые слова и фразы.

система тестирования убеждается в успешном выполненнии ряда проверок

Получается, что можно тестируемые куски выделить какими-то «тегами»/условиями (или нетестируемое) в tex-коде, так чтобы на всё остальное тест внимания не обращал.

Счётчики, по-моему, проще проверять по логу.

Можно, но так будет унифицированный подход. Правильно ли будет отслеживать и логи и pdf?

Плюс, так мы будем ещё зависимы от формата логов (вдруго поменяется).

Кроме того, наш итоговый продукт -- это pdf. Правильнее его проверять, как мне кажется.

Кроме того, можно использовать что-то типа pdfminer.

Моё субъективное мнение, что RSpec -- лучший фреймворк для тестов. На Python есть ничего, но оооочень далеко от RSpec.

В логи можно писать ключевые слова. Например, сейчас в логах можно найти что-то типа

Selected options:
Draft mode: 0
Font: 2
AltFont: 1
Bibliography backend: 1
Precompile images: 0

Это добавлено из dissertation.tex и synopsis.tex командой typeout.
Плюс этого подхода в том, что формат сообщения контролируется из исходников, и его можно найти по установленному ключевому слову.

Моё субъективное мнение, что RSpec -- лучший фреймворк для тестов. На Python есть ничего, но оооочень далеко от RSpec.

pdfminer - это просто конвертер pdf в txt. Проверять его вывод можно и в RSpec

система тестирования убеждается в успешном выполненнии ряда проверок

Получается, что можно тестируемые куски выделить какими-то «тегами»/условиями (или нетестируемое) в tex-коде, так чтобы на всё остальное тест внимания не обращал.

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

В связи с появлением Actions в гитхабе и checks в пуллреквестах (https://help.github.com/en/actions/building-and-testing-code-with-continuous-integration/setting-up-continuous-integration-using-github-actions
https://developer.github.com/v3/checks/
)
@seregaxvm может быть, сможете посмотреть (сначала на своем форке, а потом и сюда внедрить) как сделать так, чтобы при появлении пуллреквестов можно было иметь список прохождения checks (для начала 3 компилятора х 3 вида работ (диссер, автореферат, презентация) х 2-3 версии texlive ([2018], 2019, 2020), хотя, конечно, можно и все проверяемые опции запуска использовать ), желательно в параллельных процессах/докерах? Чтобы видеть, что заканчиваются хотя бы без ошибок.
Кажется, что через Actions можно и без deploy keys скрипты автоматизации написать

Может больше подойдёт issue templates?

Вот пример использования.

Я так понимаю, что это просто равносильно надежде на то, что люди нормально тестируют именно то, что шлют (а там ещё разное с точки зрения gui, настроек типа -shell-escape, -interaction=nonstopmode). А в случае с continuous integration технологиями будет явный прогон независимой системой через хотя бы запросы make ... в каком-то режиме фейла если не работает

Думаю, templates можно сделать по крайней мере на время запуска этой системы, т.к. настройка templates тривиальна.

Пока что не понял, как github workflow отличается от travis-ci.

templates можно сделать по крайней мере на время запуска этой системы

PR welcome ;)

github workflow отличается от travis-ci

Вот я тыкаю Actions у репозитория и получаю
Снимок экрана от 2020-03-15 20-07-43

И тыкаю потом Set up у этого simple workflow:
Снимок экрана от 2020-03-15 20-10-52

И выходит, что не знаю, чем там по содержимому отличается, но, похоже, что может так удастся обойтись без deploy keys. В «идеальном мире»: написать там под несколько видов docker'ов c разными texlive с разными именованными jobs, в которых make что-то там и смотреть на пуллреквесте, какие успешно получат зеленые галочки (желательно, чтобы они там все параллельно запускались, если нет ограничений. И в marketplace справа там уже заготовки типа https://github.com/marketplace/actions/download-artifact

https://blog.martisak.se/2020/05/16/latex-test-cases/
Статья про тестирование latex

Заведена отдельная ветка для проб по юнит тестам - feature/unit-tests -
https://github.com/AndreyAkinshin/Russian-Phd-LaTeX-Dissertation-Template/tree/feature/unit-tests

В #424 добавлена инфраструктура для проведения тестов. Дело остаётся за малым - написать тесты для всех вариантов сборки документа. Хотя на том, что есть на данный момент, можно тестировать внедрение CI.