persona-dsl 26.1.20.8__py3-none-any.whl

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/components/action.py

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

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
+        """Содержит реальную логику выполнения шага."""
+        ...

persona_dsl/components/combined_step.py

@@ -0,0 +1,68 @@
+from abc import abstractmethod
+from typing import Any, Generator
+
+from .base_step import BaseStep
+
+
+class CombinedStep(BaseStep):
+    """
+    Базовый класс для высокоуровневого, композитного шага (Combined Step),
+    который объединяет последовательность других шагов (Steps) для достижения
+    бизнес-цели. Управляется через генератор.
+
+    Также предоставляет метод make(persona) для story-стиля, который
+    просто вызывает execute(persona) без добавления логики.
+
+    Основной контракт — реализация генераторного метода _run(), который
+    позволяет описывать как простые последовательности Steps, так и сложную
+    логику с передачей результатов между ними.
+    """
+
+    def make(self, persona: Any) -> None:
+        self.execute(persona)
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> Any:
+        """
+        Исполняет генераторный сценарий из `_run`, передавая результаты
+        выполнения Steps обратно в генератор.
+        """
+        from .step import Step
+
+        gen = self._run(persona, *args, **kwargs)
+        try:
+            # Первый вызов для запуска генератора и получения первого шага
+            step_to_execute = gen.send(None)
+            while True:
+                # Проверяем, что из CombinedStep не yield'ят низко-уровневые Ops
+                if not isinstance(step_to_execute, (Step, CombinedStep)):
+                    raise TypeError(
+                        f"Компонент '{self.__class__.__name__}' (наследник CombinedStep) "
+                        f"может yield'ить только другие шаги (наследники Step/CombinedStep), "
+                        f"но был получен объект типа {type(step_to_execute).__name__}."
+                    )
+
+                # Выполняем полученный шаг
+                last_result = step_to_execute.execute(persona)
+                # Отправляем результат обратно в генератор и получаем следующий шаг
+                step_to_execute = gen.send(last_result)
+        except StopIteration as e:
+            # Генератор завершился (оператором return), его результат в e.value
+            return e.value
+
+    @abstractmethod
+    def _get_step_description(self, persona: Any) -> str:  # pragma: no cover
+        """Возвращает текстовое описание шага для Allure."""
+        ...
+
+    @abstractmethod
+    def _run(
+        self, persona: Any, *args: Any, **kwargs: Any
+    ) -> Generator[Any, Any, Any]:  # pragma: no cover
+        """
+        Декларативно-императивный контракт.
+        Yield'ит последовательность Steps и явно возвращает результат.
+        """
+        # Этот код нужен, чтобы сделать метод абстрактным генератором.
+        # В реальных реализациях он будет заменён.
+        if False:
+            yield

persona_dsl/components/expectation.py

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

persona_dsl/components/fact.py

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

persona_dsl/components/goal.py

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

persona_dsl/components/ops.py

@@ -0,0 +1,7 @@
+from .base_step import BaseStep
+
+
+class Ops(BaseStep):
+    """Базовый класс для всех низкоуровневых, исполняемых операций."""
+
+    pass

persona_dsl/components/step.py

