tgtest 0.1.0__py3-none-any.whl

tgtest/__init__.py

@@ -0,0 +1,26 @@
+"""tgtest - end-to-end testing platform for Telegram bots.
+
+Acts as a real Telegram *user* (via Telethon/MTProto) to talk to your bots and
+assert on their replies. Tests can be written either as declarative YAML
+scenarios or as Python/pytest functions using the same client helpers.
+"""
+from .config import Settings
+from .logger import configure_logger
+from .client import BotTester, ReplyMatchError
+from .scenario import Scenario, load_scenario, load_scenarios
+from .engine import run_scenario
+from .exceptions import TgTestError, StepError, ScenarioError
+
+__all__ = [
+    "Settings",
+    "configure_logger",
+    "BotTester",
+    "ReplyMatchError",
+    "Scenario",
+    "load_scenario",
+    "load_scenarios",
+    "run_scenario",
+    "TgTestError",
+    "StepError",
+    "ScenarioError",
+]

tgtest/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tgtest/cli.py

@@ -0,0 +1,104 @@
+"""Command-line runner: `python -m tgtest run scenarios/`.
+
+Discovers YAML scenarios, runs them against the configured bot, and prints a
+per-scenario PASS/FAIL summary. Exit code is non-zero if any scenario fails so
+it slots into CI.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+import time
+
+from .config import Settings
+from .logger import configure_logger
+from .client import BotTester
+from .scenario import load_scenarios, Scenario
+from .engine import run_scenario
+from .exceptions import StepError, ScenarioError
+
+GREEN, RED, DIM, BOLD, RESET = "\033[32m", "\033[31m", "\033[2m", "\033[1m", "\033[0m"
+
+
+def _c(text: str, color: str, use_color: bool) -> str:
+    return f"{color}{text}{RESET}" if use_color else text
+
+
+async def _run_all(scenarios: list[Scenario], config: Settings, use_color: bool) -> int:
+    logger = configure_logger(config)
+    passed = failed = 0
+    async with BotTester.create(config) as tester:
+        for sc in scenarios:
+            logger.info("Running scenario: %s", sc.name)
+            label = f"{sc.name}" + (f" [{sc.source}]" if sc.source else "")
+            start = time.monotonic()
+            try:
+                await run_scenario(tester, sc)
+            except StepError as exc:
+                failed += 1
+                dur = time.monotonic() - start
+                print(f"{_c('FAIL', RED, use_color)} {label} ({dur:.1f}s)")
+                loc = f"step {exc.step_index}"
+                if exc.step_desc:
+                    loc += f" — {exc.step_desc}"
+                print(_c(f"      {loc}", DIM, use_color))
+                for line in str(exc).splitlines():
+                    print(_c(f"      {line}", RED, use_color))
+                logger.error("FAIL %s at step %s: %s", sc.name, exc.step_index, exc)
+            except Exception as exc:
+                failed += 1
+                dur = time.monotonic() - start
+                print(f"{_c('ERROR', RED, use_color)} {label} ({dur:.1f}s)")
+                print(_c(f"      {type(exc).__name__}: {exc}", RED, use_color))
+                logger.exception("ERROR %s: %s", sc.name, exc)
+            else:
+                passed += 1
+                dur = time.monotonic() - start
+                print(f"{_c('PASS', GREEN, use_color)} {label} ({dur:.1f}s)")
+                logger.info("PASS %s (%.1fs)", sc.name, dur)
+
+    total = passed + failed
+    summary = f"\n{passed}/{total} passed"
+    print(_c(summary, GREEN if not failed else RED, use_color))
+    return 1 if failed else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="tgtest", description="Telegram bot E2E test runner"
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    run = sub.add_parser("run", help="run YAML scenarios")
+    run.add_argument("paths", nargs="+", help="scenario files, dirs, or globs")
+    run.add_argument("--bot", help="override bot for all scenarios")
+    run.add_argument("--env", help="path to a .env file")
+    run.add_argument("--no-color", action="store_true", help="disable colored output")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "run":
+        try:
+            config = Settings.load(env_file=args.env)
+        except RuntimeError as exc:
+            print(f"config error: {exc}", file=sys.stderr)
+            return 2
+        try:
+            scenarios = load_scenarios(args.paths)
+        except ScenarioError as exc:
+            print(f"scenario error: {exc}", file=sys.stderr)
+            return 2
+        if args.bot:
+            for sc in scenarios:
+                sc.bot = args.bot
+        if not scenarios:
+            print("no scenarios found", file=sys.stderr)
+            return 2
+        use_color = not args.no_color and sys.stdout.isatty()
+        return asyncio.run(_run_all(scenarios, config, use_color))
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tgtest/client.py

@@ -0,0 +1,227 @@
+"""BotTester - the user-facing client for talking to a bot and asserting replies.
+
+Wraps Telethon's `client.conversation()` context, which gives ordered,
+timeout-aware access to a bot's replies (including edits and button clicks).
+This is the single object both the YAML engine and Python/pytest tests drive.
+
+Typical Python usage:
+
+    async with BotTester.create(config) as tester:
+        async with tester.conversation("@my_bot") as chat:
+            await chat.send("/start")
+            await chat.expect(contains="Welcome", buttons=["Settings"])
+            await chat.click("Settings")
+            await chat.expect_edit(contains="Settings menu")
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+
+from telethon import TelegramClient
+from telethon.errors import TimeoutError as TelethonTimeout
+
+from .config import Settings
+from .matchers import Matcher, button_texts
+from .proxy import ProxyConfig, parse_proxy
+
+# Re-export so tests can `from tgtest import ReplyMatchError`.
+ReplyMatchError = AssertionError
+
+
+def _proxy_kwargs(proxy: ProxyConfig | None) -> dict:
+    """Translate a ProxyConfig into TelegramClient keyword arguments."""
+    if proxy is None:
+        return {}
+    if proxy.kind == "mtproxy":
+        # MTProxy needs a dedicated connection class; proxy is (host, port, secret).
+        from telethon import connection
+
+        return {
+            "connection": connection.ConnectionTcpMTProxyRandomizedIntermediate,
+            "proxy": (proxy.host, proxy.port, proxy.secret),
+        }
+    # python-socks tuple: (kind, host, port, rdns, username, password).
+    return {
+        "proxy": (
+            proxy.kind,
+            proxy.host,
+            proxy.port,
+            proxy.rdns,
+            proxy.username,
+            proxy.password,
+        )
+    }
+
+
+def build_client(config: Settings) -> TelegramClient:
+    """Create a (not-yet-connected) TelegramClient, applying any proxy config.
+
+    Shared by BotTester (test runs) and login.py (first-time auth) so both honor
+    TG_PROXY identically.
+    """
+    proxy = parse_proxy(config.proxy)
+    return TelegramClient(
+        config.session, config.api_id, config.api_hash, **_proxy_kwargs(proxy)
+    )
+
+
+class _Chat:
+    """A live conversation with one bot. Tracks the 'current' message so that
+    `click`/`expect_buttons`/`expect_edit` operate on the most recent reply."""
+
+    def __init__(self, conv, bot, default_timeout: float):
+        self._conv = conv
+        self._bot = bot
+        self._default_timeout = default_timeout
+        self.last = None  # most recent Message we received
+
+    # --- sending --------------------------------------------------------
+    async def send(self, text: str):
+        """Send a plain text message to the bot."""
+        return await self._conv.send_message(text)
+
+    async def command(self, cmd: str):
+        """Send a bot command, prepending '/' if the caller omitted it."""
+        if not cmd.startswith("/"):
+            cmd = "/" + cmd
+        return await self._conv.send_message(cmd)
+
+    # --- receiving ------------------------------------------------------
+    async def get_reply(self, timeout: float | None = None):
+        """Wait for and return the next reply message from the bot."""
+        try:
+            self.last = await self._conv.get_response(
+                timeout=timeout if timeout is not None else self._default_timeout
+            )
+        except (asyncio.TimeoutError, TelethonTimeout):
+            wait = timeout or self._default_timeout
+            raise AssertionError(
+                f"timed out after {wait}s waiting for a reply"
+            ) from None
+        return self.last
+
+    async def expect(self, timeout: float | None = None, **spec):
+        """Wait for the next reply and assert it matches the given clauses.
+
+        Clauses are the same keys as a YAML `expect` block (equals, contains,
+        regex, buttons, ...). Returns the matched Message.
+        """
+        message = await self.get_reply(timeout=timeout)
+        self._assert(Matcher.from_spec(spec), message)
+        return message
+
+    async def expect_edit(self, timeout: float | None = None, **spec):
+        """Wait for the *current* message to be edited and assert on it.
+
+        Bots commonly edit a message in place after an inline-button click.
+        """
+        if self.last is None:
+            raise AssertionError("expect_edit called before any reply was received")
+        try:
+            self.last = await self._conv.get_edit(
+                self.last,
+                timeout=timeout if timeout is not None else self._default_timeout,
+            )
+        except (asyncio.TimeoutError, TelethonTimeout):
+            wait = timeout or self._default_timeout
+            raise AssertionError(
+                f"timed out after {wait}s waiting for an edit"
+            ) from None
+        self._assert(Matcher.from_spec(spec), self.last)
+        return self.last
+
+    async def expect_no_reply(self, within: float = 2.0):
+        """Assert the bot sends nothing within `within` seconds."""
+        try:
+            msg = await self._conv.get_response(timeout=within)
+        except (asyncio.TimeoutError, TelethonTimeout):
+            return  # success: nothing arrived
+        raise AssertionError(
+            f"expected no reply within {within}s but got: {msg.text!r}"
+        )
+
+    def expect_buttons(self, *labels: str, exact: bool = False):
+        """Assert the current message exposes the given inline/reply buttons."""
+        if self.last is None:
+            raise AssertionError("expect_buttons called before any reply was received")
+        actual = button_texts(self.last)
+        if exact:
+            if actual != list(labels):
+                raise AssertionError(
+                    f"buttons differ\n  expected: {list(labels)}\n  actual:   {actual}"
+                )
+        else:
+            missing = [b for b in labels if b not in actual]
+            if missing:
+                raise AssertionError(
+                    f"missing buttons {missing}\n  actual buttons: {actual}"
+                )
+
+    # --- interacting ----------------------------------------------------
+    async def click(self, text: str | None = None, *, index: int | None = None,
+                     data: str | None = None):
+        """Click an inline button on the current message.
+
+        Identify the button by visible `text`, by 0-based `index`, or by raw
+        callback `data`.
+        """
+        if self.last is None:
+            raise AssertionError("click called before any reply was received")
+        if text is not None:
+            return await self.last.click(text=text)
+        if data is not None:
+            payload = data.encode() if isinstance(data, str) else data
+            return await self.last.click(data=payload)
+        if index is not None:
+            return await self.last.click(index)
+        raise ValueError("click requires one of: text, index, data")
+
+    # --- internal -------------------------------------------------------
+    def _assert(self, matcher: Matcher, message):
+        reason = matcher.check(message)
+        if reason is not None:
+            raise AssertionError(f"{matcher.describe()} failed:\n  {reason}")
+
+
+class BotTester:
+    """Owns the Telethon client connection. Hands out per-bot `_Chat` objects."""
+
+    def __init__(self, client: TelegramClient, config: Settings):
+        self._client = client
+        self._config = config
+
+    @classmethod
+    @asynccontextmanager
+    async def create(cls, config: Settings):
+        """Connect (using an existing session) and yield a ready BotTester.
+
+        The session must already be authorized; run `python login.py` once to
+        create it. We deliberately do NOT prompt for a login code here so that
+        test runs never block on interactive input.
+        """
+        client = build_client(config)
+        await client.connect()
+        if not await client.is_user_authorized():
+            await client.disconnect()
+            raise RuntimeError(
+                f"Session {config.session!r} is not authorized. "
+                "Run `python login.py` once to log in."
+            )
+        try:
+            yield cls(client, config)
+        finally:
+            await client.disconnect()
+
+    @asynccontextmanager
+    async def conversation(self, bot: str | None = None, timeout: float | None = None):
+        """Open a conversation with `bot` (defaults to TG_DEFAULT_BOT)."""
+        target = bot or self._config.default_bot
+        if not target:
+            raise ValueError("no bot specified and TG_DEFAULT_BOT is not set")
+        entity = await self._client.get_entity(target)
+        conv_timeout = timeout if timeout is not None else self._config.timeout
+        async with self._client.conversation(
+            entity, timeout=conv_timeout, total_timeout=None
+        ) as conv:
+            yield _Chat(conv, entity, conv_timeout)

