vedro-step-tracer 0.1.0a4__tar.gz

vedro_step_tracer-0.1.0a4/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: vedro-step-tracer
+Version: 0.1.0a4
+Summary: Vedro plugin that traces function calls in e2e steps and renders call-tree reports
+Requires-Python: >=3.9
+Requires-Dist: vedro<2,>=1.10

vedro_step_tracer-0.1.0a4/README.md

@@ -0,0 +1,92 @@
+# VedroStepTracer
+
+Плагин для [vedro](https://vedro.io/), который автоматически трейсит вызовы функций во время выполнения тестов и генерирует детальные HTML-отчёты с деревом вызовов, переменными и трейсбеком ошибок.
+
+## Для чего нужен
+
+При падении e2e-теста сложно понять **что именно произошло** — какие функции вызывались, с какими аргументами, что вернули и где упало. Плагин перехватывает все вызовы из указанных директорий через `sys.settrace()`, строит иерархическое дерево и сохраняет его как интерактивный HTML-файл и/или выводит в stdout.
+
+- 🌳 **Видно весь путь до ошибки** — дерево вложенных вызовов `helpers/contexts/interfaces` с аргументами, локальными переменными и возвращаемыми значениями каждого шага, поэтому не нужно расставлять `print`/`breakpoint` и перезапускать тест, чтобы понять, где и с какими данными всё пошло не так
+- 📄 **Отчёт файлом рядом с артефактами сценария** — пишется в `.vedro/artifacts/...` (раскладка `vedro.plugins.artifacted`) при падении сценария, а при `--tr` — и для успешных; в результат сценария добавляется кликабельная ссылка `🔎 Trace report: …`. Блоки с деталями упавшей ветки развёрнуты сразу, остальное свёрнуто, чтобы не тонуть в шуме
+- ✂️ **Длинные значения сокращаются, но не теряются** — в HTML хвост скрыт под `…` и раскрывается по клику (и находится поиском по отчёту); в stdout и дереве тестов IDE обрезка жёсткая, полная версия остаётся в артефакте
+- 🔗 **Прямая ссылка на артефакты job'а GitLab CI** — не нужно вручную искать нужный запуск и скачивать файл, чтобы посмотреть трейс
+
+---
+
+## CLI-флаги
+
+| Флаг | Тип | По умолчанию | Описание |
+|------|-----|-------------|----------|
+| `--tr [LEVEL]` | `int` (0–3) | `1` (если указан без значения) | Включает интерактивный трейс в stdout. Уровни детализации: |
+| | | | `0` — только return из target_dirs |
+| | | | `1` — return + scope |
+| | | | `2` — scope + args/return всех уровней |
+| | | | `3` — всё (scope + args + locals + return) |
+| `--tr-no-color` | `flag` | `false` | Отключить ANSI-раскраску в выводе трейса |
+| `--tr-gitlab` | `flag` | auto | Добавить маркеры схлопываемых секций GitLab CI (автоопределяется по `CI_JOB_ID`) |
+
+### Примеры запуска
+
+```bash
+# Базовый трейс (return + scope)
+python -m vedro run --tr
+
+# Максимальная детализация
+python -m vedro run --tr 3
+
+# Без цветов (для логов)
+python -m vedro run --tr --tr-no-color
+```
+
+---
+
+## Параметры конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|-------------|----------|
+| `enabled` | `bool` | `True` | Включить/выключить плагин |
+| `target_dirs` | `list[str]` | `["helpers", "contexts", "interfaces"]` | Директории для трейсинга (относительно workdir) |
+| `exclude_paths` | `list[str]` | `[]` | Glob-паттерны файлов внутри `target_dirs`, вызовы из которых не попадают в дерево |
+| `exclude_functions` | `list[str]` | `[]` | Имена функций, которые не попадают в дерево |
+| `attach_artifacts` | `bool` | `True` | Сохранять отчёт в директорию артефактов сценария |
+| `save_to_dir` | `bool` | `False` | Дополнительно сохранять HTML в `output_dir` |
+| `output_dir` | `str` | `"logs/traces"` | Папка для HTML-отчётов (нужна только при `save_to_dir`) |
+| `print_to_stdout` | `bool` | `False` | Печатать полное дерево в stdout (иначе — только ссылка на отчёт) |
+| `max_str_len` | `int` | `1000` | Макс. длина строкового значения; применяется к каждой физической строке |
+| `max_line_len` | `int` | `1000` | Макс. длина одной физической строки в выводе нестандартного объекта (`__str__`/`repr`/rich) |
+| `collapse_passthrough` | `bool` | `True` | Схлопывать транзитные цепочки вызовов в одну хлебную крошку |
+| `job_id` | `str` | `""` | ID задачи CI (для ссылок на артефакты) |
+| `artifact_url_pattern` | `str` | `""` | Шаблон URL артефакта: `{job_id}`, `{path}` |
+| `workdir_subpath` | `str` | `""` | Подпуть рабочей директории в репозитории; задайте, если тесты запускаются из вложенной директории |
+
+---
+
+## Пример конфигурации
+
+```python
+# vedro.cfg.py
+import os
+import vedro
+
+from vedro_step_tracer import VedroStepTracer
+
+
+class Config(vedro.Config):
+
+    class Plugins(vedro.Config.Plugins):
+
+        class StepTracer(VedroStepTracer):
+            enabled = True
+            target_dirs = ['helpers', 'contexts', 'interfaces']
+            exclude_paths = ['interfaces/generated_client.py']
+
+            # Отчёт уходит файлом в артефакты сценария; stdout остаётся читаемым.
+            attach_artifacts = True
+            print_to_stdout = False
+
+            output_dir = 'logs/traces'
+            save_to_dir = bool(os.environ.get('CI_JOB_ID'))
+
+            job_id = os.environ.get('CI_JOB_ID')
+            artifact_url_pattern = 'https://gitlab.example.com/group/SomeProject/-/jobs/{job_id}/artifacts/file/{path}'
+```

vedro_step_tracer-0.1.0a4/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "vedro-step-tracer"
+version = "0.1.0a4"
+description = "Vedro plugin that traces function calls in e2e steps and renders call-tree reports"
+requires-python = ">=3.9"
+dependencies = [
+    "vedro>=1.10,<2",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["vedro_step_tracer*"]

vedro_step_tracer-0.1.0a4/setup.cfg

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

vedro_step_tracer-0.1.0a4/vedro_step_tracer/__init__.py

@@ -0,0 +1,19 @@
+"""
+Vedro plugin: автоматический трейсинг вызовов функций из helpers/, contexts/, interfaces/.
+
+Использует sys.settrace() для перехвата всех вызовов и возвратов из целевых
+директорий, собирает локальные переменные и возвращаемые значения, выводит
+иерархическое дерево по спецификации формата вывода шагов теста.
+
+Структура пакета:
+  * ``settings``  — изменяемые в рантайме настройки (лимит длины строк);
+  * ``tracing``   — модель дерева, sys.settrace-трейсер, пост-обработка;
+  * ``reporting`` — рендереры отчётов: ``terminal`` (stdout) и ``html``;
+  * ``gitlab``    — специфика GitLab CI: секции лога, ссылки на артефакты;
+  * ``plugin`` / ``config`` — интеграция с vedro.
+"""
+
+from .config import VedroStepTracer
+from .plugin import VedroStepTracerPlugin
+
+__all__ = ("VedroStepTracer", "VedroStepTracerPlugin",)

vedro_step_tracer-0.1.0a4/vedro_step_tracer/config.py

@@ -0,0 +1,99 @@
+"""Конфиг плагина (vedro PluginConfig)."""
+
+from typing import List, Optional
+
+from vedro.core import PluginConfig
+
+from .plugin import VedroStepTracerPlugin
+
+__all__ = ("VedroStepTracer",)
+
+
+class VedroStepTracer(PluginConfig):
+    plugin = VedroStepTracerPlugin
+
+    # Директории для отслеживания (относительно рабочей папки)
+    target_dirs: List[str] = ["helpers", "contexts", "interfaces"]
+
+    # Файлы внутри target_dirs, вызовы из которых не попадают в дерево
+    # (glob-паттерны, например "interfaces/api_client.py").
+    # Исключение означает «не создавать узел для вызовов из этого файла»:
+    # вложенные целевые вызовы сохраняются и прицепляются к ближайшему
+    # не исключённому предку.
+    exclude_paths: List[str] = []
+
+    # Имена функций, которые не попадают в дерево (по тому же правилу).
+    exclude_functions: List[str] = []
+
+    # Куда сохранять логи (используется только при save_to_dir = True)
+    output_dir: str = "logs/traces"
+
+    # Сохранять отчёт в директорию артефактов сценария (.vedro/artifacts,
+    # раскладка plugins.artifacted) — рядом с prompt-файлами и дампами.
+    # Файл пишется напрямую, артефактом vedro не прикрепляется: в результате
+    # сценария остаётся одна строка со ссылкой на отчёт.
+    attach_artifacts: bool = True
+
+    # Дополнительно сохранять HTML-отчёт в output_dir. Прежнее поведение;
+    # нужно там, где артефакты vedro не собираются (например, часть job'ов CI).
+    save_to_dir: bool = False
+
+    # Печатать полное дерево трейса в stdout. По умолчанию выключено: отчёт
+    # уходит в артефакт, а в stdout остаётся только ссылка на него. Полное
+    # дерево печатается при явном --tr.
+    print_to_stdout: bool = False
+
+    # Максимальная длина строкового значения перед сокращением.
+    # Применяется к каждой физической строке отдельно.
+    max_str_len: int = 1000
+
+    # Максимальная длина одной физической строки в выводе нестандартного
+    # объекта (рендер через __str__/repr/rich, например HTTP-трейс).
+    max_line_len: int = 1000
+
+    # Схлопывать транзитные цепочки вызовов: обёртка без собственных
+    # переменных, с одним вложенным вызовом и тем же возвращаемым объектом
+    # печаталась отдельным уровнем с тем же значением. Схлопывание без
+    # потерь — имена звеньев остаются в хлебной крошке
+    # "SomeProject ▸ load_data → DataClient ▸ fetch".
+    collapse_passthrough: bool = True
+
+    # ID job'а GitLab CI (например, job_id = os.environ.get('CI_JOB_ID')).
+    # По умолчанию не заполнен (локальный запуск). Его наличие используется
+    # для автоопределения запуска в GitLab CI, если флаг --tr-gitlab не
+    # передан явно.
+    job_id: str = ""
+
+    # Паттерн ссылки на артефакт GitLab CI с плейсхолдерами {job_id} и {path},
+    # например:
+    # "https://gitlab.example.com/group/SomeProject/-/jobs/{job_id}/artifacts/file/{path}"
+    # Используется для ссылки на Trace report только если job_id заполнен
+    # (запуск в GitLab CI); при локальном запуске ссылка формируется через локальный file:// путь.
+    artifact_url_pattern: str = ""
+
+    # Подпуть рабочей директории относительно корня репозитория,
+    # используемый при формировании хостовых и артефактных ссылок.
+    # Пустая строка означает, что рабочая директория — корень репозитория.
+    workdir_subpath: str = ""
+
+    # Удалять ранее сохранённые HTML-отчёты из output_dir перед прогоном.
+    # Иначе директория копится от запуска к запуску, и среди старых файлов
+    # трудно найти отчёт текущего прогона. Удаляются только *.html в самой
+    # output_dir, без рекурсии (см. filenames.cleanup_reports).
+    cleanup_before: bool = True
+
+    # Выводить дерево шагов service-сообщениями TeamCity — тогда шаги и
+    # вложенные вызовы видны деревом в тест-раннере PyCharm (встроенный
+    # репортёр vedro сообщает IDE только о сценариях).
+    # None — определять автоматически: выбран репортёр `-r pycharm` либо
+    # прогон идёт под IDE/TeamCity (см. teamcity_env_vars).
+    teamcity: Optional[bool] = None
+
+    # Переменные окружения, наличие которых означает запуск под
+    # PyCharm/TeamCity (используются при teamcity = None).
+    teamcity_env_vars: List[str] = ["PYCHARM_HOSTED", "TEAMCITY_VERSION", "PYCHARM_HELPERS_DIR"]
+
+    # Рисовать глифы дерева ("║  ┃  │  ├╴ ") перед строками в режиме TeamCity.
+    # False — печатать только заголовки и содержимое: внутри развёрнутого
+    # узла вложенность видна и без них, а отступы съедают ширину под значения.
+    teamcity_tree_prefix: bool = False

vedro_step_tracer-0.1.0a4/vedro_step_tracer/filenames.py

@@ -0,0 +1,71 @@
+"""Имена файлов отчётов: санитизация и очистка старых отчётов.
+
+Имя отчёта строится из subject сценария, а там встречается что угодно —
+двоеточия, слэши, кавычки. Такие символы ломают путь (`/`), несовместимы с
+Windows/сетевыми ФС (`:`, `?`, `*`, `"`, `<`, `>`, `|`) и требуют
+экранирования в ссылках, которые печатаются в терминал и в GitLab CI.
+Поэтому имя всегда приводится к безопасному виду.
+"""
+
+import os
+import re
+from typing import List
+
+__all__ = ("sanitize_filename", "cleanup_reports",)
+
+# Символы, недопустимые в именах файлов хотя бы на одной из целевых ФС,
+# плюс управляющие символы.
+_UNSAFE_RE = re.compile(r'[<>:"/\\|?*\x00-\x1f]+')
+# Пробельные последовательности схлопываются в одно подчёркивание: имена
+# отчётов часто попадают в ссылки, где пробелы приходится экранировать.
+_SPACE_RE = re.compile(r"\s+")
+_UNDERSCORE_RE = re.compile(r"_{2,}")
+
+_FALLBACK_NAME = "scenario"
+
+
+def sanitize_filename(name: str, max_length: int = 80) -> str:
+    """
+    Привести произвольную строку к безопасному имени файла (без расширения).
+
+    Небезопасные символы и пробелы заменяются подчёркиванием, повторы
+    схлопываются, точки и подчёркивания по краям убираются (имя, начинающееся
+    с точки, скрыто в файловых менеджерах). Пустой результат заменяется на
+    ``scenario``, чтобы отчёт не превратился в файл без имени.
+    """
+    cleaned = _UNSAFE_RE.sub("_", name)
+    cleaned = _SPACE_RE.sub("_", cleaned)
+    cleaned = _UNDERSCORE_RE.sub("_", cleaned)
+    cleaned = cleaned.strip("._ ")
+    if max_length > 0:
+        cleaned = cleaned[:max_length].strip("._ ")
+    return cleaned or _FALLBACK_NAME
+
+
+def cleanup_reports(output_dir: str, suffix: str = ".html") -> List[str]:
+    """
+    Удалить ранее сохранённые отчёты из директории вывода.
+
+    Удаляются только файлы с нужным расширением и только в самой директории
+    (без рекурсии): она может быть смонтирована рядом с другими артефактами,
+    и сносить её целиком небезопасно. Возвращает список удалённых путей;
+    ошибки доступа игнорируются — очистка не должна ронять прогон тестов.
+    """
+    removed: List[str] = []
+    try:
+        entries = os.listdir(output_dir)
+    except OSError:
+        return removed
+
+    for entry in entries:
+        if not entry.endswith(suffix):
+            continue
+        path = os.path.join(output_dir, entry)
+        if not os.path.isfile(path):
+            continue
+        try:
+            os.remove(path)
+        except OSError:
+            continue
+        removed.append(path)
+    return removed

vedro_step_tracer-0.1.0a4/vedro_step_tracer/gitlab.py

@@ -0,0 +1,124 @@
+"""GitLab CI-специфика: схлопываемые секции лога и ссылки на артефакты."""
+
+import os
+import time
+from typing import Optional
+from urllib.parse import quote
+
+__all__ = (
+    "SectionIdGenerator", "section_start", "section_end",
+    "to_host_path", "to_relative_path", "to_artifact_url", "make_terminal_link",
+)
+
+
+class SectionIdGenerator:
+    """Выдаёт уникальные идентификаторы секций в пределах одного отчёта."""
+
+    def __init__(self, prefix: str = "tr") -> None:
+        self._prefix = prefix
+        self._counter = 0
+
+    def next_id(self) -> str:
+        self._counter += 1
+        return f"{self._prefix}{self._counter}"
+
+
+def section_start(section_id: str, collapsed: bool = True) -> str:
+    """Маркер начала схлопываемой секции GitLab CI (пишется перед заголовком)."""
+    ts = int(time.time())
+    opts = "[collapsed=true]" if collapsed else ""
+    return f"\033[0Ksection_start:{ts}:{section_id}{opts}\r\033[0K"
+
+
+def section_end(section_id: str) -> str:
+    """Маркер конца схлопываемой секции GitLab CI."""
+    ts = int(time.time())
+    return f"\033[0Ksection_end:{ts}:{section_id}\r\033[0K\n"
+
+
+def to_host_path(filepath: str, project_root: str, workdir_subpath: str) -> str:
+    """
+    Преобразовать путь в рабочей директории в путь на хостовой машине.
+
+    Если задан `HOST_PROJECT_ROOT_DIRECTORY`, к корню проекта на хосте
+    добавляются подпуть рабочей директории и относительный путь к файлу.
+    """
+    host_root = os.environ.get("HOST_PROJECT_ROOT_DIRECTORY")
+    if not host_root:
+        return filepath
+    try:
+        rel_path = os.path.relpath(filepath, project_root)
+    except ValueError:
+        return filepath
+    if rel_path.startswith(".."):
+        return filepath
+    return os.path.join(host_root, workdir_subpath, rel_path)
+
+
+def to_relative_path(filepath: str, project_root: str) -> str:
+    """
+    Преобразовать путь внутри контейнера в путь относительно рабочей
+    директории (workdir) тестов — `project_root`.
+
+    Используется для блока с кодом из traceback: там удобнее видеть короткий
+    путь относительно workdir, а не абсолютный путь на хосте. Файлы вне
+    workdir (например, сторонние библиотеки) остаются нетронутыми
+    (абсолютный путь как есть).
+    """
+    try:
+        rel_path = os.path.relpath(filepath, project_root)
+    except ValueError:
+        return filepath
+    if rel_path.startswith(".."):
+        return filepath
+    return rel_path
+
+
+def to_artifact_url(filepath: str, project_root: str, job_id: str,
+                    url_pattern: str, workdir_subpath: str) -> Optional[str]:
+    """
+    Построить ссылку на прикреплённый артефакт GitLab CI (job_id известен —
+    сборка запущена именно в GitLab CI).
+
+    Паттерн задаётся переменной окружения PROJECT_ARTIFACT_PATTERN (см.
+    VedroStepTracer.artifact_url_pattern) с плейсхолдерами {job_id} и {path},
+    например:
+    "https://gitlab.example.com/group/SomeProject/-/jobs/{job_id}/artifacts/file/{path}"
+
+    Если job_id или паттерн не заданы (локальный запуск) — возвращает None,
+    и вызывающий код должен использовать локальную file:// ссылку.
+    """
+    if not job_id or not url_pattern:
+        return None
+    try:
+        rel_path = os.path.relpath(filepath, project_root)
+    except ValueError:
+        return None
+    if rel_path.startswith(".."):
+        return None
+    artifact_path = os.path.join(workdir_subpath, rel_path)
+    try:
+        return url_pattern.format(job_id=job_id, path=artifact_path)
+    except (KeyError, IndexError):
+        return None
+
+
+def make_terminal_link(path: str) -> str:
+    """
+    Вернуть путь как file:// URI, чтобы терминал сам распознал его как
+    кликабельную ссылку на файл.
+
+    Изначально использовалась OSC 8 hyperlink escape-последовательность
+    (ESC]8;;URI ESC\\ TEXT ESC]8;;ESC\\), но репортёр vedro выводит
+    extra_details через rich/logging-конвейер, который не пропускает
+    "сырые" управляющие последовательности — в терминале виден только
+    обычный текст без ссылки.
+
+    Более надёжный кроссплатформенный вариант — просто вывести сам file://
+    URI: большинство терминалов (Terminal.app и iTerm2 на macOS; GNOME
+    Terminal, Konsole, kitty, VS Code на Linux) автоматически подсвечивают
+    и делают кликабельными строки, распознанные как URL, без необходимости
+    в OSC 8.
+    """
+    abs_path = os.path.abspath(path)
+    return "file://" + quote(abs_path, safe="/:")