persona-dsl 26.1.20.8__tar.gz

persona_dsl-26.1.20.8/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/persona_dsl/runtime/dist *.js

persona_dsl-26.1.20.8/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: persona-dsl
+Version: 26.1.20.8
+Summary: DSL для реализации паттерна Screenplay в Python-тестах.
+Requires-Python: >=3.9
+Requires-Dist: playwright==1.55.0
+Requires-Dist: pytest
+Requires-Dist: pytest-cov
+Requires-Dist: allure-pytest
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: requests
+Requires-Dist: pyhamcrest
+Requires-Dist: redis
+Requires-Dist: Faker
+Requires-Dist: pillow
+Requires-Dist: zeep
+Requires-Dist: pg8000
+Requires-Dist: oracledb
+Requires-Dist: kafka-python
+Requires-Dist: Unidecode>=1.3
+Requires-Dist: black
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-redis; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"

persona_dsl-26.1.20.8/README.md

@@ -0,0 +1,185 @@
+# 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(...))`
+
+```python
+# 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`:
+
+```yaml
+# 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-структура:
+```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`):**
+```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`**: Регистрация ролей для валидации.
+
+```python
+# 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-клиентов, сокращая рутинную работу.

persona_dsl-26.1.20.8/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "persona-dsl"
+version = "26.01.20.008"
+description = "DSL для реализации паттерна Screenplay в Python-тестах."
+requires-python = ">=3.9"
+dependencies = [
+    "playwright==1.55.0",
+    "pytest",
+    "pytest-cov",
+    "allure-pytest",
+    "python-dotenv",
+    "pyyaml",
+    "pydantic>=2,<3",
+    "requests",
+    "pyhamcrest",
+    "redis",
+    "Faker",
+    "pillow",
+    "zeep",
+    "pg8000",
+    "oracledb",
+    "kafka-python",
+    "Unidecode>=1.3",
+    "black",
+]
+[project.optional-dependencies]
+dev = [
+    "black",
+    "ruff",
+    "mypy",
+    "pytest-cov",
+    "pre-commit",
+    "types-requests",
+    "types-PyYAML",
+    "types-redis",
+    "pytest-asyncio",
+    "pytest-timeout",
+    "pytest-xdist",
+]
+
+[project.entry-points.pytest11]
+persona_dsl = "persona_dsl.pytest_plugin"
+
+[project.scripts]
+persona-page-gen = "persona_dsl.generators.cli:page_main"
+persona-api-gen = "persona_dsl.generators.cli:api_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+source = ["src/persona_dsl"]
+omit = [
+    # --- Компоненты, сложные для юнит-тестирования (снапшоты) ---
+    "src/persona_dsl/expectations/web/matches_screenshot.py",
+    "src/persona_dsl/expectations/web/matches_aria_snapshot.py",
+    # --- Файлы без исполняемой логики (базовые классы, Enum'ы, импорты) ---
+    "src/persona_dsl/__init__.py",
+    "src/persona_dsl/skills/__init__.py",
+    "src/persona_dsl/enums.py",
+    "src/persona_dsl/skill_id.py",
+    "src/persona_dsl/expectation.py",
+]
+parallel = true
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.mypy]
+python_version = "3.12"
+warn_unused_ignores = true
+warn_redundant_casts = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+strict_equality = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "persona_dsl.*"
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+ignore_errors = true
+

persona_dsl-26.1.20.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

persona_dsl-26.1.20.8/src/persona_dsl/__init__.py

@@ -0,0 +1,35 @@
+from .components.action import Action
+from .utils.decorators import data_driven, tag, parametrize_simple
+from .persona import BaseRole
+from .skills.core.skill_definition import BaseSkill
+from .components.expectation import Expectation
+from .components.fact import Fact
+from .components.goal import Goal
+from .persona import Persona
+from .skills.core.skill_definition import SkillId
+from .utils.waits import wait_until
+from .skills.core.base import Skill
+from .skills import UseAPI, UseBrowser, UseDatabase, UseKafka, UseSOAP
+from .components.step import Step
+
+__all__ = [
+    "Action",
+    "Expectation",
+    "Goal",
+    "Persona",
+    "Fact",
+    "SkillId",
+    "Step",
+    "data_driven",
+    "tag",
+    "parametrize_simple",
+    "BaseRole",
+    "BaseSkill",
+    "Skill",
+    "wait_until",
+    "UseAPI",
+    "UseBrowser",
+    "UseDatabase",
+    "UseKafka",
+    "UseSOAP",
+]

