# Testing Patterns

**Analysis Date:** 2026-03-28

## Test Framework

**Runner:** None

No test framework, test files, or test configuration exist in this codebase. There are no unit tests, integration tests, or end-to-end tests.

## Test File Organization

**Location:** No test files exist anywhere in the project.

**Naming:** No convention established.

## Current Testing Approach

Testing is entirely manual. The skill is tested by:
1. Installing to `~/.claude/skills/owl/` (per `docs/DEPLOY.md`)
2. Running Claude Code sessions that exercise owl commands
3. Observing behavior of `owl.sh` subcommands interactively

## What Should Be Tested

**`owl.sh` subcommands (high priority):**
- `setup` -- creates perch directory structure, writes ready file
- `poll` -- blocks until message arrives, prints and deletes it
- `poll --setup` -- combines setup + poll
- `deliver` -- writes message to target inbox, checks alive
- `reply` -- writes message to sender inbox, checks alive
- `send` -- creates ephemeral perch, delivers, polls for reply, cleans up
- `list` -- enumerates active owls, cleans stale ones
- `stop` -- removes perch files; `--all` removes entire owlery

**Helper functions (medium priority):**
- `_get_pid()` -- extracts PID from info.json
- `_check_alive()` -- validates target perch exists and PID is live
- `_write_msg()` -- writes correctly formatted message file
- `_poll_once()` -- filesystem polling loop

**Edge cases (high priority):**
- Stale PID cleanup in `list`
- Self-send prevention (documented in SKILL.md but enforced only at the prompt layer, not in `owl.sh`)
- Race conditions with concurrent message delivery
- Cleanup of ephemeral perch in `send` after poll completes

## Recommended Test Approach

Since this is a pure bash script with no external dependencies (only bash + coreutils), tests could use:

**Option 1: Bash-native tests**
```bash
#!/usr/bin/env bash
# test_owl.sh

OWLERY=$(mktemp -d)
export HOME=$(mktemp -d)
mkdir -p "$HOME/.claude/owlery"

# Test setup creates perch
output=$(bash owl.sh setup testid)
[ "$output" = "READY:testid" ] || echo "FAIL: setup output"
[ -f "$HOME/.claude/owlery/testid/ready" ] || echo "FAIL: ready file"
[ -d "$HOME/.claude/owlery/testid/inbox" ] || echo "FAIL: inbox dir"
```

**Option 2: BATS (Bash Automated Testing System)**
```bash
@test "setup creates perch with ready file" {
  run bash owl.sh setup testid
  [ "$status" -eq 0 ]
  [ "$output" = "READY:testid" ]
  [ -f "$OWLERY/testid/ready" ]
}
```

**Key considerations:**
- `_poll_once()` blocks indefinitely, so tests must either background the poll or use timeouts
- Tests should use a temp directory for `OWLERY` to avoid polluting real owlery
- The `OWLERY` variable is hardcoded to `$HOME/.claude/owlery` at line 5 of `owl.sh` -- making it configurable via env var would simplify testing

## Coverage

**Requirements:** None enforced

**Current coverage:** 0% -- no automated tests exist

## CI/CD

**Pipeline:** None

No `.github/workflows/`, `.gitlab-ci.yml`, `Makefile`, or any CI configuration exists. Deployment is manual per `docs/DEPLOY.md`.

## Linting

**ShellCheck:** Not configured, but `owl.sh` would benefit from ShellCheck static analysis. No `.shellcheckrc` file present.

---

*Testing analysis: 2026-03-28*