"""Tests for the scripted CLI's output language (:mod:`meshterm.ui.script`). The CLI is read by ``awk``, and every rule that makes that possible is testable: no colour, no wrapping, no framing, quoted names, absolute times, one token for absent, one documented exit status per outcome. These are the enforcement point for :mod:`meshterm.ui.script` the way ``test_gallery`` is for the screens. """ from __future__ import annotations import io import re from datetime import datetime, timedelta, timezone import pytest from rich.console import Group from rich.panel import Panel from rich.table import Table from rich.text import Text from meshterm.core import exitcodes from meshterm.ui import script #: Any ANSI escape sequence. Nothing the scripted console emits may match this. _ANSI = re.compile(r"\x1b\[") def _rendered(*renderables: object) -> str: """Print ``renderables`` through the scripted console and return what came out.""" buffer = io.StringIO() console = script.console(buffer) for renderable in renderables: console.print(renderable) console.file.flush() return buffer.getvalue() # -- quoting ------------------------------------------------------------------------- @pytest.mark.parametrize( "value,expected", [ ("Yagi-Repeater", '"Yagi-Repeater"'), ("YUL Cartierville", '"YUL Cartierville"'), ("Node, Inc", '"Node, Inc"'), ('He said "hi"', '"He said \\"hi\\""'), ("back\\slash", '"back\\\\slash"'), ("", '""'), (None, '""'), ], ) def test_quote_makes_any_name_exactly_one_field(value: str | None, expected: str) -> None: """A name is quoted and its quotes and backslashes escaped, whatever it holds. This is what lets a listing be split: an unquoted ``YUL Cartierville`` is two fields, and an unquoted ``Node, Inc`` is two hops of a path line. """ assert script.quote(value) == expected def test_a_quoted_name_survives_a_round_trip_through_the_escaping() -> None: """The escaping is the ordinary backslash convention, so the value reads back.""" for name in ('a "quoted" name', "back\\slash", 'both\\"kinds'): body = script.quote(name)[1:-1] assert body.replace('\\"', '"').replace("\\\\", "\\") == name # -- timestamps ---------------------------------------------------------------------- def test_stamp_is_absolute_local_iso_to_the_second() -> None: """A time is printed as something a script can sort and subtract.""" when = datetime(2026, 9, 7, 22, 22, 41, tzinfo=timezone.utc) text = script.stamp(when) assert datetime.fromisoformat(text) == when assert text.endswith(when.astimezone().strftime("%z")[:3] + ":00") def test_stamp_reads_an_unknown_offset_as_absent() -> None: """A naive datetime is a time whose offset we don't know, which is not a fact. The same rule :func:`~meshterm.ui.widgets._age_seconds` applies to relative ages. """ assert script.stamp(None) == script.NONE assert script.stamp(datetime(2026, 9, 7, 22, 22, 41)) == script.NONE def test_no_relative_age_ever_reaches_the_scripted_output() -> None: """``3h`` is for a screen; the CLI's stamp is absolute even for a fresh time.""" assert script.stamp(datetime.now(timezone.utc) - timedelta(seconds=5)) != "now" # -- the absent token ----------------------------------------------------------------- def test_one_token_stands_for_every_kind_of_absence() -> None: """A reader (and a parser) learns ``-`` once, and never meets an em dash or an n/a.""" assert script.NONE == "-" assert script.number(None) == script.NONE assert script.path([]) == script.NONE def test_number_formats_with_its_spec_when_there_is_one() -> None: """A present number is formatted; only an absent one becomes the token.""" assert script.number(2.64, "+.1f") == "+2.6" assert script.number(-1.5, "+.1f") == "-1.5" assert script.number(7) == "7" # -- path lines ----------------------------------------------------------------------- def test_a_path_line_quotes_each_node_and_hangs_its_hash_outside_the_quotes() -> None: """The CLI's path shape: ``"Name" (hash)``, hops joined by a bare comma.""" line = script.path([("Alice", "3d"), ("Yagi-Repeater", "f2")]) assert line == '"Alice" (3d),"Yagi-Repeater" (f2)' def test_a_path_line_names_our_own_node_like_any_other() -> None: """No star: the glyph says "you already know this one", which is false of a parser.""" line = script.path([("MockCompanion", "a1"), ("Alice", "3d"), ("MockCompanion", "a1")]) assert "★" not in line assert line.startswith('"MockCompanion" (a1)') assert line.endswith('"MockCompanion" (a1)') def test_a_path_line_prints_a_name_alone_when_no_hash_places_it() -> None: """An unidentified node has a name and nothing else; it does not get an empty ``()``.""" assert script.path([("Alice", None)]) == '"Alice"' def test_a_path_line_splits_even_when_a_name_holds_a_comma() -> None: """The quoting is what makes the bare comma separator safe.""" line = script.path([("Node, Inc", "3d"), ("Bob", "f2")]) assert line.count(",") == 2 # the one inside the name, and the one separating hops assert line == '"Node, Inc" (3d),"Bob" (f2)' # -- the console ---------------------------------------------------------------------- def test_the_scripted_console_emits_no_escape_sequence_at_all() -> None: """Not a colour, not a bold, not a dim — ``stdout`` is a pipe more often than a screen.""" loud = Text.assemble( ("brand", "brand"), ("bold", "bold"), ("hex", "#ff8800"), ("reverse", "reverse") ) assert not _ANSI.search(_rendered(loud)) def test_the_scripted_console_never_wraps_a_record_onto_a_second_line() -> None: """A record is a line: wrapping would put half its fields under the wrong headings.""" table = script.columns("KEY", "VALUE") table.add_row("basemap_tilejson_url", "x" * 400) lines = _rendered(table).splitlines() assert len(lines) == 2 # the header and the one record assert lines[1].endswith("x" * 400) def test_the_scripted_console_leaves_no_trailing_whitespace() -> None: """Padding the last column to its width would put invisible spaces on every line.""" table = script.columns("NAME", "TYPE") table.add_row(script.quote("a-long-name"), "node") table.add_row(script.quote("b"), "repeater") for line in _rendered(table).splitlines(): assert line == line.rstrip(), repr(line) def test_the_gutter_still_separates_columns_after_the_trimming() -> None: """The trimmer holds trailing whitespace back; it must not eat the padding *between*. Rich writes a rendered row segment by segment and flushes after each one, so a wrapper that trimmed at flush would throw away the very spaces that make the columns columns (see :class:`meshterm.ui.script._Trimmed`). """ table = script.columns("NAME", "TYPE", "PKTS", right=("PKTS",)) table.add_row(script.quote("Alice"), "node", "12") header, record = _rendered(table).splitlines() assert header.split() == ["NAME", "TYPE", "PKTS"] assert record.split() == ['"Alice"', "node", "12"] assert " " * script.GUTTER in record def test_columns_align_so_every_record_splits_the_same_way() -> None: """Every field lands in its heading's column, whatever the widths.""" table = script.columns("NAME", "TYPE") table.add_row(script.quote("Yagi-Repeater"), "repeater") table.add_row(script.quote("Al"), "node") header, *records = _rendered(table).splitlines() starts = {line.index("re") if "repeater" in line else line.index("node") for line in records} assert starts == {header.index("TYPE")} # every TYPE value opens under its heading # -- framing -------------------------------------------------------------------------- def test_a_panel_gives_up_its_border_and_its_title() -> None: """No frames: the command the reader typed is the title.""" out = _rendered(*script.flatten(Panel(Text("body"), title="Trace summary"))) assert out.strip() == "body" def test_a_table_gives_up_its_box_its_title_and_its_expansion() -> None: """A shared table that still arrives boxed is unframed on the way out.""" from rich import box table = Table(title="Contacts", box=box.SIMPLE_HEAD, expand=True) table.add_column("NAME") table.add_row("Alice") out = _rendered(*script.flatten(table)) assert "Contacts" not in out assert not any(ch in out for ch in "─│┌└") def test_a_group_is_unframed_member_by_member() -> None: """Framing is stripped however deep a shared renderable nests it.""" nested = Group(Panel(Text("one"), title="First"), Panel(Text("two"), title="Second")) assert _rendered(*script.flatten(nested)).split() == ["one", "two"] def test_no_rendered_line_is_a_box_drawing_rule() -> None: """No borders and no header rules — a listing is its header line and its records.""" table = script.columns("NAME", "TYPE") table.add_row(script.quote("Alice"), "node") assert "─" not in _rendered(table) # -- key/value listings --------------------------------------------------------------- def test_pairs_print_one_fact_per_line_with_no_header() -> None: """The ``sysctl -a`` shape: a key, the gutter, and the rest of the line as its value.""" out = _rendered(script.pairs([("name", "MockCompanion"), ("uptime_s", "93784")])) assert [line.split(None, 1) for line in out.splitlines()] == [ ["name", "MockCompanion"], ["uptime_s", "93784"], ] def test_a_pairs_value_is_unquoted_because_it_is_the_rest_of_the_line() -> None: """Quoting is for a name sharing a line with other fields; here there are only two.""" out = _rendered(script.pairs([("name", "YUL Cartierville")])) assert out.splitlines()[0].split(None, 1) == ["name", "YUL Cartierville"] # -- exit statuses -------------------------------------------------------------------- def test_every_exit_code_is_documented() -> None: """A documented return value is half of what makes the CLI scriptable.""" codes = { exitcodes.OK, exitcodes.FAILURE, exitcodes.USAGE, exitcodes.NO_DEVICE, exitcodes.DEVICE, exitcodes.NO_RESULT, } assert set(exitcodes.MEANINGS) == codes assert all(meaning for meaning in exitcodes.MEANINGS.values()) def test_the_codes_are_distinct_and_ok_is_zero() -> None: """The shell's own convention, and no two outcomes share a status.""" assert exitcodes.OK == 0 assert len(set(exitcodes.MEANINGS)) == len(exitcodes.MEANINGS) def test_the_help_epilog_names_every_status() -> None: """A caller should not have to find the table in a README.""" from meshterm.cli import EXIT_STATUS_EPILOG for code, meaning in exitcodes.MEANINGS.items(): assert f"{code} {meaning}" in EXIT_STATUS_EPILOG