286 lines
9.0 KiB
HTML
286 lines
9.0 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>shout — shell output tester</title>
|
|
<meta name="description" content="shell output tester">
|
|
<style>
|
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
|
|
:root {
|
|
--bg: #fff;
|
|
--fg: #444;
|
|
--bright: #1a1a1a;
|
|
--green: #1a7f37;
|
|
--red: #cf222e;
|
|
--dim: #888;
|
|
--accent: #1a7f37;
|
|
--code-bg: #f5f5f5;
|
|
--border: #ddd;
|
|
}
|
|
|
|
@media (prefers-color-scheme: dark) {
|
|
:root {
|
|
--bg: #0a0a0a;
|
|
--fg: #b0b0b0;
|
|
--bright: #e0e0e0;
|
|
--green: #4ec966;
|
|
--red: #e55;
|
|
--dim: #555;
|
|
--accent: #4ec966;
|
|
--code-bg: #111;
|
|
--border: #222;
|
|
}
|
|
}
|
|
|
|
html { font-size: 16px; }
|
|
|
|
body {
|
|
background: var(--bg);
|
|
color: var(--fg);
|
|
font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', 'JetBrains Mono', 'Menlo', 'Consolas', monospace;
|
|
line-height: 1.6;
|
|
padding: 0 1.5rem;
|
|
max-width: 680px;
|
|
margin: 0 auto;
|
|
-webkit-font-smoothing: antialiased;
|
|
}
|
|
|
|
header {
|
|
padding: 6rem 0 2.5rem;
|
|
}
|
|
|
|
h1 {
|
|
font-size: 2.5rem;
|
|
font-weight: 700;
|
|
color: var(--bright);
|
|
letter-spacing: -0.03em;
|
|
}
|
|
|
|
h1 span {
|
|
color: var(--accent);
|
|
}
|
|
|
|
.tagline {
|
|
font-size: 1.1rem;
|
|
color: var(--dim);
|
|
margin-top: 0.5rem;
|
|
}
|
|
|
|
.install {
|
|
margin-top: 2rem;
|
|
display: inline-block;
|
|
background: var(--code-bg);
|
|
border: 1px solid var(--border);
|
|
padding: 0.6rem 1.2rem;
|
|
border-radius: 4px;
|
|
font-size: 0.9rem;
|
|
color: var(--bright);
|
|
cursor: pointer;
|
|
position: relative;
|
|
transition: border-color 0.15s;
|
|
}
|
|
|
|
.install:hover {
|
|
border-color: var(--accent);
|
|
}
|
|
|
|
.install .hint {
|
|
color: var(--dim);
|
|
font-size: 0.75rem;
|
|
margin-left: 1rem;
|
|
}
|
|
|
|
section {
|
|
padding: 0 0 2em 0;
|
|
}
|
|
|
|
h2 {
|
|
font-size: 0.85rem;
|
|
font-weight: 600;
|
|
color: var(--dim);
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.1em;
|
|
margin-bottom: 1.5rem;
|
|
}
|
|
|
|
p {
|
|
margin-bottom: 1rem;
|
|
font-size: 0.95rem;
|
|
}
|
|
|
|
.bright { color: var(--bright); }
|
|
.green { color: var(--green); }
|
|
.red { color: var(--red); }
|
|
.dim { color: var(--dim); }
|
|
|
|
pre {
|
|
background: var(--code-bg);
|
|
border: 1px solid var(--border);
|
|
border-radius: 4px;
|
|
padding: 1.2rem 1.4rem;
|
|
overflow-x: auto;
|
|
font-size: 0.85rem;
|
|
line-height: 1.7;
|
|
margin-bottom: 1.5rem;
|
|
}
|
|
|
|
pre code {
|
|
color: var(--fg);
|
|
}
|
|
|
|
.prompt { color: var(--dim); }
|
|
.cmd { color: var(--bright); }
|
|
.output { color: var(--fg); }
|
|
.comment { color: var(--dim); font-style: italic; }
|
|
.wildcard { color: var(--accent); }
|
|
.exit-code { color: var(--red); }
|
|
.pass { color: var(--green); }
|
|
|
|
|
|
footer {
|
|
padding: 3rem 0;
|
|
border-top: 1px solid var(--border);
|
|
color: var(--dim);
|
|
font-size: 0.8rem;
|
|
}
|
|
|
|
footer a {
|
|
color: var(--fg);
|
|
text-decoration: none;
|
|
}
|
|
|
|
footer a:hover {
|
|
color: var(--accent);
|
|
}
|
|
|
|
a {
|
|
color: var(--accent);
|
|
text-decoration: none;
|
|
}
|
|
|
|
a:hover {
|
|
text-decoration: underline;
|
|
}
|
|
|
|
@media (max-width: 520px) {
|
|
header { padding: 3rem 0 2rem; }
|
|
h1 { font-size: 2rem; }
|
|
section { padding: 2rem 0; }
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<header>
|
|
<h1><span>$</span> shout</h1>
|
|
<p class="tagline">shell output tester</p>
|
|
<div class="install" onclick="navigator.clipboard.writeText('curl -fsSL https://because.sh/shout | sh')">
|
|
<span class="prompt">$</span> <span class="cmd">curl -fsSL https://because.sh/shout | sh</span>
|
|
<span class="hint">click to copy</span>
|
|
</div>
|
|
</header>
|
|
|
|
<section>
|
|
<h2>Write a test</h2>
|
|
<p>A <code>.shout</code> file is just a shell session. Commands start with <code class="bright">$</code>, everything else is expected output.</p>
|
|
<pre><code><span class="prompt">$</span> <span class="cmd">echo hello</span>
|
|
<span class="output">hello</span>
|
|
|
|
<span class="prompt">$</span> <span class="cmd">ls missing</span>
|
|
<span class="output">ls: missing: No such file or directory</span>
|
|
<span class="exit-code">[1]</span>
|
|
|
|
<span class="prompt">$</span> <span class="cmd">brew --version</span>
|
|
<span class="output">Homebrew 5</span><span class="wildcard">...</span></code></pre>
|
|
<p><code class="wildcard">...</code> matches anything — inline or across lines.</p>
|
|
<p><code class="exit-code">[1]</code> asserts the exit code.</p>
|
|
<p><code class="dim">$#</code> starts a comment line — not executed, no output expected.</p>
|
|
<pre><code><span class="prompt">$</span><span class="comment"># start the server</span>
|
|
<span class="prompt">$</span> <span class="cmd">my-server &</span>
|
|
<span class="prompt">$</span><span class="comment"># now test it</span>
|
|
<span class="prompt">$</span> <span class="cmd">curl localhost:8080</span>
|
|
<span class="output">OK</span></code></pre>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Setup & teardown</h2>
|
|
<p>Use <code class="bright">@setup</code> to share commands across test files. Use <code class="bright">@teardown</code> to clean up after tests — it runs regardless of pass/fail.</p>
|
|
<pre><code><span class="comment"># setup.shout</span>
|
|
<span class="output">export DB_URL=sqlite:data/test.db</span>
|
|
<span class="bright">@teardown</span> <span class="cmd">rm -f "$SHOUT_PROJECT_DIR/data/test.db"</span></code></pre>
|
|
<pre><code><span class="bright">@setup</span> <span class="cmd">setup.shout</span>
|
|
<span class="bright">@teardown</span> <span class="cmd">rm -f /tmp/extra-cleanup</span>
|
|
|
|
<span class="prompt">$</span> <span class="cmd">create-db && run-tests</span>
|
|
<span class="wildcard">...</span></code></pre>
|
|
<p><code>@teardown</code> can appear in both <code>.shout</code> files and setup files. Teardown failures produce warnings but don't affect test results.</p>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Macros</h2>
|
|
<p>Use <code class="bright">@def</code> to define reusable command macros.</p>
|
|
<pre><code><span class="bright">@def</span> <span class="cmd">greet echo "hello world"</span>
|
|
|
|
<span class="prompt">$</span> <span class="cmd">greet</span>
|
|
<span class="output">hello world</span></code></pre>
|
|
<p>If a command matches a macro name exactly, the body is substituted. Use <code>\</code> for multi-line bodies — the body can start on the same line or on the next continuation line. Macros from setup files are inherited; user-file macros override them.</p>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Run it</h2>
|
|
<pre><code><span class="prompt">$</span> <span class="cmd">shout test</span>
|
|
<span class="pass">...............
|
|
15 passed</span> <span class="dim">in 23ms</span></code></pre>
|
|
<p>Each file gets a fresh temp directory and its own <code>/bin/sh</code> session. State carries between commands within a file.</p>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Update expectations</h2>
|
|
<pre><code><span class="prompt">$</span> <span class="cmd">shout test --update</span></code></pre>
|
|
<p>Rewrites your <code>.shout</code> files with the actual output. No more copy-pasting from the terminal.</p>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Usage</h2>
|
|
<pre><code><span class="prompt">$</span> <span class="cmd">shout test --help</span>
|
|
<span class="output">Usage: shout test [options] [files...]
|
|
|
|
Run .shout test files
|
|
|
|
Arguments:
|
|
files Files or directories to test
|
|
|
|
Options:
|
|
-u, --update Rewrite expected output in-place with actual output
|
|
-k, --keep Keep temp directories after run
|
|
--clean-env Start with empty environment
|
|
--path <path> Prepend <path> to PATH (repeatable)
|
|
--timeout <dur> Per-command timeout (default: "10s")
|
|
-t, --filter Only run files matching <pattern> (substring match)
|
|
-v, --verbose Print each command as it runs
|
|
--port-from <n> Auto-assign $PORT starting from n (default: "5400")
|
|
--parallel Run files in parallel
|
|
-h, --help display help for command</span></code></pre>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Environment</h2>
|
|
<p>Shout sets these variables before running your commands:</p>
|
|
<pre><code><span class="bright">HOME</span> <span class="dim">→</span> <span class="output">temp directory for this test file</span>
|
|
<span class="bright">SHOUT_DIR</span> <span class="dim">→</span> <span class="output">same temp directory</span>
|
|
<span class="bright">SHOUT_SOURCE_DIR</span> <span class="dim">→</span> <span class="output">directory containing the .shout file</span>
|
|
<span class="bright">SHOUT_PROJECT_DIR</span> <span class="dim">→</span> <span class="output">directory where shout was invoked</span>
|
|
<span class="bright">PORT</span> <span class="dim">→</span> <span class="output">auto-assigned from 5400 (or --port-from), increments per file</span>
|
|
<span class="bright">PATH</span> <span class="dim">→</span> <span class="output">prepended with --path dirs, if any</span></code></pre>
|
|
<p>Each file runs in its own temp directory. <code>--clean-env</code> starts with an empty environment instead of inheriting yours.</p>
|
|
</section>
|
|
|
|
<footer>
|
|
<a href="https://github.com/because/shout">GitHub</a> · <a href="https://www.npmjs.com/package/@because/shout">npm</a>
|
|
</footer>
|
|
|
|
</body>
|
|
</html>
|