tgtest/config.py

@@ -0,0 +1,50 @@
+"""Application settings, loaded from the environment via pydantic-settings.
+
+Mirrors the project template's `Settings(BaseSettings)` pattern. All tgtest
+variables share the ``TG_`` prefix (e.g. ``TG_API_ID`` -> ``api_id``), so both
+the CLI runner and the pytest plugin get identical, validated config.
+"""
+from __future__ import annotations
+
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """tgtest settings loaded from environment / ``.env`` (prefix ``TG_``)."""
+
+    # Telegram user-account credentials (api_id/api_hash from my.telegram.org).
+    api_id: int
+    api_hash: str
+    # Telethon session file; created once by `python login.py`.
+    session: str = "tgtest.session"
+    # Phone of the test user account, used only for first-time login.
+    phone: str | None = None
+    # Bot used when a scenario / test does not name one explicitly.
+    default_bot: str | None = None
+    # Optional proxy URL, e.g. socks5://user:pass@host:1080 or mtproxy://SECRET@host:443.
+    proxy: str | None = None
+    # Default per-step reply timeout, in seconds.
+    timeout: float = 15.0
+    # Logging.
+    app_name: str = "tgtest"
+    log_level: str = "INFO"
+
+    model_config = SettingsConfigDict(
+        env_prefix="TG_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @classmethod
+    def load(cls, env_file: str | None = None) -> "Settings":
+        """Load settings, raising a friendly error if credentials are missing."""
+        try:
+            return cls(_env_file=env_file) if env_file else cls()
+        except ValidationError as exc:
+            raise RuntimeError(
+                "Invalid tgtest config (see .env.example). "
+                "TG_API_ID and TG_API_HASH are required; get them from "
+                f"https://my.telegram.org.\n{exc}"
+            ) from exc

tgtest/engine.py

@@ -0,0 +1,75 @@
+"""Execute a parsed Scenario against a live BotTester conversation.
+
+The engine maps each YAML step to a call on the `_Chat` helper. All assertion
+failures and timeouts are wrapped in StepError with the offending step's index
+and description, so the runner can pinpoint failures.
+"""
+from __future__ import annotations
+
+import asyncio
+
+from .client import BotTester
+from .matchers import Matcher
+from .scenario import Scenario, Step
+from .exceptions import StepError
+
+
+async def _run_step(chat, step: Step):
+    action, value, opts = step.action, step.value, step.options
+    timeout = float(opts["timeout"]) if "timeout" in opts else None
+
+    if action == "send":
+        await chat.send(str(value))
+    elif action == "command":
+        await chat.command(str(value))
+    elif action == "sleep":
+        await asyncio.sleep(float(value))
+    elif action == "expect":
+        message = await chat.get_reply(timeout=timeout)
+        reason = Matcher.from_spec(value).check(message)
+        if reason:
+            raise AssertionError(reason)
+    elif action == "expect_edit":
+        await chat.expect_edit(timeout=timeout, **(_as_spec(value)))
+    elif action == "expect_no_reply":
+        within = float(value) if value is not None else float(opts.get("within", 2.0))
+        await chat.expect_no_reply(within=within)
+    elif action == "expect_buttons":
+        labels = value if isinstance(value, list) else [value]
+        chat.expect_buttons(*labels, exact=bool(opts.get("exact", False)))
+    elif action == "click":
+        await chat.click(
+            text=value if isinstance(value, str) else None,
+            index=opts.get("index"),
+            data=opts.get("data"),
+        )
+    else:  # pragma: no cover - parser guarantees valid actions
+        raise StepError(f"unknown action {action!r}", step_index=step.index)
+
+
+def _as_spec(value):
+    """expect_edit accepts the same shorthand as expect (string or dict)."""
+    if value is None:
+        return {}
+    if isinstance(value, str):
+        return {"equals": value}
+    return dict(value)
+
+
+async def run_scenario(tester: BotTester, scenario: Scenario):
+    """Run every step of a scenario. Raises StepError on the first failure."""
+    async with tester.conversation(scenario.bot, timeout=scenario.timeout) as chat:
+        for step in scenario.steps:
+            try:
+                await _run_step(chat, step)
+            except AssertionError as exc:
+                raise StepError(
+                    str(exc), step_index=step.index, step_desc=step.describe()
+                ) from exc
+            except StepError:
+                raise
+            except Exception as exc:  # surface unexpected errors with step context
+                raise StepError(
+                    f"{type(exc).__name__}: {exc}",
+                    step_index=step.index, step_desc=step.describe(),
+                ) from exc

tgtest/exceptions.py

@@ -0,0 +1,23 @@
+"""Exception hierarchy for tgtest."""
+
+
+class TgTestError(Exception):
+    """Base class for all tgtest errors."""
+
+
+class ScenarioError(TgTestError):
+    """Raised when a YAML scenario is malformed or cannot be parsed."""
+
+
+class StepError(TgTestError):
+    """Raised when a scenario step fails (assertion failed or timed out).
+
+    Carries the step index and a human-readable description so the runner can
+    report exactly which step in which scenario broke.
+    """
+
+    def __init__(self, message: str, *, step_index: int | None = None,
+                 step_desc: str | None = None):
+        self.step_index = step_index
+        self.step_desc = step_desc
+        super().__init__(message)

tgtest/logger.py

@@ -0,0 +1,41 @@
+"""Logging setup, modeled on the project template's rotating-file logger."""
+from __future__ import annotations
+
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from tgtest.config import Settings
+
+
+def configure_logger(settings: Settings) -> logging.Logger:
+    """Configure and return the application logger.
+
+    Writes rotating log files under ``logs/`` and, at DEBUG level, also echoes
+    to the console so test runs can be traced live.
+    """
+    log_dir = Path("logs")
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    logger = logging.getLogger(settings.app_name)
+    logger.setLevel(settings.log_level.upper())
+    logger.propagate = False
+
+    formatter = logging.Formatter(
+        "%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    file_handler = RotatingFileHandler(
+        log_dir / "tgtest.log",
+        maxBytes=5 * 1024 * 1024,
+        backupCount=3,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(formatter)
+    file_handler.setLevel(settings.log_level.upper())
+
+    if not logger.handlers:
+        logger.addHandler(file_handler)
+
+    return logger

tgtest/matchers.py

@@ -0,0 +1,125 @@
+"""Text and button matchers shared by the engine and the Python helper API.
+
+A matcher is built from a dict (the body of an `expect` step) and applied to a
+Telethon Message. It returns None on success or a human-readable failure
+reason string. Keeping failures as strings (rather than raising) lets the
+caller assemble a single rich StepError with full context.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# Keys in an expect block that describe the message *text*.
+_TEXT_KEYS = ("equals", "contains", "icontains", "regex", "iregex", "not_contains")
+
+
+def _message_text(message) -> str:
+    """Best-effort textual content of a message (text, or media caption)."""
+    return (getattr(message, "text", None) or getattr(message, "message", None) or "")
+
+
+def button_texts(message) -> list[str]:
+    """Flatten an inline/reply keyboard into a list of button label strings."""
+    labels: list[str] = []
+    buttons = getattr(message, "buttons", None)
+    if not buttons:
+        return labels
+    for row in buttons:
+        for btn in row:
+            text = getattr(btn, "text", None)
+            if text is not None:
+                labels.append(text)
+    return labels
+
+
+@dataclass
+class Matcher:
+    equals: str | None = None
+    contains: str | None = None
+    icontains: str | None = None
+    not_contains: str | None = None
+    regex: str | None = None
+    iregex: str | None = None
+    buttons: list[str] | None = None          # buttons that must all be present
+    buttons_exact: list[str] | None = None     # full keyboard must equal this set/order
+    has_buttons: bool | None = None            # assert presence/absence of any keyboard
+    _raw: dict = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_spec(cls, spec) -> "Matcher":
+        """Build a Matcher from a YAML `expect` value.
+
+        Accepts a plain string (shorthand for `equals`) or a dict of keys.
+        """
+        if spec is None:
+            return cls(_raw={})
+        if isinstance(spec, str):
+            return cls(equals=spec, _raw={"equals": spec})
+        if not isinstance(spec, dict):
+            raise ValueError(
+                f"expect must be a string or mapping, got {type(spec).__name__}"
+            )
+        known = {
+            "equals", "contains", "icontains", "not_contains", "regex", "iregex",
+            "buttons", "buttons_exact", "has_buttons",
+        }
+        unknown = set(spec) - known
+        if unknown:
+            raise ValueError(f"unknown expect keys: {', '.join(sorted(unknown))}")
+        return cls(
+            equals=spec.get("equals"),
+            contains=spec.get("contains"),
+            icontains=spec.get("icontains"),
+            not_contains=spec.get("not_contains"),
+            regex=spec.get("regex"),
+            iregex=spec.get("iregex"),
+            buttons=spec.get("buttons"),
+            buttons_exact=spec.get("buttons_exact"),
+            has_buttons=spec.get("has_buttons"),
+            _raw=dict(spec),
+        )
+
+    def check(self, message) -> str | None:
+        """Return None if the message satisfies every clause, else a reason."""
+        return self._check_text(_message_text(message)) or self._check_buttons(
+            button_texts(message)
+        )
+
+    def _check_text(self, text: str) -> str | None:
+        if self.equals is not None and text != self.equals:
+            return f"text != equals\n  expected: {self.equals!r}\n  actual:   {text!r}"
+        if self.contains is not None and self.contains not in text:
+            return f"text does not contain {self.contains!r}\n  actual: {text!r}"
+        if self.icontains is not None and self.icontains.lower() not in text.lower():
+            return f"text does not contain (ci) {self.icontains!r}\n  actual: {text!r}"
+        if self.not_contains is not None and self.not_contains in text:
+            return (
+                f"text unexpectedly contains {self.not_contains!r}\n  actual: {text!r}"
+            )
+        if self.regex is not None and not re.search(self.regex, text):
+            return f"text does not match regex {self.regex!r}\n  actual: {text!r}"
+        if self.iregex is not None and not re.search(self.iregex, text, re.IGNORECASE):
+            return f"text does not match regex (ci) {self.iregex!r}\n  actual: {text!r}"
+        return None
+
+    def _check_buttons(self, actual: list[str]) -> str | None:
+        if self.has_buttons is not None and bool(actual) != self.has_buttons:
+            return (
+                f"has_buttons expected {self.has_buttons}, "
+                f"got {bool(actual)} (buttons={actual})"
+            )
+        if self.buttons is not None:
+            missing = [b for b in self.buttons if b not in actual]
+            if missing:
+                return f"missing buttons {missing}\n  actual buttons: {actual}"
+        if self.buttons_exact is not None and actual != list(self.buttons_exact):
+            return (
+                f"buttons differ\n  expected: {list(self.buttons_exact)}\n"
+                f"  actual:   {actual}"
+            )
+        return None
+
+    def describe(self) -> str:
+        parts = [f"{k}={v!r}" for k, v in self._raw.items()]
+        return "expect(" + ", ".join(parts) + ")" if parts else "expect(any reply)"