tquality-py-core 0.1.4

Driver-agnostic core for tquality test automation (Selenium, Appium, WinAppDriver, etc.)

tquality-py-core

Независимое от драйвера ядро для автоматизации тестирования tquality. Предоставляет основу, на которой строятся пакеты, специфичные для драйверов (Selenium, Appium, WinAppDriver).

Компоненты

• BaseConfig - конфигурация на основе pydantic-settings с загрузкой из config.json5 (с поддержкой комментариев и висячих запятых через json5), переменных окружения и dotenv. Для добавления полей, специфичных для драйвера, используется наследование.
• Logger, LogLevel, step - журналирование в контексте одного теста с интеграцией allure. Уровни шагов: NORMAL, CRITICAL (снимок экрана в конце) и WITH_SCREENCAST (видеозапись шага через подключаемый поставщик).
• BaseForm - базовый класс для страниц и форм (страница - форма с полным контекстом).
• BaseElement - абстрактный интерфейс, который реализуют элементы, специфичные для драйвера.
• StringUtils - вспомогательные функции разбора строк.

Не входит в ядро

• Конкретная интеграция с драйверами (Selenium, Appium, WinAppDriver) - живёт в отдельных пакетах, зависящих от этого ядра.
• Типы элементов (Button, Input, Label и т. п.) - реализации, специфичные для драйвера, живут рядом с интеграцией драйвера.
• Настройка контейнера внедрения зависимостей - каждый использующий пакет собирает свой контейнер через dependency-injector, регистрируя службы ядра и службы, специфичные для драйвера.

Контракт интеграции

Использующие пакеты должны:

1. Наследовать BaseConfig с полями, специфичными для драйвера.
2. Зарегистрировать функцию получения Logger через set_logger_resolver(lambda: YourServices.logger()), где YourServices - контейнер использующего пакета. Это нужно, чтобы step() из ядра находил активный Logger в любом модуле.
3. При необходимости реализовать ScreenshotProvider / ScreencastProvider и внедрить их в Logger через контейнер, чтобы шаги уровня CRITICAL прикрепляли снимки экрана, а WITH_SCREENCAST - видеозапись (конкретный формат - на стороне поставщика, например webm в Selenium) к отчёту allure. Без поставщиков шаги проходят с предупреждением в журнал.
4. Предоставить конкретные подклассы BaseElement с логикой поиска и ожидания.

Требования

• Python 3.12+

Установка

Пакет публикуется в публичный PyPI. Это рекомендуемый способ установки для всех потребителей:

pip install tquality-py-core

или с использованием uv:

uv add tquality-py-core

В pyproject.toml потребителя:

dependencies = [
    "tquality-py-core>=0.1.3",
]

Альтернатива: установка из GitHub-зеркала

Если нужна сборка из исходников (например, для проверки коммита, ещё не вышедшего в релиз), пакет также доступен из публичного GitHub-зеркала по тегу:

uv pip install "tquality-py-core @ git+https://github.com/Tquality-ru/tquality-py-core.git@v0.1.3"

В этом случае hatch у потребителя требует явного разрешения direct-references:

[tool.hatch.metadata]
allow-direct-references = true

CLI

После установки доступна команда tquality-config:

tquality-config init        # сгенерировать config.json5 со значениями по умолчанию
tquality-config schema      # сгенерировать schema/config.schema.json (для сопровождающих)

Сгенерированный config.json5 включает ссылку на JSON-схему, опубликованную через jsDelivr. Адрес автоматически привязан к версии пакета: при установке выпущенной версии (0.1.3) → @v0.1.3, при установке невыпущенной версии (+g..., .dev) → @master:

{
    "$schema": "https://cdn.jsdelivr.net/gh/Tquality-ru/tquality-py-core@v0.1.3/schema/config.schema.json",
    // Комментарии поддерживаются - можно пояснить выбор значения.
    "base_url": "http://localhost",
    "default_timeout": 10.0,
    "log_dir": "logs",
    "highlight_elements": false,
}

Редакторы с поддержкой JSON Schema (VS Code, JetBrains IDE) автоматически подсказывают доступные поля и проверяют значения. Синтаксис jsonc/json5 позволяет оставлять комментарии // и /* */ и висячие запятые.

Разработка

См. CONTRIBUTING.md для инструкций по настройке окружения разработчика, установке перехватчиков git и проверке типов mypy.

CI/CD

GitLab CI запускает две проверки на каждом MR и на master:

• mypy - строгий режим проверки типов.
• tests - запуск pytest с отчётом JUnit.

При публикации тега git вида vX.Y.Z:

• publish-pypi - сборка (версия берётся из тега через hatch-vcs) и загрузка пакета в публичный PyPI. Требует переменную PYPI_TOKEN в настройках CI/CD (protected, masked).
• publish - дублирующая публикация в GitLab Package Registry (внутреннее зеркало).
• mirror-to-github - master и сам тег отправляются в https://github.com/Tquality-ru/tquality-py-core (ветки feature/* на зеркало не копируются).

История версий - в CHANGELOG.md.

Зачем это существует

Отделяет универсальные шаблоны (журналирование, объекты страниц, загрузка конфигурации) от кода, специфичного для драйвера. Appium и WinAppDriver повторно используют ту же модель объектов страниц, отчётность по шагам и конвейер конфигурации без обязательной зависимости от Selenium.