From 866451ce092bcda3da21545314d44d834d8126fb Mon Sep 17 00:00:00 2001 From: ruinivist Date: Sat, 28 Mar 2026 12:04:19 +0000 Subject: [PATCH] docs: add license + readme typo fixes --- LICENSE | 21 +++++++++++++++++++ README.md | 57 +++++++++++++++++++++++++++++++++++++++++++--------- e2e/demo/in | 5 +++-- e2e/demo/out | 12 ++--------- 4 files changed, 74 insertions(+), 21 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c568e62 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 ruinivist + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index f7c19e5..ea86ac9 100644 --- a/README.md +++ b/README.md @@ -2,39 +2,78 @@ E2E tests for CLIs. -Problem: There isn't an easy way for testing e2e behavior on CLIs that is as simple as you recording a set of actions and ensuring future build replicate the ouput. What is ussually done is via code which doesn't convey visually what the test actually is. +Problem: There isn't an easy way to test E2E behavior for CLIs that is as simple as recording a set of actions and ensuring future builds replicate the output. What is usually done is code-based, which doesn't convey visually what the test actually is. > _mire tries to make it as simple as recording and replaying_ ![demo](demo.gif) +**How it works?** + +Idea is that mire spawns a session and drops you in it to record your actions, as you would do for manual testing.\ +Once done, it'll save the inputs and outputs as goldens to compare against.\ +Tests will use those inputs later to recreate and verify that the output for the same set of input keystrokes is still the same. + **Features** - sandboxed -- fast, explicit, simple, enought that a 10s gif can demonstrate it entirely +- fast, explicit, simple, enough that a 10s gif can demonstrate it entirely - record, test, that's it - start simple, tweak the entire environment if you want ## Quickstart +Linux-focused for now; requires `bash` and `bwrap` to be available in `PATH`. + **Install** - clone - `make build` -- add `build/mire` to path +- add `build/mire` to your `PATH` **Using** -- `mire init` to create the the single config file, every entry is explicit in config. +- `mire init` to create the single config file; every entry is explicit. - `mire record test/name/` - now test how you would test manually, try out commands to see if they work as expected - `mire test` or `mire test specific/test` - `mire rewrite` - to rewrite all golden outputs in case of a style change -**Using fixtures?** -You can write you script commands in `setup.sh` at any level, anything at that and nested level will have those run before dropping you -into record. +**Fixtures?** + +This is for for modifying anything within the sandox. + +You can write your script commands in `setup.sh` at any level. Anything at that and nested levels will be run before dropping you into record. + +**Configuration** + +There's a root level config file - `mire.toml` created via `mire init`.\ +This is primarily for host to sandbox setup. + +```toml +[mire] + # which folder to strore tests in + test_dir = "e2e" + # regexes for differing lines to ignore during replay comparison + ignore_diffs = [] + +[sandbox] + # home is where mire would drop you by default on record + home = "/home/test" + # read only paths from host, entry looks like "path on host:path on sanbox" + # paths on host are absolute or relative to repo root + mounts = [] + # read only host paths to expose on PATH inside the sandbox as /tmp/mire/bin/ + # paths on host can be absolute or relative to repo root + paths = [] +``` + +All possible options are in this config, if it's not there isn't not possible at the moment. + +For anything esoteric, you can always just modify the generated `shell.sh` directly as well. + +> This branched off as a setup for another project so I've only added what I felt needed. Feel free to make an issue! ## Other tools? -VHS comes close, which is what I initially tried for. It isn't suitable for testing as the output is terminal sessions captured as full frames in text. This makes it hard to know what the test is unless you watch it and even then it has timing issues, multiple blank frames polluting goldens, slow exection unless -you post process to limit all the sleeps, and also required you to handle the test environment/sandboxing yourself. +VHS comes close, which is what I initially tried. It isn't suitable for testing because the output is terminal sessions captured as full frames in text. This makes it hard to know what the test is unless you watch it, and even then it has timing issues, multiple blank frames polluting goldens, and slow execution unless +you post-process to limit all the sleeps. It also requires you to handle the test environment and sandboxing yourself. diff --git a/e2e/demo/in b/e2e/demo/in index 21bb6e2..13a97db 100644 --- a/e2e/demo/in +++ b/e2e/demo/in @@ -1,2 +1,3 @@ -cowsay "you can just type and test yoas you wouidld" -exit +micro +asome +exit diff --git a/e2e/demo/out b/e2e/demo/out index a173319..0a3287e 100644 --- a/e2e/demo/out +++ b/e2e/demo/out @@ -1,11 +1,3 @@ -[?2004h$ cowsay "you can just type and test yo  as you wouid  ld" -[?2004l _________________________________________ -< you can just type and test as you would > - ----------------------------------------- - \ ^__^ - \ (oo)\_______ - (__)\ )\/\ - ||----w | - || || -[?2004h$ exit +[?2004h$ micro +[?2004l [?1049h[?25l[?2004h[?1000h[?1002h[?1006h[?25l(B1 (B (B                         (BNo name (1,1) | ft:unknown | unix | utf-8 Alt-g: bindings, Ctrl-g: help(B [?12l[?25h[?25l(Ba(B+ (,2)| ft:uknown| unix| utf-8[?12l[?25h[?25l(BFilename:[?12l[?25h[?25ls[?12l[?25h[?25lo[?12l[?25h[?25lm[?12l[?25h[?25le[?12l[?25h[?25l(B2 (Bsme (1,2) | ft:unknow | uix| utf-8 (BSavd some [?12l[?25h[?25l[?12l[?25h[?12l[?25h(B[?1049l[?1l>[?1000l[?1002l[?1006l[?2004l[?2004h$ exit [?2004l exit