Разработка

Настройка локальной копии репозитория Wagtail git немного сложнее, чем использование готового релизного пакета Wagtail, так как для сборки JavaScript и CSS-активов требуется Node.js и NPM. (Это не требуется при использовании релизной версии, так как скомпилированные активы включены в релизный пакет.)

Если вы предпочитаете развивать приложение на виртуальной машине, скрипты vagrant-wagtail-develop и docker-wagtail-develop являются наиболее быстрым способом начать работу. Они предоставят вам работающий экземпляр демонстрационного сайта Wagtail Bakery с кодовыми базами Wagtail и bakerydemo, доступными в качестве общих папок для редактирования на вашем хост-компьютере.

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

Если вы предпочитаете настроить все компоненты вручную, продолжайте читать. Эти инструкции предполагают, что вы знакомы с использованием pip и virtualenv для управления пакетами Python.

Настройка кодовой базы Wagtail

Установите Node.js версии 14. Вы также можете использовать менеджер версий Node (nvm), так как Wagtail предоставляет файл .nvmrc в корне проекта с минимально необходимой версией Node - см. инструкции по установке nvm.

Вам также потребуется установить библиотеки libjpeg и zlib, если вы этого еще не сделали - см. платформенно-зависимые инструкции по установке Pillow.

Скопируйте копию кодовой базы Wagtail:

$ git clone https://github.com/wagtail/wagtail.git
$ cd wagtail

При активированном вашем virtualenv установите пакет Wagtail в режиме разработки с включёнными зависимостями для тестирования и документации:

$ pip install -e .[testing,docs] -U
$ # or if using zsh as your shell:
$ #    pip install -e '.[testing,docs]' -U

Установите Node через nvm (необязательно):

$ nvm install

Установите инструменты для сборки статических активов:

$ npm install --no-save

Скомпилируйте активы:

$ npm run build

Все сайты Wagtail, запущенные в этом virtualenv, теперь будут работать с этим экземпляром Wagtail в режиме разработки. Мы рекомендуем использовать демонстрационный сайт Wagtail Bakery в качестве основы для разработки Wagtail. Имейте в виду, что шаги настройки сайта Wagtail могут включать установку релизной версии Wagtail, которая перепишет установленную вами версию разработки. В этом случае вы должны установить сайт перед выполнением шага pip install -e, или выполнить этот шаг повторно после установки сайта.

Тестирование

Из корня кодовой базы Wagtail выполните следующую команду для запуска всех Python-тестов:

$ python runtests.py

Запуск только некоторых тестов

На момент написания Wagtail имеет более 2500 тестов, что занимает много времени. Вы можете запустить тесты только для одной части Wagtail, передав путь в качестве аргумента в runtests.py или tox.

$ # Running in the current environment
$ python runtests.py wagtail.core

$ # Running in a specified Tox environment
$ tox -e py39-dj32-sqlite-noelasticsearch wagtail.core

$ # See a list of available Tox environments
$ tox -l

Вы также можете запустить тесты для отдельных TestCases, передав путь в качестве аргумента в runtests.py

$ # Running in the current environment
$ python runtests.py wagtail.core.tests.test_blocks.TestIntegerBlock

$ # Running in a specified Tox environment
$ tox -e py39-dj32-sqlite-noelasticsearch wagtail.core.tests.test_blocks.TestIntegerBlock

Выполнение миграций для моделей приложения тестов

Вы можете создать миграции для приложения тестов, выполнив следующую команду из корня Wagtail.

$ django-admin makemigrations --settings=wagtail.tests.settings

Тестирование против PostgreSQL

Примечание

Для запуска этих тестов необходимо установить необходимые модули для PostgreSQL, как описано в документации Django по базам данных.

По умолчанию Wagtail тестируется против SQLite. Вы можете переключиться на использование PostgreSQL, используя аргумент --postgres.

$ python runtests.py --postgres

Если вам нужен другой пользователь, пароль, хост или порт, используйте переменные окружения PGUSER, PGPASSWORD, PGHOST и PGPORT соответственно.

Тестирование против другой базы данных

Примечание

Для запуска этих тестов необходимо установить необходимые библиотеки и модули для заданной базы данных, как описано в документации Django по базам данных или документации 3-сторонних бекендов базы данных.

Если вам нужно протестировать против другой базы данных, установите переменную окружения DATABASE_ENGINE на имя Django-бекенда базы данных для тестирования:

$ DATABASE_ENGINE=django.db.backends.mysql python runtests.py

Это создаст новую базу данных под названием test_wagtail в MySQL и запустит тесты против неё.

Если вам нужны различные параметры подключения, используйте следующие переменные окружения, соответствующие соответствующим ключам в словаре настроек Django DATABASES:

DATABASE_ENGINE
DATABASE_NAME
DATABASE_PASSWORD
DATABASE_HOST
- Обратите внимание, что для MySQL это должно быть 127.0.0.1 вместо localhost, если вам необходимо подключиться через TCP-сокет
DATABASE_PORT

Также можно установить DATABASE_DRIVER, что соответствует значению driver в OPTIONS, если используется движок SQL Server.

Тестирование Elasticsearch

Вы можете протестировать Wagtail против Elasticsearch, передав аргумент --elasticsearch в runtests.py:

$ python runtests.py --elasticsearch