persona_dsl-26.1.20.8/src/persona_dsl/components/action.py

@@ -0,0 +1,10 @@
+from .step import Step
+
+
+class Action(Step):
+    """
+    Алиас для Step, предназначенный для story-стиля.
+    Не содержит собственной логики.
+    """
+
+    pass

persona_dsl-26.1.20.8/src/persona_dsl/components/base_step.py

@@ -0,0 +1,251 @@
+import json
+import logging
+import os
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Optional, TypeVar
+
+from allure import step
+
+from ..utils.artifacts import artifacts_dir
+from ..utils.metrics import metrics
+from ..utils.path import extract_by_path
+from ..utils.taas_integration import publish_taas_event
+from ..utils.retry import RetryPolicy
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound="BaseStep")
+
+
+class BaseStep(ABC):
+    """Единый базовый класс для всех исполняемых компонентов."""
+
+    # Политика ретраев по умолчанию для класса (может быть переопределена в наследниках)
+    retry_policy: Optional[RetryPolicy] = None
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self._instance_retry_policy: Optional[RetryPolicy] = None
+
+    def __repr__(self) -> str:
+        params = {k: v for k, v in self.__dict__.items() if not k.startswith("_")}
+        param_str = ", ".join(f"{k}={v!r}" for k, v in params.items())
+        return f"{self.__class__.__name__}({param_str})"
+
+    def with_retry(self: T, policy: RetryPolicy) -> T:
+        """
+        Возвращает копию шага с установленной политикой ретраев.
+        Полезно для ad-hoc настройки надежности в конкретном сценарии.
+        """
+        import copy
+
+        new_step = copy.copy(self)
+        new_step._instance_retry_policy = policy
+        return new_step
+
+    def _get_effective_retry_policy(self, persona: Any) -> RetryPolicy:
+        """Определяет актуальную политику ретраев (Instance > Class > Global Default)."""
+        # 1. Instance level (через .with_retry())
+        instance_policy = getattr(self, "_instance_retry_policy", None)
+        if instance_policy:
+            return instance_policy
+
+        # 2. Class level (атрибут класса)
+        if self.retry_policy:
+            return self.retry_policy
+
+        # 3. Global default from Persona config
+        # Ожидаем, что в persona.retries_config лежит dict, например:
+        # {'default': {...}, 'web_actions': {...}}
+        if hasattr(persona, "retries_config") and persona.retries_config:
+            # Можно усложнить логику и искать по типу шага (web_actions и т.д.)
+            # Пока берем 'default'
+            default_cfg = persona.retries_config.get("default")
+            if default_cfg:
+                return RetryPolicy(**default_cfg)
+
+        # 4. Hard fallback
+        return RetryPolicy(max_attempts=1)
+
+    def _get_component_type(self) -> str:
+        """
+        Определяет тип компонента на основе иерархии классов.
+        """
+        # Локальные импорты для разрыва циклической зависимости
+        from .goal import Goal
+        from .fact import Fact
+        from .action import Action
+        from .expectation import Expectation
+        from .combined_step import CombinedStep
+        from .step import Step
+        from .ops import Ops
+
+        if isinstance(self, Goal):
+            return "goal"
+        if isinstance(self, Fact):
+            return "fact"
+        if isinstance(self, Action):
+            return "action"
+        if isinstance(self, Expectation):
+            return "check"
+        if isinstance(self, CombinedStep):
+            return "combined_step"
+        if isinstance(self, Step):
+            return "step"
+        if isinstance(self, Ops):
+            if hasattr(self, "_component_type"):
+                comp_type = getattr(self, "_component_type")
+                if isinstance(comp_type, str):
+                    return comp_type
+            return "ops"
+        return "unknown"
+
+    def execute(self, persona: Any, *args: Any, **kwargs: Any) -> Any:
+        """
+        Универсальная обертка для выполнения шага с поддержкой ретраев.
+        """
+        description = self._get_step_description(persona)
+        start_time = time.time()
+        component_type = self._get_component_type()
+        policy = self._get_effective_retry_policy(persona)
+
+        params = {k: v for k, v in self.__dict__.items() if not k.startswith("_")}
+        publish_taas_event(
+            {
+                "event": "step_start",
+                "type": component_type,
+                "data": {
+                    "description": description,
+                    "timestamp": start_time,
+                    "component_name": self.__class__.__name__,
+                    "component_params": params,
+                    "max_attempts": policy.max_attempts,
+                },
+            }
+        )
+
+        value: Any = None
+        status = "passed"
+        attempt = 0
+        attempt = 0
+
+        try:
+            # Цикл ретраев
+            while True:
+                attempt += 1
+                try:
+                    with step(
+                        description
+                        if attempt == 1
+                        else f"{description} (попытка {attempt})"
+                    ):
+                        if attempt > 1 and policy.on_retry_action:
+                            step("Предварительное действие перед повтором")
+                            policy.execute_action()
+
+                        value = self._perform(persona, *args, **kwargs)
+                    break  # Успех
+                except Exception as e:
+                    if policy.should_retry(attempt, e):
+                        logger.warning(
+                            f"Шаг '{description}' упал (попытка {attempt}/{policy.max_attempts}): {e}. Ретрай через {policy.delay}с."
+                        )
+                        policy.wait(attempt)
+                    else:
+                        raise e
+
+            # Привязка результата
+            save_as = getattr(self, "save_as", None)
+            extract = getattr(self, "extract", None)
+            if save_as:
+                bound_value = (
+                    extract_by_path(value, extract)
+                    if isinstance(extract, str)
+                    else value
+                )
+                persona.memory[save_as] = bound_value
+
+            if value is not None:
+                with step(f"Получено значение: {str(value)[:100]}"):
+                    pass
+
+            return value
+
+        except Exception:
+            status = "failed"
+            raise
+        finally:
+            end_time = time.time()
+            duration = end_time - start_time
+            metrics.gauge(
+                "step.duration",
+                duration,
+                tags={
+                    "type": component_type,
+                    "name": self.__class__.__name__,
+                    "status": status,
+                },
+            )
+
+            event_data_end: dict[str, Any] = {
+                "description": description,
+                "timestamp": end_time,
+                "duration": duration,
+                "status": status,
+                "attempts_used": attempt,
+            }
+
+            result_raw: Any = None
+            result_raw_path: str | None = None
+            result_raw_url: str | None = None
+            if isinstance(value, (dict, list)):
+                result_raw = value
+                raw_dir = artifacts_dir("result_raw")
+                filename = f"{int(end_time * 1000)}-{self.__class__.__name__}.json"
+                file_path = raw_dir / filename
+                try:
+                    with open(file_path, "w", encoding="utf-8") as f:
+                        json.dump(result_raw, f, ensure_ascii=False, indent=2)
+                    result_raw_path = str(file_path)
+                    run_id = os.environ.get("TAAS_RUN_ID")
+                    result_raw_url = (
+                        f"/artifacts/{run_id}/result_raw/{filename}" if run_id else None
+                    )
+                except (IOError, TypeError) as e:
+                    logger.warning(
+                        f"Не удалось сохранить result_raw артефакт в {file_path}: {e}"
+                    )
+                    result_raw = None
+
+            event_data_end.update(
+                {
+                    "result": str(value)[:100] if value is not None else "None",
+                    "result_raw": result_raw,
+                    "bindings": {
+                        "save_as": getattr(self, "save_as", None),
+                        "extract": getattr(self, "extract", None),
+                    },
+                    "result_raw_path": result_raw_path,
+                    "result_raw_url": result_raw_url,
+                }
+            )
+
+            publish_taas_event(
+                {
+                    "event": "step_end",
+                    "type": component_type,
+                    "data": event_data_end,
+                }
+            )
+
+    @abstractmethod
+    def _get_step_description(self, persona: Any) -> str:  # pragma: no cover
+        """Возвращает текстовое описание шага для Allure."""
+        ...
+
+    @abstractmethod
+    def _perform(
+        self, persona: Any, *args: Any, **kwargs: Any
+    ) -> Any:  # pragma: no cover
+        """Содержит реальную логику выполнения шага."""
+        ...