persona-dsl 26.1.20.9

DSL для реализации паттерна Screenplay в Python-тестах.

persona-dsl: Руководство пользователя

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

1. Основные концепции

В основе фреймворка лежат шесть ключевых компонентов, которые вместе описывают любое взаимодействие с системой.

• Persona: "Действующее лицо" или актор, который выполняет действия в тесте. Это главный объект, через который вы будете работать.
• Skill: "Навык" или способность Персоны взаимодействовать с системой. Например, UseBrowser для работы с веб-интерфейсом или UseAPI для запросов к API.
• Ops: Низкоуровневая, техническая операция (клик, HTTP-запрос). Единственный компонент, который может напрямую использовать Skill.
• Action: "Действие", атомарная бизнес-операция, которая может изменять состояние системы. Состоит из последовательности Ops.
• Fact: "Факт" о состоянии системы. Действие, которое не изменяет состояние, а только запрашивает данные. Также состоит из Ops.
• Expectation: "Ожидание", которое проверяет, соответствует ли Fact определенному условию (например, IsEqualTo("some text")).
• Goal: "Цель", высокоуровневый бизнес-сценарий, объединяющий несколько Action и Fact.

2. Стиль написания тестов

Фреймворк предлагает единый, пошаговый стиль написания тестов, который легко читать и поддерживать.

• Выполнение действий: persona.make(Action(...), Goal(...))
• Получение данных: data = persona.get(Fact(...))
• Проверки: persona.check(data, Expectation(...))

# test_login.py
from persona_dsl.ops.web import NavigateTo, Fill, Click
from persona_dsl.facts.web import CurrentPath
from persona_dsl.expectations.generic import IsEqualTo
from tests.pages.login_page import LoginPage # Пример объекта страницы

def test_login_flow(persona):
    login_page = LoginPage()

    # Действия
    persona.make(
        NavigateTo("/login"),
        Fill(login_page.username_field, "testuser"),
        Fill(login_page.password_field, "password"),
        Click(login_page.submit_button)
    )

    # Получение факта
    current_path = persona.get(CurrentPath())

    # Проверка
    persona.check(current_path, IsEqualTo("/dashboard"))

3. Встроенная функциональность ("Батарейки в комплекте")

Ядро поставляется с pytest-плагином, который предоставляет полезные фикстуры и автоматизирует рутинные задачи.

3.1. Фикстуры

