robotframework-events 0.1.0__py3-none-any.whl

robotframework_events/__init__.py

@@ -0,0 +1,30 @@
+"""Robot Framework execution events as JSON Lines.
+
+Usage::
+
+    robot --listener robotframework_events.Listener tests/
+    robot --listener robotframework_events.Listener:file=results/events.jsonl tests/
+
+Programs that run Robot Framework in the same process (for example robotcode's
+debugger) can receive every event with :func:`add_callback`. Programs that read
+events files use :func:`read_events` and :class:`RunState`.
+"""
+
+from .convert import convert
+from .events import Event, from_dict, schema
+from .listener import Listener, add_callback, remove_callback
+from .reader import read_events
+from .state import RunState
+
+__all__ = [
+    "Event",
+    "Listener",
+    "RunState",
+    "add_callback",
+    "convert",
+    "from_dict",
+    "read_events",
+    "remove_callback",
+    "schema",
+]
+__version__ = "0.1.0"

robotframework_events/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

robotframework_events/cli.py

@@ -0,0 +1,176 @@
+"""The ``rfevents`` command: ``tail`` shows a run in the terminal, ``convert`` builds events from a result file."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import os
+import sys
+from collections.abc import Iterable
+from typing import TextIO
+
+from . import __version__
+from .convert import convert
+from .events import (
+    Event,
+    MessageLogged,
+    RunEnded,
+    StepStarted,
+    SuiteEnded,
+    SuiteStarted,
+    TestEnded,
+    TestStarted,
+)
+from .listener import LEVELS
+from .reader import read_events
+from .state import RunState, step_label
+
+COLORS = {"PASS": "32", "FAIL": "31", "SKIP": "33", "NOT RUN": "90", "WARN": "33", "ERROR": "31"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="rfevents", description="Robot Framework execution events.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    tail = commands.add_parser("tail", help="show a run from its events file, readable")
+    tail.add_argument("file", help="events file (.jsonl or .jsonl.gz)")
+    tail.add_argument("-f", "--follow", action="store_true", help="wait for new events until the run ends")
+    tail.add_argument(
+        "--steps",
+        type=int,
+        default=1,
+        metavar="DEPTH",
+        help="show steps this many levels below each test, 0 for none (default 1)",
+    )
+    tail.add_argument(
+        "--level",
+        default="WARN",
+        type=str.upper,
+        choices=list(LEVELS),
+        help="show log messages from this level (default WARN)",
+    )
+    tail.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+
+    conv = commands.add_parser("convert", help="build events from output.xml or output.json")
+    conv.add_argument("output", help="output.xml or output.json")
+    conv.add_argument("-o", "--outfile", help="events file to write (default: standard output)")
+
+    args = parser.parse_args(argv)
+    if isinstance(sys.stdout, io.TextIOWrapper):
+        sys.stdout.reconfigure(errors="replace")
+    try:
+        if args.command == "tail":
+            color = args.color == "always" or (
+                args.color == "auto" and sys.stdout.isatty() and "NO_COLOR" not in os.environ
+            )
+            Tail(sys.stdout, args.steps, args.level, color).show(read_events(args.file, follow=args.follow))
+        else:
+            write_converted(args.output, args.outfile)
+    except KeyboardInterrupt:
+        return 130
+    except OutputClosed:
+        # keep Python from failing again when it flushes stdout at exit
+        sys.stdout = open(os.devnull, "w")  # noqa: SIM115
+        return 0
+    except (OSError, ValueError) as e:
+        print(f"rfevents: {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def write_converted(output: str, outfile: str | None) -> None:
+    encode = json.JSONEncoder(ensure_ascii=False, separators=(",", ":")).encode
+    lines = (encode(event) + "\n" for event in convert(output))
+    if outfile is None:
+        sys.stdout.writelines(lines)
+        return
+    with open(outfile, "w", encoding="utf-8") as file:
+        file.writelines(lines)
+
+
+class OutputClosed(Exception):
+    pass
+
+
+class Tail:
+    """Prints suites, tests, top-level steps, failures and warnings as they happen."""
+
+    def __init__(self, out: TextIO, steps: int = 1, level: str = "WARN", color: bool = False) -> None:
+        self.out = out
+        self.steps = steps
+        self.level = LEVELS[level]
+        self.color = color
+        self.state = RunState()
+
+    def show(self, events: Iterable[Event]) -> None:
+        for event in events:
+            self.state.apply(event)
+            self.print_event(event)
+
+    def print_event(self, event: Event) -> None:
+        if isinstance(event, SuiteStarted):
+            self.line(self.indent(event.id), event.longname if event.parent is None else event.name)
+        elif isinstance(event, TestStarted):
+            self.line(self.indent(event.id), event.name)
+        elif isinstance(event, StepStarted):
+            depth = self.step_depth(event.id)
+            if depth <= self.steps:
+                node = self.state.nodes[event.id]
+                kind = "" if event.kind == "KEYWORD" else ("ITER" if event.kind == "ITERATION" else event.kind)
+                parts = [kind, step_label(node), *(event.args or [])]
+                self.line(self.indent(event.id), "    ".join(p for p in parts if p))
+        elif isinstance(event, TestEnded):
+            node = self.state.nodes[event.id]
+            self.line(
+                self.indent(event.id), self.paint(node.status, node.status), node.name, f"({event.elapsed:.2f} s)"
+            )
+            if node.message:
+                self.line(self.indent(event.id) + "  ", node.message)
+        elif isinstance(event, SuiteEnded):
+            node = self.state.nodes[event.id]
+            if node.parent is not None:
+                return
+            s = event.stats
+            self.line(
+                "",
+                self.paint(node.status, node.status),
+                getattr(node.started, "longname", node.name),
+                f"{s['total']} tests, {s['passed']} passed, {s['failed']} failed, {s['skipped']} skipped",
+            )
+        elif isinstance(event, MessageLogged):
+            if LEVELS.get(event.level, 2) >= self.level and event.parent in self.state.nodes:
+                self.line(
+                    self.indent(self.shown(event.parent)) + "  ",
+                    self.paint(event.level, f"[{event.level}]"),
+                    event.text or "",
+                )
+        elif isinstance(event, RunEnded):
+            self.out.flush()
+
+    def indent(self, node_id: str | None) -> str:
+        return "  " * (len(self.state.path(node_id or "")) - 1)
+
+    def shown(self, node_id: str | None) -> str | None:
+        """The node, or its nearest ancestor that is printed."""
+        for node in reversed(self.state.path(node_id or "")):
+            if node.kind in ("SUITE", "TEST") or self.step_depth(node.id) <= self.steps:
+                return node.id
+        return node_id
+
+    def step_depth(self, node_id: str) -> int:
+        """1 for steps directly in a test or suite, 2 for their children, ..."""
+        return sum(1 for node in self.state.path(node_id) if node.kind not in ("SUITE", "TEST"))
+
+    def paint(self, status: str, text: str) -> str:
+        code = COLORS.get(status)
+        return f"\033[{code}m{text}\033[0m" if self.color and code else text
+
+    def line(self, indent: str, *parts: str) -> None:
+        self.out.write(indent + "  ".join(p for p in parts if p) + "\n")
+        self.out.flush()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

robotframework_events/convert.py

@@ -0,0 +1,172 @@
+"""Events built from an existing ``output.xml`` or ``output.json``.
+
+Gives events for runs that were recorded without the listener, so they can be replayed.
+What the result file does not store is left out: steps have no ``source`` and ``lineno``,
+``run.started`` has no ``pid`` and ``cwd``, and children of ``robot:flatten`` keywords are
+missing, as in ``log.html``. Statuses are final, so there are no ``status.changed`` events.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from collections.abc import Iterator
+from datetime import datetime
+from typing import Any
+
+from robot.api import ExecutionResult
+from robot.result import TestCase, TestSuite
+
+from .events import FORMAT_VERSION
+from .listener import ROOT_TYPES, _stats, step_fields
+
+GENERATOR = re.compile(r"Robot (\S+) \(\w+ (\S+)")
+
+
+def convert(path: str | os.PathLike[str], *, run: str | None = None, max_text: int = 4096) -> Iterator[dict[str, Any]]:
+    """Yields the events of a result file as dicts, in the order a live run emits them."""
+    result = ExecutionResult(str(path))
+    return _Converter(max_text).events(result, str(path), run or str(uuid.uuid4()))
+
+
+def _time(value: datetime | None) -> float | None:
+    return round(value.timestamp(), 3) if value else None
+
+
+class _Counter:
+    __slots__ = ("children", "id")
+
+    def __init__(self, id: str) -> None:
+        self.id = id
+        self.children = 0
+
+
+class _Converter:
+    def __init__(self, max_text: int) -> None:
+        self.max_text = max_text
+        self.seq = 0
+        self.t = 0.0
+
+    def emit(self, type_: str, t: float | None, **fields: Any) -> dict[str, Any]:
+        self.seq += 1
+        # NOT RUN items have no times; keep time moving forward
+        self.t = max(self.t, t) if t is not None else self.t
+        event: dict[str, Any] = {"v": FORMAT_VERSION, "seq": self.seq, "t": self.t, "type": type_}
+        event.update((k, v) for k, v in fields.items() if v is not None and v != "")
+        return event
+
+    def events(self, result: Any, path: str, run: str) -> Iterator[dict[str, Any]]:
+        suite = result.suite
+        match = GENERATOR.match(getattr(result, "generator", "") or "")
+        self.t = _time(suite.start_time) or 0.0
+        yield self.emit(
+            "run.started",
+            self.t,
+            run=run,
+            rf=match.group(1) if match else "unknown",
+            python=match.group(2) if match else None,
+        )
+        yield from self.suite(suite, "s1", None)
+        yield self.emit("resultfile.created", None, kind="OUTPUT", path=path)
+        yield self.emit("run.ended", None, status=suite.status, stats=_stats(suite))
+
+    def suite(self, suite: TestSuite, id: str, parent: str | None) -> Iterator[dict[str, Any]]:
+        yield self.emit(
+            "suite.started",
+            _time(suite.start_time),
+            id=id,
+            parent=parent,
+            name=suite.name,
+            longname=suite.full_name,
+            source=str(suite.source) if suite.source else None,
+            tests=suite.test_count,
+        )
+        counter = _Counter(id)
+        if suite.has_setup:
+            yield from self.step(suite.setup, counter, id)
+        for index, child in enumerate(suite.suites, 1):
+            yield from self.suite(child, f"{id}-s{index}", id)
+        for index, test in enumerate(suite.tests, 1):
+            yield from self.test(test, f"{id}-t{index}", id)
+        if suite.has_teardown:
+            yield from self.step(suite.teardown, counter, id)
+        yield self.emit(
+            "suite.ended",
+            _time(suite.end_time),
+            id=id,
+            status=suite.status,
+            message=suite.message,
+            elapsed=round(suite.elapsed_time.total_seconds(), 3),
+            stats=_stats(suite),
+        )
+
+    def test(self, test: TestCase, id: str, parent: str) -> Iterator[dict[str, Any]]:
+        yield self.emit(
+            "test.started",
+            _time(test.start_time),
+            id=id,
+            parent=parent,
+            name=test.name,
+            longname=test.full_name,
+            source=str(test.source) if test.source else None,
+            lineno=test.lineno,
+            tags=list(test.tags) or None,
+        )
+        counter = _Counter(id)
+        if test.has_setup:
+            yield from self.step(test.setup, counter, id)
+        yield from self.body(test.body, counter, id)
+        if test.has_teardown:
+            yield from self.step(test.teardown, counter, id)
+        yield self.emit(
+            "test.ended",
+            _time(test.end_time),
+            id=id,
+            status=test.status,
+            message=test.message,
+            elapsed=round(test.elapsed_time.total_seconds(), 3),
+        )
+
+    def body(self, items: Any, counter: _Counter, parent: str) -> Iterator[dict[str, Any]]:
+        for item in items:
+            if item.type == "MESSAGE":
+                text = item.message or ""
+                truncated = len(text) > self.max_text
+                yield self.emit(
+                    "message.logged",
+                    _time(item.timestamp),
+                    parent=parent,
+                    level=item.level,
+                    text=text[: self.max_text] if truncated else text,
+                    truncated=True if truncated else None,
+                    html=True if item.html else None,
+                )
+            elif item.type in ROOT_TYPES:
+                # IF/TRY branches are numbered as children of the root's parent
+                yield from self.body(item.body, counter, parent)
+            else:
+                yield from self.step(item, counter, parent)
+
+    def step(self, item: Any, counter: _Counter, parent: str) -> Iterator[dict[str, Any]]:
+        counter.children += 1
+        id = f"{counter.id}-k{counter.children}"
+        kind = item.type
+        yield self.emit(
+            "step.started", _time(item.start_time), id=id, parent=parent, kind=kind, **step_fields(kind, item)
+        )
+        own = _Counter(id)
+        if getattr(item, "has_setup", False):
+            yield from self.step(item.setup, own, id)
+        if hasattr(item, "body"):
+            yield from self.body(item.body, own, id)
+        if getattr(item, "has_teardown", False):
+            yield from self.step(item.teardown, own, id)
+        yield self.emit(
+            "step.ended",
+            _time(item.end_time),
+            id=id,
+            status=item.status,
+            message=item.message,
+            elapsed=round(item.elapsed_time.total_seconds(), 4),
+        )

