v0.1.0 installation walkthrough#

This protocol starts from the published binary, not a checkout build. Use a fresh directory. Playtestr installs no service or global configuration.

Download and verify#

Open the v0.1.0 release and download the archive and adjacent .sha256 for exactly one supported host.

Linux:

sha256sum --check playtestr_0.1.0_linux_amd64.tar.gz.sha256
tar -xzf playtestr_0.1.0_linux_amd64.tar.gz
./playtestr_0.1.0_linux_amd64/playtestr --version

macOS:

expected=$(awk '{print $1}' playtestr_0.1.0_darwin_arm64.tar.gz.sha256)
actual=$(shasum -a 256 playtestr_0.1.0_darwin_arm64.tar.gz | awk '{print $1}')
test "$actual" = "$expected"
tar -xzf playtestr_0.1.0_darwin_arm64.tar.gz
./playtestr_0.1.0_darwin_arm64/playtestr --version

Windows PowerShell:

$archive = 'playtestr_0.1.0_windows_amd64.zip'
$expected = (Get-Content "$archive.sha256").Split()[0]
$actual = (Get-FileHash $archive -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw 'Playtestr archive checksum mismatch' }
Expand-Archive $archive -DestinationPath .
& '.\playtestr_0.1.0_windows_amd64\playtestr.exe' --version

Stop if the checksum differs. The version command must print playtestr v0.1.0. The standalone runner does not require Go; the application you test and its runtime are separate prerequisites.

Run a first test#

Create a directory named playtestr first test. On Linux or macOS, create an executable hello.sh:

#!/bin/sh
printf 'Name: '
IFS= read -r name
printf 'Hello, %s!\n' "$name"

Make it executable:

chmod +x hello.sh

Create hello.json beside it:

{
  "version": 1,
  "name": "shell greeting",
  "command": ["./hello.sh"],
  "steps": [
    {"expect": "Name:"},
    {"text": "terminal tester"},
    {"key": "Enter"},
    {"expect": "Hello, terminal tester!"},
    {"exit": 0}
  ]
}

On Windows, create hello.cmd:

@echo off
set /p "name=Name: "
echo Hello, %name%!

Use this Windows hello.json:

{
  "version": 1,
  "name": "Windows command greeting",
  "command": ["cmd.exe", "/d", "/s", "/c", "hello.cmd"],
  "steps": [
    {"expect": "Name:"},
    {"text": "terminal tester"},
    {"key": "Enter"},
    {"expect": "Hello, terminal tester!"},
    {"exit": 0}
  ]
}

Run the extracted binary by its path, or temporarily add its directory to PATH, then run:

playtestr test --report results.json hello.json

Expected: exit 0, five passing steps, and summary.passed equal to 1.

Prove failure and recovery#

Change the final expectation to Hello, wrong! and rerun. Expected: exit 1, a failed report, and hello.json.actual.txt. Because this short target exits before a match, the category can be unexpected_exit; a still-running target normally reaches assertion_timeout.

Restore the correct expectation and rerun. Expected: exit 0 and a passing report without an evidence reference. The old adjacent screen file can remain as historical evidence; inspect it for sensitive application output, then remove it explicitly. Do not infer the current result from an old artifact.

Change the command temporarily to playtestr-target-does-not-exist. Expected: exit 1 and launch_failure. If the report destination is a directory, expected: exit 1 and FAIL write report: without a claim that the report was saved.

For a trusted target that remains open, pressing Ctrl+C once should cancel the active spec, stop its managed process tree, write a cancelled report when requested, and exit 130. Do not use a production service for this check.

Remove only the archive, checksum, extracted version directory, and first-test directory you created. Review any screen/diff evidence before sharing it. For a problem, follow the sanitized report checklist in SUPPORT.md .

View source ↗ · Suggest an edit ↗