shellwright-testing

Shellwright Testing

This skill covers using the shellwright MCP tools (shell_start, shell_send, shell_read, shell_stop, shell_screenshot) to launch and test LlamaOfFate programs interactively.

Tool Behavior

read vs send

• shell_read returns the current terminal buffer instantly. Use it to poll for output. No delay needed.
• shell_send sends input and returns bufferBefore/bufferAfter. Use it only when sending actual input (commands, text). Do NOT send empty strings to poll — use read instead.
• The delay_ms on send controls how long to wait after sending before capturing bufferAfter. If bufferAfter doesn't show the expected output, the app may still be processing — follow up with read.

Delay Guidelines for send

For LLM calls, send with a short delay (200ms) then poll with read until the input prompt reappears. Do not use large delays on send — the tool does not return early.

Completion Detection

Check for the app's input prompt at the end of the read buffer to know when the app is ready for the next command:

Terminal Sizing

Use cols: 120, rows: 50 to minimize scrolling artifacts in the buffer.

Launching Programs

Launch directly via shell_start with the binary as command and flags as args — no bash wrapper needed. This keeps the buffer clean (no shell prompt noise).

shell_start(command="./bin/llamaoffate", args=[], cols=120, rows=50)
shell_start(command="./bin/llm-scene-loop", args=["-scene", "saloon", "-log", ""], cols=120, rows=50)
shell_start(command="./bin/scenario-generator", args=["-name", "Test", "-concept", "Warrior"], cols=120, rows=50)

CWD defaults to the workspace root, so relative paths to ./bin/ and configs/ work.

Use -log "" on programs that support it to disable session log file creation during testing.

Building

No justfile targets exist for examples. Build manually:

go build -o ./bin/llamaoffate ./cmd/cli
go build -o ./bin/llm-scene-loop ./examples/llm-scene-loop
go build -o ./bin/scenario-generator ./examples/scenario-generator
go build -o ./bin/scenario-walkthrough ./examples/scenario-walkthrough
go build -o ./bin/scene-generator ./examples/scene-generator

All programs require an LLM config file (e.g., configs/azure-llm.yaml or configs/ollama-llm.yaml) for LLM access.

Program Inventory

Testing Patterns

Batch Programs (scenario-generator, scene-generator)

1. shell_start(command="./bin/scenario-generator", args=["-name", "Test", "-concept", "Warrior", "-log", ""])
2. read — output is already in the buffer (LLM call may take time; poll with read until complete)
3. Verify expected content in output
4. shell_stop

Interactive Programs (llamaoffate, llm-scene-loop, scenario-walkthrough)

1. shell_start(command="./bin/llm-scene-loop", args=["-scene", "saloon", "-log", ""])
2. read — confirm startup, look for > prompt
3. send("help\r", delay_ms=200) — test built-in commands, check bufferAfter
4. send("I look around\r", delay_ms=200) — for LLM input, then poll with read until > reappears
5. send("exit\r", delay_ms=200) — end the session
6. shell_stop

Screenshots

Use shell_screenshot to capture terminal state as PNG when visual verification is needed. Primarily useful for debugging buffer issues or documenting behavior.