@@ -0,0 +1,75 @@
+from typing import Any, Generator
+
+from .base_step import BaseStep
+
+
+class Step(BaseStep):
+    """
+    Базовый класс для доменно-ориентированных шагов (Steps),
+    которые инкапсулируют бизнес-логику и состоят из последовательности
+    низкоуровневых операций (Ops), управляемых через генератор.
+
+    Предоставляет универсальные методы-обёртки для разных стилей написания:
+    - perform_as(persona): story-стиль для действий
+    - get(persona): story-стиль для фактов (возвращает значение)
+    - check(persona, actual_value): story-стиль для проверок
+
+    Основной контракт — реализация генераторного метода _run(), который
+    позволяет описывать как простые последовательности Ops, так и сложную
+    логику с передачей результатов между операциями.
+    """
+
+    def perform_as(self, persona: Any) -> None:
+        self.execute(persona)
+
+    def get(self, persona: Any) -> Any:
+        return self.execute(persona)
+
+    def check(self, persona: Any, actual_value: Any) -> None:
+        self.execute(persona, actual_value)
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> Any:
+        """
+        Исполняет генераторный сценарий из `_run`, передавая результаты
+        выполнения Ops обратно в генератор.
+        """
+        from .ops import Ops
+
+        gen = self._run(persona, *args, **kwargs)
+        try:
+            # Первый вызов для запуска генератора и получения первой операции
+            op_to_execute = gen.send(None)
+            while True:
+                # Проверяем, что из Step yield'ят только Ops
+                if not isinstance(op_to_execute, Ops):
+                    raise TypeError(
+                        f"Компонент '{self.__class__.__name__}' (наследник Step) "
+                        f"может yield'ить только объекты-наследники Ops, "
+                        f"но был получен объект типа {type(op_to_execute).__name__}."
+                    )
+
+                # Выполняем полученную операцию
+                current_result = op_to_execute.execute(persona)
+                # Отправляем результат обратно в генератор и получаем следующую операцию
+                op_to_execute = gen.send(current_result)
+        except StopIteration as e:
+            # Генератор завершился (оператором return), его результат в e.value
+            return e.value
+
+    def _run(self, persona: Any, *args: Any, **kwargs: Any) -> Generator[Any, Any, Any]:
+        """
+        Декларативно-императивный контракт.
+        Yield'ит последовательность Ops и явно возвращает результат.
+
+        По умолчанию выбрасывает NotImplementedError. Наследники должны либо:
+        1. Реализовать этот метод (генераторный стиль).
+        2. Переопределить _perform (императивный стиль).
+        """
+        raise NotImplementedError(
+            f"Класс {self.__class__.__name__} должен реализовать метод '_run' (генераторный стиль) "
+            f"или переопределить метод '_perform' (императивный стиль)."
+        )
+        # Этот yield нужен, чтобы Python считал метод генератором (даже если он сразу падает)
+        # Это важно для статических анализаторов и некоторых проверок.
+        if False:
+            yield

persona_dsl/expectations/generic/__init__.py

@@ -0,0 +1,15 @@
+from .is_equal import IsEqualTo
+from .contains_the_text import ContainsTheText
+from .has_entries import HasEntries
+from .contains_item import ContainsItem
+from .is_greater_than import IsGreaterThan
+from .path_equal import PathEqual
+
+__all__ = [
+    "IsEqualTo",
+    "ContainsTheText",
+    "HasEntries",
+    "ContainsItem",
+    "IsGreaterThan",
+    "PathEqual",
+]

persona_dsl/expectations/generic/contains_item.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from persona_dsl.components.expectation import Expectation
+from hamcrest import assert_that, has_item
+
+
+class ContainsItem(Expectation):
+    """Проверяет, что список содержит указанный элемент."""
+
+    def __init__(self, expected_item: Any):
+        self.expected_item = expected_item
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        """Проверяет, что список содержит указанный элемент."""
+        actual_list = args[0]
+        assert_that(actual_list, has_item(self.expected_item))
+
+    def _get_step_description(self, persona: Any) -> str:
+        return f"содержит элемент '{self.expected_item}'"

persona_dsl/expectations/generic/contains_the_text.py

@@ -0,0 +1,15 @@
+from typing import Any
+from persona_dsl.components.expectation import Expectation
+from hamcrest import assert_that, contains_string
+
+
+class ContainsTheText(Expectation):
+    def __init__(self, expected_text: str):
+        self.expected_text = expected_text
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        actual_text = args[0]
+        assert_that(actual_text, contains_string(self.expected_text))
+
+    def _get_step_description(self, persona: Any) -> str:
+        return f"содержит текст '{self.expected_text}'"

persona_dsl/expectations/generic/has_entries.py

