o-family

o-family monogatari

monogatari — a tale

Stories for apps built on ochazuke: JSON keystroke scripts played headless against your app's real UI, with expectations on what the screen shows.

libraryv0.1.0earlyGo 1.26 or newer

GitHub READMEGo referenceCHANGELOG

overview

What it is

A story is a JSON file that names an app, a fixture and a script of keys, and says what the screen must show afterwards. monogatari plays it against the app's real ochazuke.Model, headless under go test or live in a terminal, so a UI bug becomes a story before it is fixed and a reviewer can walk an app change key by key without touching anyone's data.

monogatari knows no app. An app's behaviour comes in through its fixtures, named starting states built from a seed, and the tester links in only behind the monogatari build tag, so a normal binary carries none of it.

install

go get 
go get github.com/unixsuperhero/monogatari@latest
tester build 
go build -tags monogatari -o bin/mtm-story ./cmd/mtm
a storyjson
{
  "name": "the palette highlights nothing until ctrl+n",
  "area": "palette",
  "page": { "lists": [{ "id": "a", "rows": 3 }] },
  "script": [":", "ctrl+n"],
  "expect": [
    { "after": 1, "highlighted": 0, "dimmed": 1, "mode": "insert", "lacks": ["> "] },
    { "highlighted": 0, "dimmed": 1, "contains": ["> accept"] }
  ]
}

features

What it does

  1. 01 / 05

    Stories

    JSON keystroke scripts with expectations: the focused list, the mode, text the screen contains or lacks, the highlighted rows, the page. Keys are named as bindings name them.

  2. 02 / 05

    Headless runs

    Every story runs under go test against the app's real UI, with a fake clock, jobs and ticks, so a run is the same every time.

  3. 03 / 05

    Recordings

    Every live session is recorded: a ring of the last five per story, plus named saves you keep. Replay with timing, trim to the keys that matter, turn one into a headless check.

  4. 04 / 05

    Explorer

    Walks an app's states from a story's start and reports panics, focus traps, hints that lie, overflowing renders and jobs that never settle, each written out as a story.

  5. 05 / 05

    A host per app

    CLI subcommands, an index TUI and a player, mounted as an oden command under the app's own name (mtm story ...).

in an appsh
mtm-story story run panes                         # headless; non-zero exit on failure
mtm-story story open panes/detach-keeps-preview   # live, in the real chrome
mtm-story story explore panes                     # the state explorer

read more

Documentation