• persona: Главная фикстура. Создает экземпляр Persona для теста и автоматически наделяет её нужными навыками.
• config: Загружает конфигурацию из файлов config/*.yaml и секреты из .env.* в зависимости от окружения (--env=...).
• testdata: Удобная фабрика для загрузки тестовых данных из tests/data/*.{yaml,yml,json}.

3.2. Автоматическая интеграция с Allure

Вам не нужно вручную создавать шаги в отчете, фреймворк делает это за вас:

• Каждый вызов persona.make(), persona.get() и persona.check() автоматически оборачивается в allure.step().
• Текст шага генерируется из метода _get_step_description(), который вы реализуете в своих компонентах.
• Результат, полученный Фактом (Fact), автоматически логируется во вложенном шаге.
• Навык UseAPI по явной настройке (log_bodies=True) прикрепляет к отчёту полные тела запросов и ответов.

3.3. Автоматические артефакты при падении теста

При падении любого теста, который использовал браузер, фреймворк автоматически собирает артефакты для отладки и прикладывает их к Allure-отчету:

• Скриншот последней активной страницы.
• HTML-код страницы (page source).

Оба этих параметра включены по умолчанию. Их можно отключить в файле config/{env}.yaml в секции reporting:

# config/dev.yaml
reporting:
  screenshot_on_fail: false
  pagesource_on_fail: false

3.4. Декораторы для тестов

Ядро предоставляет удобные декораторы для работы с pytest:

• @tag("smoke", "regression"): Позволяет назначать тестам теги (pytest-маркеры).
• @data_driven(...): Упрощает параметризацию тестов, позволяя загружать тестовые данные из списков или файлов в tests/data/*.{yaml,yml,json}.
• @parametrize_simple(...): Обёртка над pytest.mark.parametrize для простых наборов данных.

Динамические данные в @data_driven (SystemVar)

Вы можете использовать генераторы данных (SystemVar) прямо в ваших YAML/JSON файлах для параметризации.

Для этого используется специальная JSON-структура:

{
  "kind": "system",
  "name": "имя_провайдера",
  "args": { "аргумент": "значение" }
}

Доступные провайдеры (name):

• uuid(): Детерминированный UUID v4.
• randomInt(min, max): Случайное целое число.
• randomFloat(min, max, precision): Случайное число с плавающей точкой.
• randomString(length, alphabet?): Случайная строка.
• now(fmt?, tz?): Текущая дата/время.
• dateShift(days, fmt?, tz?): Дата со сдвигом.
• fromEnv(name, default?): Значение из переменной окружения.
• faker(provider, locale?, ...): Данные из библиотеки Faker.
• sequence(name, seed?): Детерминированная числовая последовательность.
• concat(parts: list): Склеивает строки.
• template(pattern, variables): Форматирует строку по шаблону.

Пример (tests/data/dynamic_users.yaml):

- test_id: "user-1"
  payload:
    username:
      kind: system
      name: randomString
      args: { length: 8 }
    email:
      kind: system
      name: faker
      args: { provider: "email" }

Все значения генерируются детерминированно на основе run_id, env и variant_id (test_id), что обеспечивает воспроизводимость тестов.

4. Конфигурация и Декларация (conftest.py)

Вся настройка фреймворка — декларативная и сосредоточена в tests/conftest.py.

4.1. Декларация в conftest.py

1. class Roles(BaseRole): Enum-класс для объявления всех кастомных ролей (например, ADMIN).
2. class Skills(BaseSkill): Класс для объявления всех именованных навыков (например, REPORTING_API).
3. PERSONA_SKILLS = [...]: Список всех навыков, используемых в проекте, для строгой валидации конфигурации.
4. PERSONA_ROLES = Roles: Регистрация ролей для валидации.

# tests/conftest.py
from persona_dsl import BaseRole, BaseSkill, SkillId

class Roles(BaseRole):
    ADMIN = "admin"

class Skills(BaseSkill):
    REPORTING_API = (SkillId.API, "reporting")

PERSONA_ROLES = Roles
PERSONA_SKILLS = [
    BaseSkill.BROWSER,
    BaseSkill.API,
    Skills.REPORTING_API,
]

4.2. Структура конфигурации

• config/{env}.yaml: Параметры для окружения (URL, настройки headless и т.д.).
• config/auth.yaml: Секреты и учетные данные.

При запуске плагин автоматически проверяет, что для каждой роли и навыка из conftest.py есть соответствующая конфигурация в YAML.

5. Готовые компоненты (Ops)

Ядро persona-dsl поставляется с набором готовых Ops для всех поддерживаемых Skill'ов.

• persona_dsl.ops.web: NavigateTo, Click, Fill, PressKey, ElementText, ElementIsVisible, PageScreenshot, PageAriaSnapshot и др.
• persona_dsl.ops.api: JsonAs (для отправки запросов и валидации ответа по Pydantic модели), SendRequest.
• persona_dsl.ops.db: FetchOne, FetchAll, ExecuteSQL.
• persona_dsl.ops.kafka: SendMessage, MessageInTopic.
• persona_dsl.ops.soap: CallOperation, OperationResult.

6. Генераторы кода

Для ускорения разработки persona-dsl включает два генератора:

• persona-page-gen: Интерактивно создает классы Page из ARIA-снимка веб-страницы.
• persona-api-gen: Генерирует Pydantic-модели и классы Action/Fact из спецификации OpenAPI.

Это позволяет быстро создавать основу для PageObjects и API-клиентов, сокращая рутинную работу.