@@ -0,0 +1,21 @@
+from typing import Dict, Any
+from persona_dsl.components.expectation import Expectation
+from hamcrest import assert_that, has_entries
+
+
+class HasEntries(Expectation):
+    """
+    Проверяет, что фактический словарь содержит все ключи и значения
+    из ожидаемого словаря.
+    """
+
+    def __init__(self, expected_data: Dict[str, Any]):
+        self.expected_data = expected_data
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        """Проверяет, что actual_data содержит все записи из expected_data."""
+        actual_data = args[0]
+        assert_that(actual_data, has_entries(self.expected_data))
+
+    def _get_step_description(self, persona: Any) -> str:
+        return f"содержит записи {self.expected_data}"

persona_dsl/expectations/generic/is_equal.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+from persona_dsl.components.expectation import Expectation
+from hamcrest import assert_that, equal_to
+
+
+class IsEqualTo(Expectation):
+    """Проверяет, что фактическое значение равно ожидаемому."""
+
+    def __init__(self, expected: Any):
+        """Инициализирует ожидание.
+
+        Args:
+            expected: Ожидаемое значение.
+        """
+        self.expected = expected
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        """Проверяет, что фактическое значение равно ожидаемому."""
+        actual = args[0]
+        assert_that(actual, equal_to(self.expected))
+
+    def _get_step_description(self, persona: Any) -> str:
+        return f"равно '{self.expected}'"

persona_dsl/expectations/generic/is_greater_than.py

@@ -0,0 +1,18 @@
+from typing import Any
+from persona_dsl.components.expectation import Expectation
+from hamcrest import assert_that, greater_than
+
+
+class IsGreaterThan(Expectation):
+    """Проверяет, что одно число больше другого."""
+
+    def __init__(self, value: int | float):
+        self.value = value
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        """Проверяет, что одно число больше другого."""
+        actual_value = args[0]
+        assert_that(actual_value, greater_than(self.value))
+
+    def _get_step_description(self, persona: Any) -> str:
+        return f"больше чем {self.value}"

persona_dsl/expectations/generic/path_equal.py

@@ -0,0 +1,27 @@
+from typing import Any
+
+from hamcrest import assert_that, equal_to
+
+from persona_dsl.components.expectation import Expectation
+from persona_dsl.utils.path import extract_by_path
+
+
+class PathEqual(Expectation):
+    """
+    Проверяет, что значение по указанному пути (dot/bracket нотация) внутри объекта равно ожидаемому.
+
+    Пример:
+        PathEqual("a.b[0].c", 42).check({"a": {"b": [{"c": 42}]}})  # проходит
+    """
+
+    def __init__(self, path: str, expected: Any):
+        self.path = path
+        self.expected = expected
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        actual = args[0]
+        value = extract_by_path(actual, self.path)
+        assert_that(value, equal_to(self.expected))
+
+    def _get_step_description(self, persona: Any) -> str:
+        return f"значение по пути '{self.path}' равно '{self.expected}'"

persona_dsl/expectations/web/__init__.py

@@ -0,0 +1,5 @@
+from .is_displayed import IsDisplayed
+from .matches_screenshot import MatchesScreenshot
+from .matches_aria_snapshot import MatchesAriaSnapshot
+
+__all__ = ["IsDisplayed", "MatchesScreenshot", "MatchesAriaSnapshot"]

persona_dsl/expectations/web/is_displayed.py

@@ -0,0 +1,13 @@
+from typing import Any
+from persona_dsl.components.expectation import Expectation
+
+
+class IsDisplayed(Expectation):
+    """Проверяет, что значение (результат факта) равно True."""
+
+    def _perform(self, persona: Any, *args: Any, **kwargs: Any) -> None:
+        actual_value = args[0]
+        assert actual_value is True, "Элемент не отображается, хотя ожидалось обратное."
+
+    def _get_step_description(self, persona: Any) -> str:
+        return "отображается на странице"