Wagtail попытается подключиться к локальному экземпляру Elasticsearch (http://localhost:9200) и использовать индекс test_wagtail.

Если ваш экземпляр Elasticsearch расположен в другом месте, вы можете установить переменную окружения ELASTICSEARCH_URL для указания его местоположения:

$ ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py --elasticsearch

Unit-тесты для JavaScript

Мы используем Jest для unit-тестов клиентской бизнес-логики или UI-компонентов. Из корня кодовой базы Wagtail выполните следующую команду для запуска всех фронтенд unit-тестов:

$ npm run test:unit

Интеграционные тесты

Наш набор тестов браузера для end-to-end также использует Jest, совместно с Puppeteer. Мы настроили его для отдельной установки, чтобы не увеличивать размер установки существующих инструментов Node. Для запуска тестов вам необходимо установить зависимости и запустить сервер Django в режиме разработки:

$ export DJANGO_SETTINGS_MODULE=wagtail.tests.settings_ui
$ # Assumes the current environment contains a valid installation of Wagtail for local development.
$ ./wagtail/tests/manage.py migrate
$ ./wagtail/tests/manage.py createcachetable
$ DJANGO_SUPERUSER_EMAIL=admin@example.com DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=changeme ./wagtail/tests/manage.py createsuperuser --noinput
$ ./wagtail/tests/manage.py runserver 0:8000
$ npm --prefix client/tests/integration install
$ npm run test:integration

Интеграционные тесты по умолчанию нацелены на http://localhost:8000. Используйте переменную окружения TEST_ORIGIN для использования другого порта или тестирования удалённого экземпляра Wagtail: TEST_ORIGIN=http://localhost:9000 npm run test:integration.

Поддержка браузеров и устройств

Wagtail предназначен для использования на широком спектре устройств и браузеров. Поддерживаемые версии браузеров/устройств включают:

Браузер	Устройство/ОС	Версия(и)
Mobile Safari	iOS Phone	Последние 2
Mobile Safari	iOS Tablet	Последние 2
Chrome	Android	Последние 2
Chrome	Рабочий стол	Последние 2
MS Edge	Windows	Последние 2
Firefox	Рабочий стол	Последняя
Firefox ESR	Рабочий стол	Последняя
Safari	macOS	Последние 3

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

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

Копирование и вставка форматированного текста в редактор форматированного текста.
Прикреплённая панель инструментов в редакторе форматированного текста.
Стиль выделения фокуса в главном меню и меню проводника.
Доступ с клавиатуры к действиям в таблицах списка страниц.

Неподдерживаемые браузеры/устройства:

Браузер	Устройство/ОС	Версия(и)
Стандартный браузер	Android	Все
IE	Рабочий стол	Все
Safari	Windows	Все

Цели доступности

Мы хотим сделать Wagtail доступным для пользователей широкого спектра вспомогательных технологий. Конкретный стандарт, на который мы нацелены, — WCAG2.1, уровень AA. Вот конкретные вспомогательные технологии, для которых мы стремимся к тестированию и, в конечном счете, поддержке:

NVDA на Windows с Firefox ESR
VoiceOver на macOS с Safari
Увеличение масштаба Windows и Zoom на macOS
Распознавание речи Windows и Dictation на macOS
Мобильный VoiceOver на iOS или TalkBack на Android
Режим высокой контрастности Windows

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

react-axe интегрирован непосредственно в наши средства сборки, чтобы определять подлежащие выполнению действия проблемы. Журналирует результаты в консоли браузера.
@wordpress/jest-puppeteer-axe выполняет проверки Axe в рамках интеграционных тестов.
Axe расширение Chrome для более всестороннего автоматизированного тестирования данной страницы.
Accessibility Insights for Web расширение Chrome для полуавтоматизированного тестирования и ручных аудитов.

Известные проблемы с доступностью

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

Сводка задач WCAG2.1 AA для администрирования CMS.
Наш аудит доступности 2021 года.

В аудиторском отчете также указано, какие части Wagtail были и не были протестированы, как проблемы влияют на соответствие WCAG 2.1 и каково возможное влияние на пользователей.

Компиляция статических ресурсов

Все статические ресурсы, такие как JavaScript, CSS, изображения и шрифты для администрирования Wagtail, компилируются из соответствующих источников с помощью gulp. Скомпилированные ресурсы не добавляются в репозиторий и компилируются перед пакетированием каждого нового выпуска. Скомпилированные ресурсы не должны отправляться в рамках запроса на добавление.

Для компиляции ресурсов выполните:

$ npm run build

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

$ npm start

Компиляция документации

Документация Wagtail создается с помощью Sphinx. Для установки Sphinx и компиляции документации выполните:

$ cd /path/to/wagtail
$ # Install the documentation dependencies
$ pip install -e .[docs]
$ # or if using zsh as your shell:
$ #    pip install -e '.[docs]' -U
$ # Compile the docs
$ cd docs/
$ make html

Скомпилированная документация теперь будет находиться в docs/_build/html. Откройте эту папку в веб-браузере, чтобы просмотреть её. Python поставляется с модулем, который позволяет очень просто просматривать статические файлы в веб-браузере. Для запуска этого простого сервера выполните следующие команды:

$ cd docs/_build/html/
$ python -mhttp.server 8080

Теперь вы можете открыть <http://localhost:8080/> в своём веб-браузере, чтобы увидеть скомпилированную документацию.

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

$ cd docs/
$ make clean
$ make html

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

$ cd docs/
$ make livehtml