persona-dsl 2026.2.9
Persona DSL - Framework for implementing Screenplay pattern in Python tests
Requires Python: >=3.9

# persona-dsl: Фреймворк для автотестов на Python

`persona-dsl` — это современная библиотека для написания **E2E** и **API** автотестов, реализующая паттерн **Screenplay**.
Она предоставляет выразительный язык для описания сценариев, управляет браузером (через Playwright) и автоматически генерирует детальные отчеты Allure.

## 📦 Установка

```bash
pip install persona-dsl
python -m playwright install --with-deps
```

---

## 🚀 Быстрый старт

### 1. Описание страницы (Page Object)

В `persona-dsl` используется **Универсальная Архитектура Элементов**.
Основной класс `Page` сам является элементом-контейнером. Вложенные элементы добавляются через `add_element`.

```python
# pages/login_page.py
from persona_dsl.pages import Page
from persona_dsl.pages.elements import Input, Button

class LoginPage(Page):
    def __init__(self):
        super().__init__()
        # Имя атрибута (self.username) будет использовано как имя элемента в отчетах
        self.username = self.add_element(Input(xpath="//input[@id='user']", name="Логин"))
        self.password = self.add_element(Input(xpath="//input[@id='pass']", name="Пароль"))
        self.submit   = self.add_element(Button(xpath="//button[@type='submit']", name="Вход"))
```

### 2. Написание теста

Тесты пишутся в стиле "Persona делает действия":

```python
# tests/test_login.py
import pytest
from persona_dsl.ops.web import NavigateTo, Fill, Click
from persona_dsl.facts.web import CurrentPath
from persona_dsl.expectations.web import IsEqualTo
from pages.login_page import LoginPage

def test_login_flow(persona):
    login_page = LoginPage()

    # 1. Действия (Actions)
    persona.make(
        NavigateTo("/login"),
        Fill(login_page.username, "admin"),
        Fill(login_page.password, "secret"),
        Click(login_page.submit)
    )

    # 2. Проверка (Verification)
    # Получаем Факт (CurrentPath) и проверяем Ожидание (IsEqualTo)
    current_path = persona.get(CurrentPath())
    persona.check(current_path, IsEqualTo("/dashboard"))
```

---

## 🏗 Архитектура

### 1. Ключевые компоненты (Persona Core)

| Компонент | Назначение | Пример |
|-----------|------------|--------|
| **Persona** | Исполнитель. Хранит состояние и навыки. | `persona.make(...)` |
| **Skill** | "Навык". Дает доступ к инструментам. | `UseBrowser`, `UseAPI`, `UseDB` |
| **Ops** | Атомарная операция. Работает со Skill. | `Click`, `HttpRequest`, `ExecuteSQL` |
| **Step** | Бизнес-шаг. Группирует Ops. | `LoginStep`, `CreateOrder` |
| **Fact** | Запрос состояния (без изменений). | `CurrentPath`, `ElementText` |
| **Expectation** | Проверка значения. | `IsEqualTo`, `ContainsText` |

### 2. Универсальные Элементы (New!)

Больше нет разделения на `Element` и `ElementContainer`. Любой элемент может содержать другие элементы.

*   **`element.add_element(...)`**: Регистрирует дочерний элемент.
*   **Иерархия**: `Page -> Container -> Element`.
*   **Локаторы**: Строятся автоматически по цепочке родителей.

### 3. Генераторный подход
Все шаги (`Step`, `CombinedStep`) — это генераторы, которые "выдают" (`yield`) операции для исполнения Персоной. Это позволяет `persona-dsl` перехватывать каждый шаг, логировать его в Allure и обрабатывать ошибки.

---

## 🛠 Инструменты и Утилиты

### Генерация Page Objects
Не пишите селекторы вручную. Используйте генератор:

```bash
# Снять ARIA-снапшот и сгенерировать класс страницы
persona-page-gen --url http://localhost:8080 --output pages/home.py
```

### Генерация API клиентов
```bash
# Генерация из OpenAPI/Swagger
persona-api-gen --url http://api.example.com/openapi.json --output skills/my_api.py
```

### Запуск тестов

Тесты запускаются стандартной командой pytest:

```bash
pytest --env=dev tests/
```

---

## ⚙️ Конфигурация

### `conftest.py`
Декларативное описание навыков и ролей:
```python
PERSONA_SKILLS = [BaseSkill.BROWSER, BaseSkill.API]
```

### `config/{env}.yaml`
Параметры окружения (dev, test, prod). Выбирается через `--env=test`.

### Примеры конфигурации

Ниже представлен **полный справочник** всех возможных настроек.
Большинство параметров унифицированы и работают идентично для **Локального** запуска и **Selenoid**.

#### Полный справочник (Global Reference)

Этот конфиг покрывает все возможности фреймворка. Неиспользуемые параметры можно опускать.

```yaml
skills:
  browser:
    default:
      base_url: "https://my-app.test" # URL должен быть внутри навыка
      
      # --- Базовые настройки (Basic) ---
      type: chromium           # Тип: chromium, firefox, webkit, sberbrowser, msedge
      headless: true           # true = без UI (в контейнере тоже работает)
      channel: chrome          # (Optional) Канал: chrome, msedge, chrome-beta
      executable_path: ""      # (Optional) Кастомный путь к бинарнику
      version: "128.0"         # (Optional) Версия (для Selenoid или скачивания)
      
      # --- Размеры и Тайминги (Dimensions & Timings) ---
      viewport:
        width: 1920
        height: 1080           # Всегда используйте многострочный формат для читаемости
      slow_mo: 50.0            # Задержка между действиями (мс)
      default_timeout: 30000.0 # Таймаут поиска элементов (мс)
      default_navigation_timeout: 30000.0 # Таймаут загрузки (мс)

      # --- Аргументы и Флаги (Arguments) ---
      # Применяются и локально, и удаленно (через goog:chromeOptions)
      no_sandbox: true         # --no-sandbox
      ignore_https_errors: true # --ignore-certificate-errors
      disable_features:        # --disable-features=...
        - SidePanel
        - SberWhatsNew
      args:                    # Дополнительные аргументы
        - "--start-maximized"
        - "--disable-notifications"
        - "--disable-gpu"

      # --- Удаленный запуск (Remote / Selenoid) ---
      # Если URL задан, тесты пойдут в облако/контейнер
      selenoid_url: "http://selenoid.company.com:4444"
      
      session_retries: 3       # Повторные попытки при ошибке создания сессии
      session_timeout: 60.0    # Таймаут ожидания слота (сек)
      
      selenoid_options:
        enableVNC: true        # Включить Live-просмотр
        enableVideo: false     # Включить запись видео
        # name/videoName проставляются автоматически
```



---

## 📊 Отчетность (Allure + TaaS)

Фреймворк автоматически:
1. Создает вложенные **Allure Steps** для каждого действия.
2. Прикрепляет **Скриншоты** и **Page Source** при падении.
3. Логирует **HTTP запросы/ответы** (если включено).
4. Интегрируется с платформой **TaaS** (Test as a Service) для аналитики.