clabgen 0.3.0__tar.gz

clabgen-0.3.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Tom Young <ripnet@gmail.com> and the clabgen contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

clabgen-0.3.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: clabgen
+Version: 0.3.0
+Summary: Python client and pytest helpers for clabgen, the protocol emulator and traffic generator for containerlab
+Author-email: Tom Young <ripnet@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ripnet/clabgen
+Classifier: Framework :: Pytest
+Classifier: Topic :: System :: Networking
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# clabgen (Python)
+
+Python client and pytest helpers for
+[clabgen](https://github.com/ripnet/clabgen), the protocol emulator and
+traffic generator for containerlab. Standard library only; Python 3.9+.
+
+```sh
+pip install clabgen
+```
+
+Installing from a checkout or from git builds the package: Ubuntu 22.04's
+own pip 22.0 builds it as `UNKNOWN`, so use a newer pip there (e.g. in a
+virtualenv after `pip install -U pip`).
+
+```python
+def test_failover(clabgen_lab):              # pytest --clabgen-lab b2b
+    with clabgen_lab.measure() as m:
+        clabgen_lab["gen2"].port_down("eth1")
+        time.sleep(2)
+        clabgen_lab["gen2"].port_up("eth1")
+    m.assert_pass()
+```
+
+See [docs/python.md](https://github.com/ripnet/clabgen/blob/main/docs/python.md).
+
+Tests: `pytest` here. The unit tests need nothing; the `agent` tests run
+the agent binary (`make build` at the top, or `CLABGEN_AGENT=path`) in a
+container, so they need docker, and are skipped without it.

clabgen-0.3.0/README.md

@@ -0,0 +1,28 @@
+# clabgen (Python)
+
+Python client and pytest helpers for
+[clabgen](https://github.com/ripnet/clabgen), the protocol emulator and
+traffic generator for containerlab. Standard library only; Python 3.9+.
+
+```sh
+pip install clabgen
+```
+
+Installing from a checkout or from git builds the package: Ubuntu 22.04's
+own pip 22.0 builds it as `UNKNOWN`, so use a newer pip there (e.g. in a
+virtualenv after `pip install -U pip`).
+
+```python
+def test_failover(clabgen_lab):              # pytest --clabgen-lab b2b
+    with clabgen_lab.measure() as m:
+        clabgen_lab["gen2"].port_down("eth1")
+        time.sleep(2)
+        clabgen_lab["gen2"].port_up("eth1")
+    m.assert_pass()
+```
+
+See [docs/python.md](https://github.com/ripnet/clabgen/blob/main/docs/python.md).
+
+Tests: `pytest` here. The unit tests need nothing; the `agent` tests run
+the agent binary (`make build` at the top, or `CLABGEN_AGENT=path`) in a
+container, so they need docker, and are skipped without it.

clabgen-0.3.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clabgen"
+dynamic = ["version"]
+description = "Python client and pytest helpers for clabgen, the protocol emulator and traffic generator for containerlab"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Tom Young", email = "ripnet@gmail.com" }]
+requires-python = ">=3.9"
+dependencies = []
+classifiers = [
+  "Framework :: Pytest",
+  "Topic :: System :: Networking",
+  "Programming Language :: Python :: 3",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/ripnet/clabgen"
+
+[project.entry-points.pytest11]
+clabgen = "clabgen.pytest_plugin"
+
+[tool.setuptools.dynamic]
+version = { attr = "clabgen.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["agent: needs docker and a clabgen-agent binary (CLABGEN_AGENT or ../bin/clabgen-agent)"]

clabgen-0.3.0/setup.cfg

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

clabgen-0.3.0/src/clabgen/__init__.py

@@ -0,0 +1,18 @@
+"""Python client for clabgen agents, with helpers for pytest.
+
+    from clabgen import Lab
+
+    lab = Lab.from_docker("b2b")
+    with lab.measure() as m:
+        lab["gen2"].port_down("eth1")
+        ...
+    m.assert_pass()
+"""
+
+from ._connect import ClabgenError
+from .agent import Agent, merge, pcap_data, wait_until
+from .lab import FlowResult, FlowsFailed, Lab, Measurement
+
+__version__ = "0.3.0"
+
+__all__ = ["Agent", "ClabgenError", "FlowResult", "FlowsFailed", "Lab", "Measurement", "merge", "pcap_data", "wait_until", "__version__"]

clabgen-0.3.0/src/clabgen/_connect.py

@@ -0,0 +1,136 @@
+"""Connect protocol (JSON encoding) over plain HTTP, standard library only.
+
+Unary calls are a POST of the request as JSON. Server-streaming calls send
+and receive enveloped messages: a flags byte, a 4-byte big-endian length,
+then the JSON; the end-of-stream message (flag 0x02) carries any error.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import struct
+import urllib.error
+import urllib.request
+from datetime import datetime
+from typing import Any, Iterator
+
+SERVICE = "clabgen.v1.AgentService"
+
+# Fields holding free-form JSON (google.protobuf.Struct): their keys are the
+# protocols' own and are left alone.
+_STRUCT_FIELDS = {"config", "status", "stats", "args", "result", "data", "spec"}
+# 64-bit integers, which protobuf's JSON mapping sends as strings.
+_INT64_FIELDS = {"rx_frames", "rx_bytes", "tx_frames", "tx_bytes", "tx_errors", "rx_unmatched", "age_ms", "rtt_us"}
+_TIME_FIELDS = {"start_time", "time"}
+
+
+class ClabgenError(Exception):
+    """An error from an agent: code is Connect's ("not_found", "invalid_argument", …)."""
+
+    def __init__(self, code: str, message: str, method: str = ""):
+        super().__init__(f"{method}: {code}: {message}" if method else f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.method = method
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"(?<=[a-z0-9])([A-Z])", r"_\1", name).lower()
+
+
+def _time(s: str) -> datetime:
+    # Python before 3.11 can't parse "Z" or more than 6 fraction digits.
+    s = s.replace("Z", "+00:00")
+    s = re.sub(r"(\.\d{6})\d+", r"\1", s)
+    return datetime.fromisoformat(s)
+
+
+def from_wire(v: Any) -> Any:
+    """Convert a decoded response: snake_case field names, ints and datetimes."""
+    if isinstance(v, list):
+        return [from_wire(x) for x in v]
+    if not isinstance(v, dict):
+        return v
+    out = {}
+    for k, x in v.items():
+        k = _snake(k)
+        if k in _STRUCT_FIELDS:
+            out[k] = x
+        elif k == "counters" and isinstance(x, dict):
+            # Port counters (a message) and device IP counters (a map): all uint64.
+            out[k] = {_snake(ck): int(cv) if isinstance(cv, str) and cv.isdigit() else cv for ck, cv in x.items()}
+        elif k in _INT64_FIELDS and isinstance(x, str):
+            out[k] = int(x)
+        elif k in _TIME_FIELDS and isinstance(x, str):
+            out[k] = _time(x)
+        else:
+            out[k] = from_wire(x)
+    return out
+
+
+def _error(method: str, body: bytes, status: int) -> ClabgenError:
+    try:
+        e = json.loads(body)
+        return ClabgenError(e.get("code", "unknown"), e.get("message", ""), method)
+    except ValueError:
+        return ClabgenError("unknown", f"HTTP {status}: {body[:200].decode(errors='replace')}", method)
+
+
+class Transport:
+    """Calls one agent's AgentService at base_url (http://host:8080, or a
+    clabgen-ui proxy path like http://host:8090/agents/clab-b2b-gen1)."""
+
+    def __init__(self, base_url: str, timeout: float = 10.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _url(self, method: str) -> str:
+        return f"{self.base_url}/{SERVICE}/{method}"
+
+    def call(self, method: str, request: dict | None = None, timeout: float | None = None) -> dict:
+        data = json.dumps(request or {}).encode()
+        req = urllib.request.Request(
+            self._url(method), data=data, method="POST",
+            headers={"Content-Type": "application/json", "Connect-Protocol-Version": "1"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as r:
+                return from_wire(json.loads(r.read() or b"{}"))
+        except urllib.error.HTTPError as e:
+            raise _error(method, e.read(), e.code) from None
+        except urllib.error.URLError as e:
+            raise ClabgenError("unavailable", str(e.reason), method) from None
+
+    def stream(self, method: str, request: dict | None = None, timeout: float | None = None) -> Iterator[dict]:
+        """Server-streaming call; timeout is per read (None: wait forever).
+        The call is made before this returns, so nothing sent after it is
+        missed; the messages come from the returned iterator."""
+        payload = json.dumps(request or {}).encode()
+        req = urllib.request.Request(
+            self._url(method), data=struct.pack(">BI", 0, len(payload)) + payload, method="POST",
+            headers={"Content-Type": "application/connect+json", "Connect-Protocol-Version": "1"},
+        )
+        try:
+            r = urllib.request.urlopen(req, timeout=timeout)
+        except urllib.error.HTTPError as e:
+            raise _error(method, e.read(), e.code) from None
+        except urllib.error.URLError as e:
+            raise ClabgenError("unavailable", str(e.reason), method) from None
+        return self._messages(method, r)
+
+    @staticmethod
+    def _messages(method: str, r: Any) -> Iterator[dict]:
+        with r:
+            while True:
+                head = r.read(5)
+                if len(head) < 5:
+                    return
+                flags, n = struct.unpack(">BI", head)
+                msg = json.loads(r.read(n) or b"{}")
+                if flags & 0x02:
+                    if "error" in msg:
+                        e = msg["error"]
+                        raise ClabgenError(e.get("code", "unknown"), e.get("message", ""), method)
+                    return
+                yield from_wire(msg)

clabgen-0.3.0/src/clabgen/agent.py

@@ -0,0 +1,321 @@
+"""One clabgen agent: everything clabgenctl and the web UI can do."""
+
+from __future__ import annotations
+
+import base64
+import copy
+import time
+from pathlib import Path
+from typing import Any, Callable, Iterable, Iterator
+
+from ._connect import ClabgenError, Transport
+
+
+def _base_url(address: str) -> str:
+    if "://" in address:
+        return address
+    host, sep, port = address.rpartition(":")
+    if not sep or not port.isdigit() or host.endswith(":"):  # no port, or a bare IPv6 address
+        host, port = address, "8080"
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    return f"http://{host}:{port}"
+
+
+def _vlan(v: Any) -> dict:
+    """A VLAN tag from 100, "100", "100.5" (PCP), "0x88a8:200" or a dict."""
+    if isinstance(v, dict):
+        return v
+    if isinstance(v, int):
+        return {"vid": v}
+    s, tag = str(v), {}
+    if ":" in s:
+        tpid, s = s.split(":", 1)
+        tag["tpid"] = int(tpid, 0)
+    if "." in s:
+        s, pcp = s.split(".", 1)
+        tag["pcp"] = int(pcp)
+    tag["vid"] = int(s)
+    return tag
+
+
+def pcap_data(capture: str | Path | bytes) -> str:
+    """A capture (a pcap or pcapng file's path, or its bytes) as the packet
+    type's pcap.data: add_protocol("r", "packet", "d1", pcap={"data": pcap_data("x.pcap")})."""
+    raw = capture if isinstance(capture, bytes) else Path(capture).read_bytes()
+    return base64.b64encode(raw).decode()
+
+
+def merge(dst: dict, src: dict) -> dict:
+    """Deep-merge src onto dst (nested dicts merged, everything else replaced)."""
+    for k, v in src.items():
+        if isinstance(v, dict) and isinstance(dst.get(k), dict):
+            merge(dst[k], v)
+        else:
+            dst[k] = v
+    return dst
+
+
+def wait_until(check: Callable[[], Any], timeout: float = 30, interval: float = 0.5, what: str = "condition") -> Any:
+    """Call check until it returns something truthy (returned), or raise
+    TimeoutError after timeout seconds. Errors from check propagate."""
+    end = time.monotonic() + timeout
+    while True:
+        v = check()
+        if v:
+            return v
+        if time.monotonic() >= end:
+            raise TimeoutError(f"timed out after {timeout:g}s waiting for {what}")
+        time.sleep(interval)
+
+
+class Agent:
+    """A clabgen agent's API.
+
+    address is host[:port] (port 8080 by default), e.g. "clab-b2b-gen1", or a
+    URL: "http://172.20.20.2:8080", or an agent behind clabgen-ui,
+    "http://host:8090/agents/clab-b2b-gen1".
+
+    Methods return the API's objects as dicts with snake_case keys. Protocol
+    configs and statuses are as each protocol type defines them (see
+    `types()` or `clabgenctl types TYPE`).
+    """
+
+    def __init__(self, address: str, timeout: float = 10.0, name: str | None = None):
+        self.url = _base_url(address)
+        self.name = name or address
+        self._t = Transport(self.url, timeout)
+        self._traffic: set[str] | None = None
+
+    def __repr__(self) -> str:
+        return f"Agent({self.name!r}, url={self.url!r})"
+
+    def call(self, method: str, request: dict | None = None, **kw: Any) -> dict:
+        """Any AgentService method by name, e.g. call("ListPorts")."""
+        return self._t.call(method, request, **kw)
+
+    # Agent and ports.
+
+    def info(self) -> dict:
+        """hostname, version and start_time."""
+        return self.call("GetInfo")
+
+    def ports(self) -> list[dict]:
+        return self.call("ListPorts").get("ports", [])
+
+    def port(self, name: str) -> dict:
+        for p in self.ports():
+            if p["name"] == name:
+                return p
+        raise ClabgenError("not_found", f"port {name}", "ListPorts")
+
+    def set_port(self, name: str, up: bool) -> dict:
+        return self.call("SetPortAdmin", {"name": name, "up": up})["port"]
+
+    def port_down(self, name: str) -> dict:
+        return self.set_port(name, False)
+
+    def port_up(self, name: str) -> dict:
+        return self.set_port(name, True)
+
+    # Devices.
+
+    def devices(self) -> list[dict]:
+        return self.call("ListDevices").get("devices", [])
+
+    def device(self, name: str) -> dict:
+        for d in self.devices():
+            if d["name"] == name:
+                return d
+        raise ClabgenError("not_found", f"device {name}", "ListDevices")
+
+    def add_device(self, name: str, port: str = "eth1", *, vlans: Iterable[Any] = (), mac: str = "",
+                   addresses: Iterable[str] = (), gateway4: str = "", gateway6: str = "") -> dict:
+        """Create a device. vlans are outermost first: 100, "100.5" (with PCP),
+        "0x88a8:200" or {"tpid":…, "vid":…, "pcp":…}. An empty mac is derived."""
+        d = {"name": name, "port": port, "mac": mac, "vlans": [_vlan(v) for v in vlans],
+             "addresses": list(addresses), "gateway4": gateway4, "gateway6": gateway6}
+        return self.call("CreateDevice", {"device": d})["device"]
+
+    def update_device(self, name: str, **changes: Any) -> dict:
+        """Change some of a device's fields (port, mac, vlans, addresses,
+        gateway4, gateway6); the rest stay as they are."""
+        d = self.device(name)
+        if "vlans" in changes:
+            changes["vlans"] = [_vlan(v) for v in changes["vlans"]]
+        d.update(changes)
+        for k in ("mac_derived", "group"):
+            d.pop(k, None)
+        return self.call("UpdateDevice", {"device": d})["device"]
+
+    def delete_device(self, name: str) -> None:
+        self.call("DeleteDevice", {"name": name})
+
+    def device_ip(self, name: str) -> dict:
+        """Effective addresses, gateways, neighbors and IP counters."""
+        return self.call("GetDeviceIP", {"name": name})
+
+    def resolve(self, device: str, ip: str) -> dict:
+        """ARP/ND for ip (or its gateway): next_hop, mac, cached, rtt_us."""
+        return self.call("ResolveNeighbor", {"device": device, "ip": ip})
+
+    def clear_neighbors(self, device: str) -> None:
+        self.call("ClearNeighbors", {"device": device})
+
+    # Protocols (including traffic flows).
+
+    def types(self) -> list[dict]:
+        """Protocol types with their config and action schemas (JSON strings)."""
+        return self.call("ListProtocolTypes").get("types", [])
+
+    def protocols(self, type: str | None = None, *, status: bool = True, brief: bool = False,
+                  group_members: bool = True) -> list[dict]:
+        r = self.call("ListProtocols", {"with_status": status, "brief": brief, "no_group_members": not group_members})
+        ps = r.get("protocols", [])
+        return [p for p in ps if p["type"] == type] if type else ps
+
+    def protocol(self, name: str) -> dict:
+        return self.call("GetProtocol", {"name": name})["protocol"]
+
+    def status(self, name: str) -> dict:
+        """A protocol's live status."""
+        return self.protocol(name).get("status", {})
+
+    def add_protocol(self, name: str, type: str, device: str = "", config: dict | None = None, **fields: Any) -> dict:
+        """Create a protocol instance; keyword arguments are config fields
+        (merged onto config), e.g. add_protocol("p", "icmp", "d1", destination="10.0.0.2", rate=50)."""
+        cfg = merge(copy.deepcopy(config or {}), fields)
+        return self.call("CreateProtocol", {"protocol": {"name": name, "type": type, "device": device, "config": cfg}})["protocol"]
+
+    def update_protocol(self, name: str, config: dict | None = None, *, replace: bool = False, **fields: Any) -> dict:
+        """Change a protocol's config and restart it. By default config and the
+        keyword fields are merged onto the current config (like clabgenctl
+        proto set); replace=True sends them as the whole config."""
+        changes = merge(copy.deepcopy(config or {}), fields)
+        cfg = changes if replace else merge(copy.deepcopy(self.protocol(name).get("config", {})), changes)
+        return self.call("UpdateProtocol", {"name": name, "config": cfg})["protocol"]
+
+    def preview(self, device: str, config: dict | None = None, *, type: str = "packet", index: int = 0,
+                pcap: str | Path | bytes | None = None, **fields: Any) -> dict:
+        """What a config would send from device, without creating anything
+        (the packet builder's preview): hex, summary, and layers with their
+        fields. index picks the packet (modifiers change fields per packet)
+        or the captured frame; pcap is a capture to replay (a path or bytes)."""
+        cfg = merge(copy.deepcopy(config or {}), fields)
+        if pcap is not None:
+            merge(cfg, {"pcap": {"data": pcap_data(pcap)}})
+        r = self.call("PreviewProtocol", {"type": type, "device": device, "config": cfg, "args": {"index": index}})
+        return r.get("result", {})
+
+    def delete_protocol(self, name: str) -> None:
+        self.call("DeleteProtocol", {"name": name})
+
+    def disable(self, name: str) -> dict:
+        """Stop a protocol but keep its config (state "disabled")."""
+        return self.call("SetProtocolDisabled", {"name": name, "disabled": True})["protocol"]
+
+    def enable(self, name: str) -> dict:
+        return self.call("SetProtocolDisabled", {"name": name, "disabled": False})["protocol"]
+
+    def run(self, name: str, action: str, args: dict | None = None, **fields: Any) -> dict:
+        """Run a protocol action, e.g. run("mep1", "loopback", target_mep_id=2, count=5)."""
+        a = merge(copy.deepcopy(args or {}), fields)
+        return self.call("RunProtocolAction", {"name": name, "action": action, "args": a}).get("result", {})
+
+    # Traffic flows.
+
+    def traffic_types(self) -> set[str]:
+        """Names of the protocol types that are traffic flows (icmp, udp, l2, …)."""
+        if self._traffic is None:
+            self._traffic = {t["name"] for t in self.types() if t.get("category") == "traffic"}
+        return self._traffic
+
+    def flows(self) -> list[dict]:
+        """Traffic flow instances with their statuses."""
+        traffic = self.traffic_types()
+        return [p for p in self.protocols(group_members=False) if p["type"] in traffic]
+
+    def start(self, *flows: str) -> None:
+        for f in flows:
+            self.run(f, "start")
+
+    def stop(self, *flows: str) -> None:
+        for f in flows:
+            self.run(f, "stop")
+
+    def received(self, device: str = "") -> list[dict]:
+        """Flows received by this agent's devices: one dict per flow and
+        device, with "device" and the one-way statistics (rx, lost, loss_pct,
+        reordered, duplicate, latency_*_us, outages, outage_max_ms, …)."""
+        flows = self.call("ListReceivedFlows", {"device": device}).get("flows", [])
+        return [{"device": f["device"], **f.get("stats", {})} for f in flows]
+
+    def clear_received(self, device: str = "", flow_id: str = "") -> None:
+        self.call("ClearReceivedFlows", {"device": device, "flow_id": flow_id})
+
+    # Device groups.
+
+    def groups(self) -> list[dict]:
+        return self.call("ListDeviceGroups").get("groups", [])
+
+    def group(self, name: str, members: bool = True) -> dict:
+        return self.call("GetDeviceGroup", {"name": name, "summary_only": not members})["group"]
+
+    def add_group(self, spec: dict | str) -> dict:
+        """Create a device group from a spec dict or its YAML."""
+        g = {"yaml": spec} if isinstance(spec, str) else {"name": spec["name"], "spec": spec}
+        return self.call("CreateDeviceGroup", {"group": g})["group"]
+
+    def update_group(self, spec: dict | str) -> dict:
+        g = {"yaml": spec} if isinstance(spec, str) else {"name": spec["name"], "spec": spec}
+        return self.call("UpdateDeviceGroup", {"group": g})["group"]
+
+    def delete_group(self, name: str) -> None:
+        self.call("DeleteDeviceGroup", {"name": name})
+
+    def run_group(self, group: str, action: str, args: dict | None = None, *, protocol: str = "",
+                  members: str = "", random: int = 0, **fields: Any) -> list[dict]:
+        """Run an action on a group protocol's members: members is "" (all) or
+        1-based indices and ranges like "1-10,15"; random picks that many of them."""
+        a = merge(copy.deepcopy(args or {}), fields)
+        r = self.call("RunGroupAction", {"group": group, "protocol": protocol, "action": action, "args": a,
+                                         "members": members, "random": random})
+        return r.get("results", [])
+
+    def set_group_disabled(self, group: str, disabled: bool, *, protocol: str = "", members: str = "",
+                           random: int = 0) -> list[dict]:
+        r = self.call("SetGroupDisabled", {"group": group, "protocol": protocol, "members": members,
+                                           "random": random, "disabled": disabled})
+        return r.get("results", [])
+
+    # Scenario and events.
+
+    def scenario(self) -> str:
+        """The whole config as YAML."""
+        return self.call("GetScenario").get("yaml", "")
+
+    def apply_scenario(self, scenario: str | Path, replace: bool = False) -> None:
+        """Apply a scenario: YAML text, or a Path to a YAML file. replace=True
+        removes existing devices and protocols first. Without it, items that
+        already exist fail: everything else is applied, then ClabgenError
+        lists what failed."""
+        if isinstance(scenario, Path):
+            scenario = scenario.read_text()
+        self.call("ApplyScenario", {"yaml": scenario, "replace": replace}, timeout=60)
+
+    def events(self, replay: bool = False, timeout: float | None = None) -> Iterator[dict]:
+        """Stream events (time, source, kind, message, data) as they happen;
+        replay=True starts with the buffered recent ones. timeout bounds each
+        wait for the next event (TimeoutError / socket.timeout when it passes)."""
+        return self._t.stream("WatchEvents", {"replay": replay}, timeout=timeout)
+
+    # Waiting.
+
+    def wait_protocol(self, name: str, check: Callable[[dict], Any], timeout: float = 30,
+                      interval: float = 0.5, what: str = "") -> dict:
+        """Poll a protocol until check(protocol) is truthy; returns the protocol.
+        E.g. wait_protocol("bgp1", lambda p: p["status"]["peers"][0]["state"] == "established")."""
+        def once() -> dict | None:
+            p = self.protocol(name)
+            return p if check(p) else None
+        return wait_until(once, timeout, interval, what or f"{self.name}/{name}")

clabgen-0.3.0/src/clabgen/lab.py

@@ -0,0 +1,306 @@
+"""A lab: several agents, and traffic flows judged across all of them."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Iterator, Mapping
+
+from ._connect import ClabgenError
+from .agent import Agent, wait_until
+
+
+@dataclass
+class FlowResult:
+    """One traffic flow's measurement.
+
+    verdict is "pass", "fail" or "pending" (nothing measured yet), or None
+    when the flow has no checks. failed names the failed checks, e.g.
+    "loss_pct 2.6 > 1, outage_ms 2030 > 50". For one-way flows (no replies)
+    the agent can't judge loss, so rx, lost and loss_pct are the receivers'
+    totals and the verdict stays "pending".
+    """
+
+    agent: str
+    name: str
+    type: str
+    device: str
+    state: str
+    flow_id: str
+    one_way: bool
+    verdict: str | None
+    failed: str
+    tx: int
+    rx: int
+    lost: int
+    loss_pct: float
+    outage_max_ms: float
+    rtt_avg_ms: float | None
+    status: dict = field(repr=False)
+    received: list[dict] = field(default_factory=list, repr=False)
+
+    @property
+    def id(self) -> str:
+        return f"{self.agent}/{self.name}"
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict == "pass"
+
+    def summary(self) -> str:
+        rtt = f" rtt {self.rtt_avg_ms:.2f} ms" if self.rtt_avg_ms is not None else ""
+        v = self.verdict or "no checks"
+        if self.failed:
+            v += f" ({self.failed})"
+        way = " one way" if self.one_way else ""
+        return (f"{self.id}: {v}; tx {self.tx} rx {self.rx} lost {self.lost} ({self.loss_pct:.2f}%)"
+                f" outage {self.outage_max_ms:g} ms{rtt}{way}")
+
+
+def _result(agent: str, p: dict, received: list[dict]) -> FlowResult:
+    s = p.get("status") or {}
+    v = s.get("verdict") or {}
+    one_way = s.get("tracks_replies") is False
+    rx, lost, loss_pct = s.get("rx", 0), s.get("lost", 0), s.get("loss_pct", 0.0)
+    outage = s.get("outage_max_ms", 0.0)
+    if one_way:
+        rx = sum(r.get("rx", 0) for r in received)
+        lost = sum(r.get("lost", 0) for r in received)
+        loss_pct = 100.0 * lost / (rx + lost) if rx + lost else 0.0
+        outage = max([r.get("outage_max_ms", 0.0) for r in received], default=0.0)
+    rtt = s.get("rtt") or {}
+    return FlowResult(
+        agent=agent, name=p["name"], type=p["type"], device=p.get("device", ""), state=s.get("state", p.get("state", "")),
+        flow_id=s.get("flow_id", ""), one_way=one_way, verdict=v.get("result"), failed=v.get("failed", ""),
+        tx=s.get("tx", 0), rx=rx, lost=lost, loss_pct=loss_pct, outage_max_ms=outage,
+        rtt_avg_ms=rtt["avg_us"] / 1000 if "avg_us" in rtt else None, status=s, received=received,
+    )
+
+
+class FlowsFailed(AssertionError):
+    def __init__(self, failed: list[FlowResult], results: list[FlowResult]):
+        lines = [f"{len(failed)} of {len(results)} flows failed:"] + ["  " + r.summary() for r in failed]
+        super().__init__("\n".join(lines))
+        self.failed = failed
+        self.results = results
+
+
+class Measurement:
+    """What Lab.measure() measured; results is set when the with block ends."""
+
+    def __init__(self, lab: "Lab", flows: list[tuple[str, str]]):
+        self.lab = lab
+        self.flows = flows
+        self.started = time.time()
+        self.results: list[FlowResult] = []
+
+    def __getitem__(self, flow: str) -> FlowResult:
+        matches = [r for r in self.results if flow in (r.id, r.name)]
+        if len(matches) != 1:
+            raise KeyError(f"{flow!r}: {'no flow' if not matches else 'ambiguous, use agent/name'}")
+        return matches[0]
+
+    @property
+    def failed(self) -> list[FlowResult]:
+        return _failures(self.results, False)
+
+    def assert_pass(self, require_checks: bool = False) -> None:
+        """Raise FlowsFailed (an AssertionError) if a flow failed its checks,
+        or an echo flow with checks measured nothing; require_checks=True
+        also fails flows without checks."""
+        failed = _failures(self.results, require_checks)
+        if failed:
+            raise FlowsFailed(failed, self.results)
+
+
+def _failures(results: list[FlowResult], require_checks: bool) -> list[FlowResult]:
+    out = []
+    for r in results:
+        if r.verdict == "fail" or (r.verdict == "pending" and not r.one_way) or (r.verdict is None and require_checks):
+            out.append(r)
+    return out
+
+
+def _docker_agents(lab: str) -> dict[str, str]:
+    ids = subprocess.run(["docker", "ps", "-q", "--filter", f"label=containerlab={lab}"],
+                         check=True, capture_output=True, text=True).stdout.split()
+    if not ids:
+        return {}
+    out = {}
+    for c in json.loads(subprocess.run(["docker", "inspect", *ids], check=True, capture_output=True, text=True).stdout):
+        name = c["Config"]["Labels"].get("clab-node-name") or c["Name"].lstrip("/")
+        ips = [n.get("IPAddress") for n in c["NetworkSettings"]["Networks"].values() if n.get("IPAddress")]
+        if ips:
+            out[name] = ips[0]
+    return out
+
+
+class Lab(Mapping[str, Agent]):
+    """Agents by name. Build one from a containerlab lab on this host
+    (Lab.from_docker("b2b")), from a clabgen-ui (Lab.from_ui(url, "b2b")),
+    or from agents: Lab({"gen1": Agent("clab-b2b-gen1"), …})."""
+
+    def __init__(self, agents: Mapping[str, Agent] | Iterable[Agent]):
+        if isinstance(agents, Mapping):
+            self.agents = dict(agents)
+        else:
+            self.agents = {a.name: a for a in agents}
+        for name, a in self.agents.items():
+            a.name = name
+
+    @classmethod
+    def from_docker(cls, lab: str, timeout: float = 10.0) -> "Lab":
+        """The clabgen agents of a running containerlab lab, by node name
+        (nodes that don't answer the agent API are left out)."""
+        nodes = _docker_agents(lab)
+
+        def probe(item: tuple[str, str]) -> Agent | None:
+            a = Agent(item[1], timeout=timeout, name=item[0])
+            try:
+                a.call("GetInfo", timeout=2)
+                return a
+            except ClabgenError:
+                return None
+
+        with ThreadPoolExecutor(max_workers=16) as ex:
+            found = [a for a in ex.map(probe, sorted(nodes.items())) if a]
+        if not found:
+            raise ClabgenError("not_found", f"no clabgen agents in lab {lab!r}")
+        return cls(found)
+
+    @classmethod
+    def from_ui(cls, url: str, lab: str | None = None, timeout: float = 10.0) -> "Lab":
+        """Agents known to a clabgen-ui (e.g. http://host:8090), reached
+        through its proxy; lab picks one lab's. Names are node names, or
+        agent IDs when that would be ambiguous."""
+        url = url.rstrip("/")
+        with urllib.request.urlopen(f"{url}/api/agents", timeout=timeout) as r:
+            agents = [a for a in json.load(r).get("agents", []) if lab is None or a.get("lab") == lab]
+        if not agents:
+            raise ClabgenError("not_found", f"no agents{f' in lab {lab!r}' if lab else ''} at {url}")
+        names = [a.get("name") or a["id"] for a in agents]
+        unique = len(set(names)) == len(names)
+        return cls({(n if unique else a["id"]): Agent(f"{url}/agents/{a['id']}", timeout=timeout)
+                    for n, a in zip(names, agents)})
+
+    def __getitem__(self, name: str) -> Agent:
+        return self.agents[name]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.agents)
+
+    def __len__(self) -> int:
+        return len(self.agents)
+
+    def __repr__(self) -> str:
+        return f"Lab({list(self.agents)})"
+
+    def _each(self, fn: Any) -> dict[str, Any]:
+        with ThreadPoolExecutor(max_workers=max(1, len(self.agents))) as ex:
+            futs = {n: ex.submit(fn, a) for n, a in self.agents.items()}
+            return {n: f.result() for n, f in futs.items()}
+
+    # Flows.
+
+    def _select(self, flows: Iterable[str] | None) -> list[tuple[str, str]]:
+        all_flows = [(n, p["name"]) for n, ps in self._each(lambda a: a.flows()).items() for p in ps]
+        if flows is None:
+            return all_flows
+        out = []
+        for f in [flows] if isinstance(flows, str) else flows:
+            m = [x for x in all_flows if f in (f"{x[0]}/{x[1]}", x[1])]
+            if len(m) != 1:
+                raise KeyError(f"{f!r}: {'no such flow' if not m else 'ambiguous, use agent/name'}")
+            out.append(m[0])
+        return out
+
+    def flow_results(self, flows: Iterable[str] | None = None) -> list[FlowResult]:
+        """Every flow (or the ones named "agent/name" or "name"), with what
+        it measured since its start or last clear."""
+        sel = set(self._select(flows))
+        protos = self._each(lambda a: a.flows())
+        received: dict[str, list[dict]] = {}
+        for n, rs in self._each(lambda a: a.received()).items():
+            for r in rs:
+                received.setdefault(r.get("flow_id", ""), []).append({"agent": n, **r})
+        out = []
+        for n, ps in protos.items():
+            for p in ps:
+                if (n, p["name"]) in sel:
+                    fid = (p.get("status") or {}).get("flow_id", "")
+                    out.append(_result(n, p, received.get(fid, []) if fid else []))
+        return out
+
+    def clear_flows(self, flows: Iterable[str] | None = None) -> None:
+        """Reset flows' statistics at the senders and at every receiver."""
+        sel = set(self._select(flows))
+        ids = set()
+        for n, ps in self._each(lambda a: a.flows()).items():
+            for p in ps:
+                if (n, p["name"]) in sel:
+                    self.agents[n].run(p["name"], "clear")
+                    ids.add((p.get("status") or {}).get("flow_id", ""))
+        for fid in ids - {""}:
+            self._each(lambda a, fid=fid: a.clear_received(flow_id=fid))
+
+    def start_flows(self, flows: Iterable[str] | None = None) -> None:
+        for n, name in self._select(flows):
+            try:
+                self.agents[n].run(name, "start")
+            except ClabgenError as e:
+                if "already running" not in e.message:
+                    raise
+
+    def stop_flows(self, flows: Iterable[str] | None = None) -> None:
+        for n, name in self._select(flows):
+            try:
+                self.agents[n].run(name, "stop")
+            except ClabgenError as e:
+                if "not running" not in e.message:
+                    raise
+
+    @contextmanager
+    def measure(self, flows: Iterable[str] | None = None, settle: float = 2.0) -> Iterator[Measurement]:
+        """Clear flows, run the with block (the test: flap a link, fail a
+        node, …), wait settle seconds for packets in flight to be answered or
+        time out, then collect the results:
+
+            with lab.measure() as m:
+                lab["gen2"].port_down("eth1"); time.sleep(2); lab["gen2"].port_up("eth1")
+            m.assert_pass()
+
+        settle should be at least the flows' reply timeout (1 s by default).
+        """
+        sel = self._select(flows)
+        names = [f"{n}/{f}" for n, f in sel]
+        if sel:
+            self.clear_flows(names)
+        m = Measurement(self, sel)
+        yield m
+        time.sleep(settle)
+        m.results = self.flow_results(names) if sel else []
+
+    def wait_flows_pass(self, flows: Iterable[str] | None = None, timeout: float = 60, interval: float = 1) -> list[FlowResult]:
+        """Wait until every flow with checks passes, e.g. while a lab
+        converges after deploying. A failed verdict stays until the flow is
+        cleared, so failed flows are cleared each round: this returns once
+        all of them have passed since their last failure."""
+        last: list[FlowResult] = []
+
+        def ok() -> bool:
+            nonlocal last
+            last = self.flow_results(flows)
+            if failed := [r.id for r in last if r.verdict == "fail"]:
+                self.clear_flows(failed)
+            return not [r for r in last if r.verdict is not None and r.verdict != "pass" and not r.one_way]
+        try:
+            wait_until(ok, timeout, interval, "flows to pass")
+        except TimeoutError as e:
+            bad = [r for r in last if r.verdict is not None and r.verdict != "pass" and not r.one_way]
+            raise TimeoutError(f"{e}:\n" + "\n".join("  " + r.summary() for r in bad)) from None
+        return last

clabgen-0.3.0/src/clabgen/pytest_plugin.py

@@ -0,0 +1,40 @@
+"""pytest fixtures for clabgen labs (loaded automatically once installed).
+
+    pytest --clabgen-lab b2b                      # a containerlab lab on this host
+    pytest --clabgen-lab b2b --clabgen-ui http://host:8090   # through a clabgen-ui
+
+    def test_failover(clabgen_lab):
+        with clabgen_lab.measure() as m:
+            clabgen_lab["gen2"].port_down("eth1")
+            ...
+        m.assert_pass()
+
+Tests using clabgen_lab are skipped when no lab is given.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from .lab import Lab
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    g = parser.getgroup("clabgen")
+    g.addoption("--clabgen-lab", default=None, help="containerlab lab whose clabgen agents tests use (env CLABGEN_LAB)")
+    g.addoption("--clabgen-ui", default=None, help="reach the agents through this clabgen-ui, e.g. http://host:8090 (env CLABGEN_UI)")
+
+
+def _opt(config: pytest.Config, name: str) -> str | None:
+    return config.getoption(name) or os.environ.get(name.lstrip("-").replace("-", "_").upper())
+
+
+@pytest.fixture(scope="session")
+def clabgen_lab(pytestconfig: pytest.Config) -> Lab:
+    """The lab's agents (clabgen.Lab), by node name."""
+    lab, ui = _opt(pytestconfig, "--clabgen-lab"), _opt(pytestconfig, "--clabgen-ui")
+    if not lab and not ui:
+        pytest.skip("no clabgen lab (--clabgen-lab or CLABGEN_LAB)")
+    return Lab.from_ui(ui, lab) if ui else Lab.from_docker(lab)

clabgen-0.3.0/src/clabgen.egg-info/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: clabgen
+Version: 0.3.0
+Summary: Python client and pytest helpers for clabgen, the protocol emulator and traffic generator for containerlab
+Author-email: Tom Young <ripnet@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ripnet/clabgen
+Classifier: Framework :: Pytest
+Classifier: Topic :: System :: Networking
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# clabgen (Python)
+
+Python client and pytest helpers for
+[clabgen](https://github.com/ripnet/clabgen), the protocol emulator and
+traffic generator for containerlab. Standard library only; Python 3.9+.
+
+```sh
+pip install clabgen
+```
+
+Installing from a checkout or from git builds the package: Ubuntu 22.04's
+own pip 22.0 builds it as `UNKNOWN`, so use a newer pip there (e.g. in a
+virtualenv after `pip install -U pip`).
+
+```python
+def test_failover(clabgen_lab):              # pytest --clabgen-lab b2b
+    with clabgen_lab.measure() as m:
+        clabgen_lab["gen2"].port_down("eth1")
+        time.sleep(2)
+        clabgen_lab["gen2"].port_up("eth1")
+    m.assert_pass()
+```
+
+See [docs/python.md](https://github.com/ripnet/clabgen/blob/main/docs/python.md).
+
+Tests: `pytest` here. The unit tests need nothing; the `agent` tests run
+the agent binary (`make build` at the top, or `CLABGEN_AGENT=path`) in a
+container, so they need docker, and are skipped without it.

clabgen-0.3.0/src/clabgen.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/clabgen/__init__.py
+src/clabgen/_connect.py
+src/clabgen/agent.py
+src/clabgen/lab.py
+src/clabgen/pytest_plugin.py
+src/clabgen.egg-info/PKG-INFO
+src/clabgen.egg-info/SOURCES.txt
+src/clabgen.egg-info/dependency_links.txt
+src/clabgen.egg-info/entry_points.txt
+src/clabgen.egg-info/requires.txt
+src/clabgen.egg-info/top_level.txt
+tests/test_connect.py
+tests/test_live.py

clabgen-0.3.0/src/clabgen.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clabgen-0.3.0/src/clabgen.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+clabgen = clabgen.pytest_plugin

clabgen-0.3.0/src/clabgen.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

clabgen-0.3.0/src/clabgen.egg-info/top_level.txt

@@ -0,0 +1 @@
+clabgen

clabgen-0.3.0/tests/test_connect.py

@@ -0,0 +1,131 @@
+import json
+import struct
+import threading
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+from clabgen import Agent, ClabgenError
+from clabgen._connect import from_wire
+from clabgen.agent import _base_url, _vlan, merge
+
+
+class Fake(BaseHTTPRequestHandler):
+    """A few AgentService methods the way connect-go answers them."""
+
+    calls: list = []
+
+    def log_message(self, *a):
+        pass
+
+    def do_POST(self):
+        method = self.path.rsplit("/", 1)[-1]
+        body = self.rfile.read(int(self.headers["Content-Length"]))
+        Fake.calls.append((self.path, self.headers["Content-Type"], body))
+        if method == "ListPorts":
+            self._json(200, {"ports": [{"name": "eth1", "adminUp": True, "counters": {"rxFrames": "12", "txErrors": "0"}}]})
+        elif method == "GetInfo":
+            self._json(200, {"hostname": "h", "startTime": "2026-10-23T16:29:23.944123456Z"})
+        elif method == "GetProtocol":
+            self._json(200, {"protocol": {"name": "p", "type": "x", "status": {"someKey": 1, "peers": [{"peerAs": 2}]}}})
+        elif method == "DeleteDevice":
+            self._json(404, {"code": "not_found", "message": "device nope: not found"})
+        elif method == "WatchEvents":
+            frames = b""
+            for msg, flags in [({"source": "port/eth1", "kind": "down", "time": "2026-10-23T16:00:00Z"}, 0),
+                               ({"source": "port/eth1", "kind": "up"}, 0),
+                               ({"error": {"code": "canceled", "message": "bye"}}, 2)]:
+                b = json.dumps(msg).encode()
+                frames += struct.pack(">BI", flags, len(b)) + b
+            self.send_response(200)
+            self.send_header("Content-Type", "application/connect+json")
+            self.send_header("Content-Length", str(len(frames)))
+            self.end_headers()
+            self.wfile.write(frames)
+        else:
+            self._json(404, {"code": "unimplemented", "message": method})
+
+    def _json(self, code, v):
+        b = json.dumps(v).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(b)))
+        self.end_headers()
+        self.wfile.write(b)
+
+
+@pytest.fixture(scope="module")
+def fake():
+    srv = ThreadingHTTPServer(("127.0.0.1", 0), Fake)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    yield Agent(f"127.0.0.1:{srv.server_address[1]}")
+    srv.shutdown()
+
+
+def test_unary_converts_names_and_int64(fake):
+    p = fake.ports()[0]
+    assert p == {"name": "eth1", "admin_up": True, "counters": {"rx_frames": 12, "tx_errors": 0}}
+    path, ctype, body = Fake.calls[-1]
+    assert path == "/clabgen.v1.AgentService/ListPorts" and ctype == "application/json" and json.loads(body) == {}
+
+
+def test_timestamps(fake):
+    assert fake.info()["start_time"] == datetime(2026, 10, 23, 16, 29, 23, 944123, tzinfo=timezone.utc)
+
+
+def test_struct_fields_untouched(fake):
+    # Protocol statuses keep the protocol's own keys.
+    assert fake.status("p") == {"someKey": 1, "peers": [{"peerAs": 2}]}
+
+
+def test_errors(fake):
+    with pytest.raises(ClabgenError) as e:
+        fake.delete_device("nope")
+    assert e.value.code == "not_found" and "device nope" in str(e.value)
+
+
+def test_unavailable():
+    with pytest.raises(ClabgenError) as e:
+        Agent("127.0.0.1:1", timeout=2).info()
+    assert e.value.code == "unavailable"
+
+
+def test_stream(fake):
+    it = fake.events(replay=True)
+    first = next(it)
+    assert first["kind"] == "down" and first["time"].year == 2026
+    assert next(it)["kind"] == "up"
+    with pytest.raises(ClabgenError) as e:
+        next(it)
+    assert e.value.code == "canceled"
+    _, ctype, body = Fake.calls[-1]
+    assert ctype == "application/connect+json"
+    flags, n = struct.unpack(">BI", body[:5])
+    assert flags == 0 and json.loads(body[5:5 + n]) == {"replay": True}
+
+
+@pytest.mark.parametrize("addr,url", [
+    ("clab-b2b-gen1", "http://clab-b2b-gen1:8080"),
+    ("10.0.0.1:9000", "http://10.0.0.1:9000"),
+    ("2001:db8::1", "http://[2001:db8::1]:8080"),
+    ("[2001:db8::1]:9000", "http://[2001:db8::1]:9000"),
+    ("http://host:8090/agents/x", "http://host:8090/agents/x"),
+])
+def test_base_url(addr, url):
+    assert _base_url(addr) == url
+
+
+def test_vlan():
+    assert [_vlan(v) for v in [100, "100", "100.5", "0x88a8:200", {"vid": 7}]] == [
+        {"vid": 100}, {"vid": 100}, {"vid": 100, "pcp": 5}, {"tpid": 0x88A8, "vid": 200}, {"vid": 7}]
+
+
+def test_merge():
+    assert merge({"a": 1, "c": {"x": 1, "y": 2}}, {"b": 2, "c": {"y": 3}}) == {"a": 1, "b": 2, "c": {"x": 1, "y": 3}}
+
+
+def test_from_wire_counters_map():
+    # GetDeviceIP counters: a map of uint64s.
+    assert from_wire({"counters": {"arp_rx": "3"}, "neighbors": [{"ageMs": "1500"}]}) == {
+        "counters": {"arp_rx": 3}, "neighbors": [{"age_ms": 1500}]}

clabgen-0.3.0/tests/test_live.py

@@ -0,0 +1,141 @@
+"""Against a real agent (see conftest.agent). Two devices on the same port
+reach each other inside the agent, so flows run without a second node."""
+
+import time
+
+import pytest
+
+from clabgen import ClabgenError, FlowsFailed, Lab, pcap_data
+
+pytestmark = pytest.mark.agent
+
+A_MAC, B_MAC = "02:00:00:00:0a:01", "02:00:00:00:0b:01"
+
+
+def two_devices(agent, **kw):
+    agent.add_device("a", agent.test_port, vlans=[100], mac=A_MAC, **kw.get("a", {}))
+    agent.add_device("b", agent.test_port, vlans=[100], mac=B_MAC, **kw.get("b", {}))
+
+
+def test_info_and_ports(agent):
+    assert agent.info()["version"]
+    p = agent.port(agent.test_port)
+    assert p["oper_up"] and isinstance(p["counters"].get("rx_frames", 0), int)
+
+
+def test_devices(clean):
+    d = clean.add_device("d", clean.test_port, vlans=["0x88a8:200", "10.3"], addresses=["10.0.0.1/24"])
+    assert [v["vid"] for v in d["vlans"]] == [200, 10] and d["vlans"][0]["tpid"] == 0x88A8 and d["mac_derived"]
+    d = clean.update_device("d", vlans=[300])
+    assert [v["vid"] for v in d["vlans"]] == [300] and d["addresses"] == ["10.0.0.1/24"]
+    assert "10.0.0.1/24" in clean.device_ip("d")["addresses"]
+    clean.delete_device("d")
+    with pytest.raises(ClabgenError) as e:
+        clean.device("d")
+    assert e.value.code == "not_found"
+
+
+def test_protocols(clean):
+    two_devices(clean)
+    p = clean.add_protocol("s", "l2", "a", dst_mac=B_MAC, rate=50, checks={"max_loss_pct": 1})
+    assert p["state"] == "running" and p["config"]["rate"] == 50
+    # Merged onto the current config.
+    p = clean.update_protocol("s", rate=20, checks={"max_outage_ms": 100})
+    assert p["config"]["rate"] == 20 and p["config"]["dst_mac"] == B_MAC
+    assert p["config"]["checks"] == {"max_loss_pct": 1, "max_outage_ms": 100}
+    assert clean.disable("s")["state"] == "disabled"
+    assert clean.enable("s")["state"] == "running"
+    assert clean.run("s", "preview")
+    assert [f["name"] for f in clean.flows()] == ["s"]
+    with pytest.raises(ClabgenError) as e:
+        clean.add_protocol("s", "l2", "a")
+    assert e.value.code == "already_exists"
+
+
+def test_scenario(clean):
+    two_devices(clean)
+    y = clean.scenario()
+    assert "02:00:00:00:0a:01" in y
+    clean.apply_scenario("devices: []\n", replace=True)
+    assert clean.devices() == []
+    clean.apply_scenario(y)
+    assert {d["name"] for d in clean.devices()} == {"a", "b"}
+
+
+def test_events(clean):
+    events = clean.events(timeout=10)
+    clean.add_device("ev", clean.test_port, vlans=[7])
+    for e in events:
+        if e["source"] == "device/ev":
+            assert e["kind"] and e["time"].year >= 2026
+            break
+
+
+def echo_lab(agent):
+    two_devices(agent)
+    agent.add_protocol("echo", "l2-echo", "b")
+    agent.add_protocol("rt", "l2", "a", dst_mac=B_MAC, reply="echo", rate=100, timeout="300ms", auto_start=True,
+                       checks={"max_loss_pct": 1, "max_outage_ms": 100})
+    agent.add_protocol("oneway", "l2", "a", dst_mac=B_MAC, rate=100, auto_start=True)
+    return Lab({"gen": agent})
+
+
+def test_measure_pass(clean):
+    lab = echo_lab(clean)
+    lab.wait_flows_pass(timeout=20)
+    with lab.measure() as m:
+        time.sleep(2)
+    m.assert_pass()
+    rt, oneway = m["rt"], m["gen/oneway"]
+    assert rt.verdict == "pass" and rt.rx > 100 and rt.lost == 0 and rt.rtt_avg_ms is not None
+    # One way: the receiver's numbers, no verdict without replies.
+    assert oneway.one_way and oneway.rx > 100 and oneway.lost == 0 and oneway.received[0]["device"] == "b"
+    assert oneway.verdict is None
+
+
+def test_measure_fail(clean):
+    lab = echo_lab(clean)
+    lab.wait_flows_pass(timeout=20)
+    with lab.measure() as m:
+        clean.port_down(clean.test_port)
+        time.sleep(1)
+        clean.port_up(clean.test_port)
+    with pytest.raises(FlowsFailed) as e:
+        m.assert_pass()
+    assert [r.id for r in e.value.failed] == ["gen/rt"]
+    assert "outage_ms" in m["rt"].failed and m["rt"].lost > 50
+    assert "gen/rt: fail" in str(e.value)
+    # Failed verdicts stay until cleared; wait_flows_pass clears them.
+    assert lab.flow_results(["rt"])[0].verdict == "fail"
+    lab.wait_flows_pass(["rt"], timeout=20)
+
+
+def test_start_stop(clean):
+    lab = echo_lab(clean)
+    lab.stop_flows()
+    lab.stop_flows()  # already stopped: fine
+    assert {r.state for r in lab.flow_results()} == {"idle"}
+    lab.start_flows(["rt"])
+    assert lab.flow_results(["rt"])[0].state == "running"
+    with pytest.raises(KeyError):
+        lab.flow_results(["nope"])
+
+
+def test_packet_builder(clean):
+    two_devices(clean)
+    p = clean.preview("a", layers=[{"ethernet": {"dst": B_MAC}}, {"vlan": {"vid": 5}}, {"payload": {"size": 30}}],
+                      modifiers=[{"field": "vlan.vid", "mode": "increment"}], index=2)
+    assert p["index"] == 2 and [l["title"] for l in p["layers"]] == ["Ethernet", "Device VLAN tags (1)", "EtherType", "VLAN", "Payload"]
+    vlan = {f["name"]: f["value"] for f in p["layers"][3]["fields"]}
+    assert vlan["vid"] == "7"
+    # The previewed frame, replayed from a capture: b counts it (it is signed).
+    frame = bytes.fromhex(clean.preview("a", layers=[{"ethernet": {"dst": B_MAC}}, {"payload": {"size": 46}}])["hex"])
+    import struct
+    cap = struct.pack("<IHHiIII", 0xA1B2C3D4, 2, 4, 0, 0, 65535, 1) + struct.pack("<IIII", 0, 0, len(frame), len(frame)) + frame
+    assert clean.preview("a", pcap=cap)["frames"][0]["length"] == len(frame)
+    clean.add_protocol("replay", "packet", "a", pcap={"data": pcap_data(cap)}, mode="count", count=20, rate=200, auto_start=True)
+    clean.wait_protocol("replay", lambda x: x["status"]["state"] == "done", timeout=10)
+    assert clean.status("replay")["tx"] == 20
+    with pytest.raises(ClabgenError) as e:
+        clean.preview("a", layers=[{"udp": {}}])
+    assert "needs an IPv4 or IPv6 layer" in e.value.message