Docs Testing

Testing Guide

Smoke tests, functional workflows, and environment requirements for every piex package.

Smoke first

Every package loads with pi -e … -p "what is 1+1" --no-session before functional checks.

Smoke tests

Each package can be loaded alone via pi -e:

bash

cd piex

# Load test (extension must not throw)
pi -e ./extensions/hashline/src/hashline.ts -p "what is 1+1" --no-session
pi -e ./extensions/dap/src/dap.ts       -p "what is 1+1" --no-session
pi -e ./extensions/lsp/src/lsp.ts       -p "what is 1+1" --no-session
pi -e ./extensions/plan/src/plan.ts     -p "what is 1+1" --no-session
pi -e ./extensions/review/src/review.ts  -p "what is 1+1" --no-session
pi -e ./extensions/xai-oauth/src/xai-oauth.ts -p "what is 1+1" --no-session
# init prompt package
pi --prompt-template ./prompts/init/init.md -p "/init" --no-session

# xai-oauth unit tests (offline)
bun test extensions/xai-oauth/test/xai-oauth.test.ts extensions/xai-oauth/test/models.test.ts
cd extensions/lsp && npm install && bun test

Functional tests

hashline

bash

# Create a fixture
echo -e 'hello world\nline 2\nline 3' > /tmp/test.txt

# read → edit workflow
pi -e ./extensions/hashline/src/hashline.ts \
  -p "1. Read /tmp/test.txt 2. Use edit tool to replace 'hello world' with 'hi piex' using hashline SWAP syntax with [PATH#TAG]" \
  --no-session -nc

# Verify
cat /tmp/test.txt

dap

bash

# List debug sessions
pi -e ./extensions/dap/src/dap.ts \
  -p "Use the debug tool with action=sessions" --no-session

# Launch (requires a debug adapter)
pi -e ./extensions/dap/src/dap.ts \
  -p "Use the debug tool: action=launch, program=script.py, adapter=debugpy, timeout=5" --no-session

lsp

bash

# LSP status
pi -e ./extensions/lsp/src/lsp.ts \
  -p "Use the lsp tool with action=status" --no-session

# Diagnostics (requires matching LSP server)
pi -e ./extensions/lsp/src/lsp.ts \
  -p "Use the lsp tool with action=diagnostics, file=README.md" --no-session

plan

bash

# Interactive (TUI)
pi -e ./extensions/plan/src/plan.ts

# Then type /plan to enter plan mode

review

bash

# review tool with no changes
pi -e ./extensions/review/src/review.ts \
  -p "Use the review tool with action=diff" --no-session

# Interactive
pi -e ./extensions/review/src/review.ts
# Type /review for the review menu

init

bash

# Load prompt without writing settings
pi --prompt-template ./prompts/init/init.md
# Or after install:
pi install -l prompts/init
pi -p "/init" --no-session

Environment requirements

Package	Runtime	Extra tools
hashline	Node.js ≥ 18 or Bun ≥ 1.3.14	none
dap	Node.js ≥ 18	debug adapter (e.g. debugpy, gdb)
lsp	Node.js ≥ 18	LSP server (e.g. marksman, ts-ls)
plan	Node.js ≥ 18	none
review	Node.js ≥ 18	git
init	any (prompt resources only)	none

Bun

Under Bun, hashline uses native Bun APIs (no polyfill):

bash

bun run pi -e ./extensions/hashline/src/hashline.ts -p "hi" --no-session

Source Markdown: docs/testing.md