Metadata-Version: 2.4
Name: tquality-py-core
Version: 0.1.4
Summary: Driver-agnostic core for tquality test automation (Selenium, Appium, WinAppDriver, etc.)
Project-URL: Homepage, https://github.com/Tquality-ru/tquality-py-core
Project-URL: Repository, https://github.com/Tquality-ru/tquality-py-core
Project-URL: Issues, https://github.com/Tquality-ru/tquality-py-core/issues
Project-URL: Changelog, https://github.com/Tquality-ru/tquality-py-core/blob/master/CHANGELOG.md
Author: ООО «Точка качества»
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: allure,appium,page-object,qa,selenium,test-automation,testing,tquality,winappdriver
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: allure-python-commons>=2.13
Requires-Dist: dependency-injector>=4.41
Requires-Dist: json5>=0.9
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# 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](https://pypi.org/project/tquality-py-core/).
Это рекомендуемый способ установки для всех потребителей:

```bash
pip install tquality-py-core
```

или с использованием [uv](https://docs.astral.sh/uv/):

```bash
uv add tquality-py-core
```

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

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

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

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

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

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

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

## CLI

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

```bash
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`:

```jsonc
{
    "$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](CONTRIBUTING.md) для инструкций по настройке окружения
разработчика, установке перехватчиков git и проверке типов mypy.

## CI/CD

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

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

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

- **`publish-pypi`** - сборка (версия берётся из тега через `hatch-vcs`)
  и загрузка пакета в публичный
  [PyPI](https://pypi.org/project/tquality-py-core/). Требует переменную
  `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](CHANGELOG.md).

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

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