robotframework_events/events-v1.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/timdegroot1996/robotframework-events/blob/main/src/robotframework_events/events-v1.schema.json",
+  "title": "Robot Framework execution event, format v1",
+  "description": "One line of an events JSONL file. Fields with no value are left out. Readers ignore unknown fields and unknown event types.",
+  "type": "object",
+  "required": ["v", "seq", "t", "type"],
+  "properties": {
+    "v": { "description": "Format version.", "const": 1 },
+    "seq": { "description": "1, 2, 3, ... per stream, without gaps.", "type": "integer", "minimum": 1 },
+    "t": { "description": "Unix time in seconds.", "type": "number" },
+    "type": { "type": "string" }
+  },
+  "allOf": [
+    { "if": { "properties": { "type": { "const": "run.started" } } }, "then": { "$ref": "#/$defs/run.started" } },
+    { "if": { "properties": { "type": { "const": "run.ended" } } }, "then": { "$ref": "#/$defs/run.ended" } },
+    { "if": { "properties": { "type": { "const": "suite.started" } } }, "then": { "$ref": "#/$defs/suite.started" } },
+    { "if": { "properties": { "type": { "const": "suite.ended" } } }, "then": { "$ref": "#/$defs/suite.ended" } },
+    { "if": { "properties": { "type": { "const": "test.started" } } }, "then": { "$ref": "#/$defs/test.started" } },
+    { "if": { "properties": { "type": { "const": "test.ended" } } }, "then": { "$ref": "#/$defs/test.ended" } },
+    { "if": { "properties": { "type": { "const": "step.started" } } }, "then": { "$ref": "#/$defs/step.started" } },
+    { "if": { "properties": { "type": { "const": "step.ended" } } }, "then": { "$ref": "#/$defs/step.ended" } },
+    { "if": { "properties": { "type": { "const": "message.logged" } } }, "then": { "$ref": "#/$defs/message.logged" } },
+    { "if": { "properties": { "type": { "const": "status.changed" } } }, "then": { "$ref": "#/$defs/status.changed" } },
+    { "if": { "properties": { "type": { "const": "resultfile.created" } } }, "then": { "$ref": "#/$defs/resultfile.created" } }
+  ],
+  "$defs": {
+    "id": {
+      "description": "Robot Framework's item id, as in output.xml and log.html#<id>.",
+      "type": "string",
+      "pattern": "^s\\d+(-s\\d+)*(-t\\d+)?(-k\\d+)*$"
+    },
+    "status": { "enum": ["PASS", "FAIL", "SKIP", "NOT RUN", "NOT SET"] },
+    "stats": {
+      "type": "object",
+      "required": ["total", "passed", "failed", "skipped"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "skipped": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "strings": { "type": "array", "items": { "type": "string" } },
+
+    "run.started": {
+      "description": "First event of a stream. 'run' identifies the run; it is not repeated in later events. 'python', 'pid' and 'cwd' are missing in events converted from a result file.",
+      "required": ["run", "rf"],
+      "properties": {
+        "run": { "type": "string", "format": "uuid" },
+        "rf": { "description": "Robot Framework version.", "type": "string" },
+        "python": { "description": "Python version.", "type": "string" },
+        "pid": { "type": "integer" },
+        "cwd": { "type": "string" }
+      }
+    },
+    "run.ended": {
+      "description": "Last event of a stream.",
+      "required": ["status", "stats"],
+      "properties": {
+        "status": { "$ref": "#/$defs/status" },
+        "stats": { "$ref": "#/$defs/stats" }
+      }
+    },
+    "suite.started": {
+      "required": ["id", "name", "longname", "tests"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "parent": { "description": "Left out for the top-level suite.", "$ref": "#/$defs/id" },
+        "name": { "type": "string" },
+        "longname": { "type": "string" },
+        "source": { "type": "string" },
+        "tests": { "description": "Number of tests in the suite and its child suites.", "type": "integer", "minimum": 0 }
+      }
+    },
+    "suite.ended": {
+      "required": ["id", "status", "elapsed", "stats"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "status": { "$ref": "#/$defs/status" },
+        "message": { "type": "string" },
+        "elapsed": { "description": "Seconds.", "type": "number", "minimum": 0 },
+        "stats": { "$ref": "#/$defs/stats" }
+      }
+    },
+    "test.started": {
+      "required": ["id", "parent", "name", "longname"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "parent": { "$ref": "#/$defs/id" },
+        "name": { "type": "string" },
+        "longname": { "type": "string" },
+        "source": { "type": "string" },
+        "lineno": { "type": "integer" },
+        "tags": { "$ref": "#/$defs/strings" }
+      }
+    },
+    "test.ended": {
+      "required": ["id", "status", "elapsed"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "status": { "$ref": "#/$defs/status" },
+        "message": { "type": "string" },
+        "elapsed": { "description": "Seconds.", "type": "number", "minimum": 0 }
+      }
+    },
+    "step.started": {
+      "description": "A keyword, setup, teardown or control structure. IF/ELSE and TRY/EXCEPT roots are not emitted: their branches are children of the root's parent.",
+      "required": ["id", "kind"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "parent": { "description": "Nearest emitted ancestor.", "$ref": "#/$defs/id" },
+        "kind": {
+          "enum": ["KEYWORD", "SETUP", "TEARDOWN", "FOR", "ITERATION", "IF", "ELSE IF", "ELSE", "TRY", "EXCEPT", "FINALLY", "WHILE", "GROUP", "VAR", "RETURN", "BREAK", "CONTINUE", "ERROR"]
+        },
+        "source": { "description": "Left out when equal to the parent's source.", "type": "string" },
+        "lineno": { "type": "integer" },
+        "name": { "description": "Keyword, GROUP or VAR name.", "type": "string" },
+        "owner": { "description": "Library or resource file of a keyword.", "type": "string" },
+        "args": { "description": "Keyword arguments as written, truncated.", "$ref": "#/$defs/strings" },
+        "assign": {
+          "description": "Variables of a keyword or FOR (list), values of an ITERATION ({variable: value}), variable of an EXCEPT (string).",
+          "anyOf": [
+            { "$ref": "#/$defs/strings" },
+            { "type": "object", "additionalProperties": { "type": "string" } },
+            { "type": "string" }
+          ]
+        },
+        "flatten": { "description": "Keyword tagged robot:flatten: its children are emitted, but are not in output.xml.", "const": true },
+        "flavor": { "description": "FOR flavor, for example 'IN RANGE'.", "type": "string" },
+        "values": { "description": "FOR values, VAR values, RETURN values or ERROR values.", "$ref": "#/$defs/strings" },
+        "condition": { "description": "IF, ELSE IF or WHILE condition.", "type": "string" },
+        "limit": { "description": "WHILE limit.", "type": "string" },
+        "patterns": { "description": "EXCEPT patterns.", "$ref": "#/$defs/strings" },
+        "scope": { "description": "VAR scope.", "type": "string" }
+      }
+    },
+    "step.ended": {
+      "required": ["id", "status", "elapsed"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "status": { "$ref": "#/$defs/status" },
+        "message": { "type": "string" },
+        "elapsed": { "description": "Seconds.", "type": "number", "minimum": 0 }
+      }
+    },
+    "message.logged": {
+      "required": ["level"],
+      "properties": {
+        "parent": { "description": "The suite, test or step that logged the message.", "$ref": "#/$defs/id" },
+        "level": { "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FAIL", "SKIP"] },
+        "text": { "description": "Left out when empty; cut to max_text characters.", "type": "string" },
+        "truncated": { "const": true },
+        "html": { "const": true }
+      }
+    },
+    "status.changed": {
+      "description": "A failing or skipping suite teardown changed the status of a suite or test that already ended. Readers apply the new status.",
+      "required": ["id", "item", "status"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "item": { "enum": ["suite", "test"] },
+        "status": { "$ref": "#/$defs/status" },
+        "message": { "type": "string" }
+      }
+    },
+    "resultfile.created": {
+      "required": ["kind", "path"],
+      "properties": {
+        "kind": { "enum": ["OUTPUT", "LOG", "REPORT", "XUNIT", "DEBUG"] },
+        "path": { "type": "string" }
+      }
+    }
+  }
+}