425 lines
12 KiB
HTML
425 lines
12 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: #000;
|
|
--green: #1a7f37;
|
|
--red: #cf222e;
|
|
--dim: #888;
|
|
--accent: #1a7f37;
|
|
--code-bg: #f5f5f5;
|
|
--border: #ddd;
|
|
--yellow: #9a7200;
|
|
--install-bg: #f0faf2;
|
|
--install-border: #c5e4cc;
|
|
}
|
|
|
|
@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;
|
|
--yellow: #e5b567;
|
|
--install-bg: #0d1a10;
|
|
--install-border: #1a3d20;
|
|
}
|
|
}
|
|
|
|
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 24px;
|
|
max-width: 900px;
|
|
margin: 0 auto;
|
|
-webkit-font-smoothing: antialiased;
|
|
}
|
|
|
|
/* ---- Hero ---- */
|
|
header {
|
|
padding: 64px 0 0;
|
|
}
|
|
|
|
h1 {
|
|
font-size: 64px;
|
|
font-weight: 800;
|
|
color: var(--bright);
|
|
letter-spacing: -0.04em;
|
|
line-height: 1;
|
|
display: flex;
|
|
align-items: baseline;
|
|
vertical-align: baseline;
|
|
}
|
|
|
|
h1 .dollar {
|
|
color: var(--accent);
|
|
margin-right: 10px;
|
|
}
|
|
|
|
|
|
.subtitle {
|
|
font-size: 20px;
|
|
color: var(--dim);
|
|
margin-top: 8px;
|
|
font-weight: 400;
|
|
}
|
|
|
|
/* ---- Install ---- */
|
|
.install {
|
|
margin-top: 32px;
|
|
display: flex;
|
|
align-items: center;
|
|
justify-content: space-between;
|
|
background: var(--install-bg);
|
|
border: 1px solid var(--install-border);
|
|
padding: 11px 11px 11px 19px;
|
|
border-radius: 8px;
|
|
font-size: 14px;
|
|
color: var(--bright);
|
|
}
|
|
|
|
.install code {
|
|
white-space: nowrap;
|
|
overflow: hidden;
|
|
text-overflow: ellipsis;
|
|
}
|
|
|
|
.install .prompt { color: var(--dim); }
|
|
.install .cmd { color: var(--bright); }
|
|
|
|
.copy-btn {
|
|
background: var(--accent);
|
|
color: #fff;
|
|
border: none;
|
|
padding: 7px 14px;
|
|
border-radius: 5px;
|
|
font-family: inherit;
|
|
font-size: 12px;
|
|
font-weight: 600;
|
|
cursor: pointer;
|
|
white-space: nowrap;
|
|
transition: opacity 0.15s;
|
|
flex-shrink: 0;
|
|
margin-left: 16px;
|
|
}
|
|
|
|
@media (prefers-color-scheme: dark) {
|
|
.copy-btn { color: #0a0a0a; }
|
|
}
|
|
|
|
.copy-btn:hover {
|
|
opacity: 0.85;
|
|
}
|
|
|
|
/* ---- Section boxes ---- */
|
|
.section-box {
|
|
background: var(--code-bg);
|
|
border: 1px solid var(--border);
|
|
border-radius: 8px;
|
|
padding: 20px;
|
|
padding-top: 16px;
|
|
margin-bottom: 24px;
|
|
}
|
|
|
|
.two-col {
|
|
display: grid;
|
|
grid-template-columns: 1fr 1.4fr;
|
|
gap: 32px;
|
|
align-items: start;
|
|
}
|
|
|
|
.two-col .explain h2 {
|
|
margin-bottom: 16px;
|
|
}
|
|
|
|
.two-col .explain p {
|
|
margin-bottom: 14px;
|
|
font-size: 15px;
|
|
}
|
|
|
|
.two-col .explain .feature {
|
|
margin-bottom: 11px;
|
|
font-size: 14px;
|
|
}
|
|
|
|
.two-col .explain .feature code {
|
|
padding: 2px 0px;
|
|
border-radius: 3px;
|
|
font-size: 13px;
|
|
}
|
|
|
|
.section-box pre {
|
|
background: var(--bg);
|
|
margin-bottom: 0;
|
|
}
|
|
|
|
.section-box pre + pre {
|
|
margin-top: 12px;
|
|
}
|
|
|
|
.section-box p:last-child {
|
|
margin-bottom: 0;
|
|
}
|
|
|
|
@media (max-width: 680px) {
|
|
.two-col {
|
|
grid-template-columns: 1fr;
|
|
gap: 24px;
|
|
}
|
|
.section-box {
|
|
padding: 19px;
|
|
}
|
|
}
|
|
|
|
h2 {
|
|
font-size: 13px;
|
|
font-weight: 600;
|
|
color: var(--fg);
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.1em;
|
|
margin-bottom: 16px;
|
|
}
|
|
|
|
|
|
section {
|
|
padding: 0 0 32px 0;
|
|
}
|
|
|
|
p {
|
|
margin-bottom: 16px;
|
|
font-size: 15px;
|
|
}
|
|
|
|
.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: 6px;
|
|
padding: 19px 22px;
|
|
overflow-x: auto;
|
|
font-size: 13px;
|
|
line-height: 1.7;
|
|
margin-bottom: 24px;
|
|
}
|
|
|
|
pre code {
|
|
color: var(--fg);
|
|
}
|
|
|
|
.prompt { color: var(--yellow); }
|
|
.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: 48px 0;
|
|
border-top: 1px solid var(--border);
|
|
color: var(--dim);
|
|
font-size: 13px;
|
|
}
|
|
|
|
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: 40px 0 0; }
|
|
h1 { font-size: 44px; }
|
|
.subtitle { font-size: 16px; }
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<header>
|
|
<h1><span class="dollar">$</span>shout</h1>
|
|
<p class="subtitle">shell output tester</p>
|
|
<div class="install">
|
|
<code><span class="prompt">$</span> <span class="cmd">curl -fsSL https://because.sh/shout | sh</span></code>
|
|
<button class="copy-btn" onclick="copyInstall(this)">Copy</button>
|
|
</div>
|
|
</header>
|
|
|
|
<div style="padding: 40px 0 0;">
|
|
<div class="section-box">
|
|
<div class="two-col">
|
|
<div class="explain">
|
|
<h2>✓ Write a test</h2>
|
|
<p>Each <code class="bright">.shout</code> file is a session.</p>
|
|
<p class="feature">Commands start with <code class="prompt">$</code>.</p>
|
|
<p class="feature">Everything else is expected output.</p>
|
|
<p class="feature"><code class="wildcard">...</code> matches anything — inline or across lines.</p>
|
|
<p class="feature"><code class="exit-code">[1]</code> asserts the exit code. Default expects 0.</p>
|
|
<p class="feature">Lines starting with <code class="dim">#</code> are comments.</p>
|
|
<p class="feature">(<code class="dim">\#</code> matches output starting with <code class="dim">#</code>.)</p>
|
|
</div>
|
|
<div class="example">
|
|
<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>
|
|
|
|
<span class="comment"># start the server</span>
|
|
<span class="prompt">$</span> <span class="cmd">my-server &</span>
|
|
<span class="prompt">$</span> <span class="cmd">curl localhost:8080</span>
|
|
<span class="output">OK</span></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section-box">
|
|
<div class="two-col">
|
|
<div class="explain">
|
|
<h2>✓ Setup & teardown</h2>
|
|
<p>Use <code class="bright">@setup</code> to share commands across test files.</p>
|
|
<p>Use <code class="bright">@teardown</code> to clean up after tests — it runs regardless of pass/fail.</p>
|
|
<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>
|
|
</div>
|
|
<div class="example">
|
|
<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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section-box">
|
|
<div class="two-col">
|
|
<div class="explain">
|
|
<h2>✓ Macros</h2>
|
|
<p>Use <code class="bright">@def</code> to define reusable command macros.</p>
|
|
<p>If a command matches a macro name exactly, the body is substituted. Use <code>\</code> for multi-line bodies. Macros from setup files are inherited; user-file macros override them.</p>
|
|
</div>
|
|
<div class="example">
|
|
<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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section-box">
|
|
<div class="two-col">
|
|
<div class="explain">
|
|
<h2>✓ Run it</h2>
|
|
<p>Each file gets a fresh temp directory and its own <code>/bin/sh</code> session. State carries between commands within a file.</p>
|
|
</div>
|
|
<div class="example">
|
|
<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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section-box">
|
|
<div class="two-col">
|
|
<div class="explain">
|
|
<h2>✓ Update expectations</h2>
|
|
<p>Rewrites your <code>.shout</code> files with the actual output. No more copy-pasting from the terminal.</p>
|
|
</div>
|
|
<div class="example">
|
|
<pre><code><span class="prompt">$</span> <span class="cmd">shout test --update</span></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<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>
|
|
|
|
<script>
|
|
function copyInstall(btn) {
|
|
navigator.clipboard.writeText('curl -fsSL https://because.sh/shout | sh');
|
|
btn.textContent = 'Copied!';
|
|
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
|
|
}
|
|
</script>
|
|
|
|
</body>
|
|
</html>
|