<!--
  canonical-url: https://www.avonture.be/blog/ollama-test-generator
  published:     2026-08-03
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# ai-test: Generate Missing Unit Tests From Your Terminal With a Local LLM

> Turn your local Ollama model into an on-demand unit test generator. A zsh function that reads a Bash, PHP or Python file, detects whether you already have tests for it, prints only the missing Bats/Pest/Pytest cases needed for full coverage, offers to save them where the framework expects them, and runs the suite in a throw-away Docker container.

---
![ai-test: Generate Missing Unit Tests From Your Terminal With a Local LLM](/img/v2/ai_test.webp)

**TL;DR**

`ai-test` turns your local Ollama model into an on-demand unit test generator. Point it at a Bash, PHP or Python file, review the generated tests, save them if you like, then run them immediately in Docker — all without leaving your terminal. It supports Bats (Bash), Pest (PHP) and Pytest (Python).

This article opens the **[Ollama daily use](/series/ollama-daily-use)** series: small tools that turn a local LLM into a practical terminal companion instead of another browser tab.

Let's stop pretending: we all know unit tests are necessary, and almost nobody enjoys writing them. There's always an excuse — a tight deadline, a Bash script that was only supposed to be temporary, the sheer tedium of mocking dependencies. We promise ourselves we'll add them later, and *later* is the moment the technical debt explodes in production.

`ai-test` does the grunt work instead. Point it at a file, get a Bats, Pest or Pytest suite back, read it, save it, run it — all from the terminal, all on your machine.

**Quick Jump:** [What ai-test Does For You](#what-ai-test-does-for-you) | [Installing It](#installing-it)

## What `ai-test` Does For You

Take `greet.sh`, a small script that asks for a name and a language. One command, and a full Bats suite comes back — trimmed to three tests below, the real run produced more than fifteen:

```bash
$ ai-test greet.sh

→ No test file found for 'greet' — generating a full Bats suite.

setup() {
  source "$BATS_TEST_DIRNAME/../greet.sh"
}

@test "happy path: greets in English by default" {
  run greet "Christophe"
  [ "$status" -eq 0 ]
  [ "$output" = "Hello Christophe!" ]
}

@test "happy path: greets in French" {
  run greet "Christophe" "fr"
  [ "$status" -eq 0 ]
  [ "$output" = "Bonjour Christophe !" ]
}

@test "happy path: greets in Dutch" {
  run greet "Christophe" "nl"
  [ "$status" -eq 0 ]
  [ "$output" = "Hallo Christophe!" ]
}

→ Save this suite as tests/greet.bats? [y/N] y
→ Written to tests/greet.bats
→ Run the suite now, in Docker? [y/N] y

1..3
ok 1 happy path: greets in English by default
ok 2 happy path: greets in French
ok 3 happy path: greets in Dutch
```

That's the whole pitch: one command, a suite you can read in a minute, two confirmations, and a green run telling you it isn't decorative. Nothing was installed to run those tests, and nothing left the machine.

## Why It Works

Four ideas, and none of them require you to read a line of zsh yet:

* **The extension decides everything** — framework, naming convention, and where the file lands.
* **The prompt carries your project layout.** The model never sees a path, only a blob of text; `ai-test` computes the destination first, then dictates how the suite must load the code.
* **It reads the tests you already have** and asks for the gaps only, appended to the existing file.
* **It validates in a throw-away container**, so a suite that *looks* right has to prove it *passes*.

## Installing It

Two files to drop into `~/.zsh/fns/`, one new shell. First, the one hard dependency — `jq`, used to build the JSON payload sent to Ollama:

Prerequisite: jq

```bash
$ sudo apt update && sudo apt install jq -y

Reading package lists... Done
Building dependency tree... Done
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
```

Verify:

```bash
$ jq --version

jq-1.7
```

You also need Ollama running somewhere reachable — I've covered [installing it](/blog/ollama-installation) and [exposing it across my network](/blog/accessing-ollama-across-your-local-network) before; mine sits idle most of the day, so why not point it at the one task I keep postponing?

**Two optional tools: bat and docker (click if you want the details)**

**`bat`** — if [it](https://github.com/sharkdp/bat) is installed, the generated code is syntax-highlighted before it hits your terminal. If not, `ai-test` falls back to plain output. Watch out for one Debian/Ubuntu quirk: the `bat` name was already taken by `bacula-console-qt`, so `apt install bat` installs the binary as **`batcat`**. That's why the `_ai_bat` helper probes both spellings instead of hard-coding `bat`.

Prerequisite: bat

```bash
$ sudo apt install bat
```

Verify:

```bash
$ batcat --version
bat 0.24.0
```

**`docker`** — only needed for the "run the suite now" step at the very end. `ai-test` skips that step with a message when `docker` isn't on your `PATH`.

Prerequisite: docker

```bash
$ sudo apt install docker
```

Verify:

```bash
$ docker --version
Docker version 29.6.2, build dfc4efb
```

Now the two files. `_ollama.zsh` holds everything the series shares — the query helper, the command registry, and the `ai` entry point — while `ai-test.zsh` is the function itself:

**Project: \~/.zsh/fns**

**\_ollama.zsh**

````bash
# Foundation file for every "ai-*" function in this series. Named with a
# leading underscore: the ~/.zsh/fns/*.zsh loader sources files in
# alphabetical order, and "_" sorts before any letter — so this file is
# always loaded first, no matter how many ai-* functions get added later.
#
# Provides:
#   - _ollama_check       reachability guard for Ollama
#   - _ollama_query       shared HTTP client (curl + jq)
#   - _ai_strip_fences    removes the Markdown fences models add anyway
#   - _ai_bat             resolves "bat" vs Debian's "batcat"
#   - _ai_confirm         yes/no prompt
#   - _git_staged_diff    validated staged-diff fetcher (shared by pre-commit functions)
#   - AI_COMMANDS         registry each ai-* function adds itself to
#   - AI_PARAMS           registry of interactive parameter types (file/language/number/text/none)
#   - _ai_prompt_*        FZF/read helpers for interactive argument collection
#   - ai                  entry-point dispatcher / interactive menu

typeset -gA AI_COMMANDS
typeset -gA AI_PARAMS

# ---------------------------------------------------------------------------
# Ollama helpers
# ---------------------------------------------------------------------------

# _ollama_check — verify that the Ollama daemon is reachable.
# Fails loudly so callers can bail early rather than watching curl hang.
_ollama_check() {
  local host="${OLLAMA_HOST:-http://localhost:11434}"
  if ! curl --silent --max-time 2 "${host}/api/tags" >/dev/null 2>&1; then
    echo "ollama: cannot reach ${host} — is the Ollama container running?" >&2
    return 1
  fi
}

# _ollama_query <prompt> — send a prompt to the local model and print the response.
# Assumes Ollama is reachable; call _ollama_check first if you need an early guard.
_ollama_query() {
  local prompt="$1"
  local model="${OLLAMA_MODEL:-qwen3-coder:30b}"
  local host="${OLLAMA_HOST:-http://localhost:11434}"

  _ollama_check || return 1

  # The prompt is piped into jq rather than passed with "--arg": Linux caps a
  # single argv entry at 128 KB (MAX_ARG_STRLEN), and a large staged diff or a
  # long source file sails straight through that ceiling — jq then dies with
  # "argument list too long". "-R -s" slurps stdin as one raw string, which jq
  # escapes exactly like --arg would.
  print -r -- "$prompt" \
    | jq -Rs --arg model "$model" '{model: $model, prompt: ., stream: false}' \
    | curl --silent "${host}/api/generate" --data-binary @- \
    | jq -r '.response // empty'
}

# ---------------------------------------------------------------------------
# Output helpers
# ---------------------------------------------------------------------------

# _ai_strip_fences <text> — return only the code, without the Markdown fences.
#
# Every prompt in this series ends with "no markdown fences" and models still
# wrap their answer in ```language … ``` often enough that the output can't be
# piped or pasted as-is. When at least one fence is present, only the fenced
# regions are kept (which also drops the "Here is your test suite:" preamble);
# when there is none, the text is returned untouched.
_ai_strip_fences() {
  local text="$1"

  if [[ "$text" != *'```'* ]]; then
    print -r -- "$text"
    return 0
  fi

  print -r -- "$text" | awk '
    /^[[:space:]]*```/ { inside = !inside; next }
    inside             { print }
  '
}

# _ai_bat — print the name of the "bat" binary installed on this machine, if any.
# Debian and Ubuntu ship the package as "batcat" because the "bat" name was
# already taken by bacula-console-qt, so both spellings have to be probed.
_ai_bat() {
  local candidate
  for candidate in bat batcat; do
    if command -v "$candidate" >/dev/null 2>&1; then
      print -- "$candidate"
      return 0
    fi
  done
  return 1
}

# _ai_relpath <path> — print <path> relative to the current folder when it sits
# below it. Purely cosmetic: it keeps prompts readable instead of asking
# "Save as /home/christophe/projects/…/tests/backup.bats?".
_ai_relpath() {
  local path="${1:A}"
  print -- "${path#${PWD}/}"
}

# _ai_confirm <question> — ask a yes/no question; return 0 only on an explicit yes.
_ai_confirm() {
  local answer
  print -n "${1} [y/N] "
  read -r answer
  [[ "$answer" == [yY]* ]]
}

# ---------------------------------------------------------------------------
# Git helpers
# ---------------------------------------------------------------------------

# _git_staged_diff <caller> — validate the git context and return the staged diff.
# Handles three early-exit cases (not a repo, nothing staged, oversized diff)
# so every pre-commit function gets them for free without repeating the guards.
#
# Past AI_DIFF_MAX_CHARS the full diff is *not* returned: a diff of several
# hundred kilobytes overflows the model's context window, and the answer that
# comes back is worse than the one you get from a summary. The fallback keeps
# the shape of the change — per-file stat, plus the file and hunk headers,
# which carry the enclosing function names git puts after each "@@" — and
# drops the line-by-line content.
_git_staged_diff() {
  local caller="${1:-ai}"
  local max="${AI_DIFF_MAX_CHARS:-12000}"

  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
    echo "${caller}: not inside a git repository" >&2
    return 1
  fi

  local diff
  diff=$(git diff --staged)

  if [[ -z "$diff" ]]; then
    echo "${caller}: nothing staged — run 'git add' first" >&2
    return 1
  fi

  # "print -r" everywhere below: without it, print expands escape sequences and
  # a literal \n or \t inside the diff would come back mangled.
  if (( ${#diff} <= max )); then
    print -r -- "$diff"
    return 0
  fi

  echo "${caller}: staged diff is large (${#diff} chars) — sending a structural summary instead of the full diff. Commit in smaller chunks for a more precise answer." >&2

  local summary
  summary="$(git diff --staged --stat)

--- FILE AND HUNK HEADERS ONLY (full diff omitted, ${#diff} chars) ---
$(print -r -- "$diff" | grep -E '^(diff --git|new file|deleted file|rename (from|to)|@@)')"

  # Even the summary can exceed the ceiling on a very wide change.
  if (( ${#summary} > max )); then
    summary="${summary[1,$max]}
[…summary truncated…]"
  fi

  print -r -- "$summary"
}

# ---------------------------------------------------------------------------
# Interactive argument helpers (used by the ai() dispatcher)
# ---------------------------------------------------------------------------

# _ai_prompt_file [label] — open an fzf file picker; print the chosen path.
_ai_prompt_file() {
  local label="${1:-Select a file:}"
  local bat_bin preview='cat {}'
  bat_bin=$(_ai_bat) && preview="${bat_bin} --color=always {} 2>/dev/null || cat {}"

  if command -v fd >/dev/null 2>&1; then
    fd --type f | fzf --prompt="${label} " --height=50% --reverse --preview="$preview"
  else
    find . -type f | fzf --prompt="${label} " --height=50% --reverse --preview="$preview"
  fi
}

# _ai_prompt_language — open an fzf language picker; print the chosen language.
_ai_prompt_language() {
  printf '%s\n' English French Dutch German Spanish Italian Portuguese Japanese Chinese Korean \
    | fzf --prompt='Target language: ' --height=40% --reverse
}

# _ai_prompt_number [label] — read a positive integer; print it (or nothing on Enter, which
# lets the caller fall back to its own default). Returns 1 only on invalid input.
_ai_prompt_number() {
  local label="${1:-Number (Enter for default):}"
  print -n "${label} "
  local n
  read n
  if [[ -z "$n" ]]; then
    return 0
  fi
  if [[ ! "$n" =~ ^[1-9][0-9]*$ ]]; then
    echo "Expected a positive integer." >&2
    return 1
  fi
  print -- "$n"
}

# _ai_prompt_text [label] — read a free-form string; print it. Returns 1 if empty.
_ai_prompt_text() {
  local label="${1:-Input:}"
  print -n "${label} "
  local t
  read t
  if [[ -z "$t" ]]; then
    echo "No input given." >&2
    return 1
  fi
  print -- "$t"
}

# ---------------------------------------------------------------------------
# Entry-point dispatcher
# ---------------------------------------------------------------------------

# ai              → interactive fzf menu of every registered ai-* command
# ai <cmd> [args] → dispatch straight to ai-<cmd> [args]
#
# When opened via the fzf menu, each command's declared AI_PARAMS type triggers
# a secondary picker before the command runs:
#   file     → fzf file picker (fd + preview if available)
#   language → fzf language list
#   number   → read prompt, empty input uses the command's own default
#   text     → read prompt, required
#   none     → run the command directly (it collects its own input)
# Space-separated values declare multiple parameters in order, e.g. "file language".
ai() {
  local cmd="$1"

  # Direct dispatch: ai <cmd> [args]
  if [[ -n "$cmd" && "$cmd" != "help" && "$cmd" != "list" ]]; then
    if (( ${+AI_COMMANDS[$cmd]} )); then
      shift
      "ai-${cmd}" "$@"
      return
    fi
    echo "ai: unknown command '${cmd}'" >&2
    echo >&2
  fi

  # Interactive menu
  if ! command -v fzf >/dev/null 2>&1; then
    echo "Available ai commands:"
    for key in ${(ok)AI_COMMANDS}; do
      printf "  ai %-10s %s\n" "$key" "$AI_COMMANDS[$key]"
    done
    return
  fi

  local picked
  picked=$(
    for key in ${(ok)AI_COMMANDS}; do
      printf '%s\t%s\n' "$key" "$AI_COMMANDS[$key]"
    done \
      | fzf --delimiter='\t' --with-nth=2 --prompt='ai > ' --height=40% --reverse \
      | cut -f1
  )
  [[ -z "$picked" ]] && return

  # Collect arguments interactively based on AI_PARAMS declaration
  local -a args=()
  local param_type
  for param_type in ${(s: :)${AI_PARAMS[$picked]:-none}}; do
    case "$param_type" in
      file)
        local f
        f=$(_ai_prompt_file "File for ai-${picked}:") || return 1
        args+=("$f")
        ;;
      language)
        local l
        l=$(_ai_prompt_language) || return 1
        args+=("$l")
        ;;
      number)
        local n
        n=$(_ai_prompt_number) || return 1
        [[ -n "$n" ]] && args+=("$n")
        ;;
      text)
        local t
        t=$(_ai_prompt_text) || return 1
        args+=("$t")
        ;;
      none) ;;
    esac
  done

  "ai-${picked}" "${args[@]}"
}
````

**ai-test.zsh**

```bash
# ai-test <file> — generate (or complete) a unit test suite for a script using
# a local LLM. Detects Bash/PHP/Python from the extension, looks for an
# existing test file using each ecosystem's naming convention, and asks the
# model to either write a full suite or fill the coverage gaps only.
#
# The result is printed first, then offered for saving at the path its
# ecosystem expects, then optionally run inside a throw-away Docker container
# so no test runner has to be installed on the host.

AI_COMMANDS[test]="ai-test <file.sh|.php|.py>  — generate or complete a unit test suite"
AI_PARAMS[test]="file"

# Images used to run the generated suites. Overridable from ~/.zshrc.
: ${AI_TEST_BATS_IMAGE:=bats/bats:latest}
: ${AI_TEST_PHP_IMAGE:=php:8.4-cli}
: ${AI_TEST_PY_IMAGE:=python:3.14-slim}

# _ai_project_root <dir> <marker...> — walk up from <dir> until a folder
# containing one of the markers is found; print it, or <dir> when none matches.
# This is what keeps "src/Backup.php" from proposing "src/tests/…".
_ai_project_root() {
  local dir="${1:A}"
  shift
  local candidate="$dir" marker
  while [[ "$candidate" != "/" ]]; do
    for marker in "$@"; do
      if [[ -e "${candidate}/${marker}" ]]; then
        print -- "$candidate"
        return 0
      fi
    done
    candidate="${candidate:h}"
  done
  print -- "$dir"
}

# _ai_test_root <ext> <dir> — print the folder the "tests/" tree hangs from,
# using the marker file each ecosystem puts at the root of a project.
_ai_test_root() {
  local ext="$1" dir="$2"
  case "$ext" in
    sh|bash) _ai_project_root "$dir" .git ;;
    php)     _ai_project_root "$dir" composer.json .git ;;
    py)      _ai_project_root "$dir" pyproject.toml setup.py .git ;;
  esac
}

# _ai_test_target <ext> <root> <base> — print the conventional path where the
# generated suite belongs, following each ecosystem's own layout:
#   Bats   → tests/<name>.bats
#   Pest   → tests/Unit/<Name>Test.php   (PSR-4 style, next to composer.json)
#   Pytest → tests/test_<name>.py
_ai_test_target() {
  local ext="$1" root="$2" base="$3"
  case "$ext" in
    sh|bash) print -- "${root}/tests/${base}.bats" ;;
    php)     print -- "${root}/tests/Unit/${base}Test.php" ;;
    py)      print -- "${root}/tests/test_${base}.py" ;;
  esac
}

# _ai_relative_to <from_dir> <path> — print <path> as seen from <from_dir>.
# Used to tell the model how the test file will reach the code under test.
_ai_relative_to() {
  local from="${1:A}" to="${2:A}" rel

  if rel=$(realpath --relative-to="$from" "$to" 2>/dev/null); then
    print -- "$rel"
    return 0
  fi

  # Portable fallback: climb until "from" is a prefix of "to", counting the
  # hops as "../" segments.
  local common="$from" up=""
  while [[ "$to" != "${common}/"* && "$common" != "/" ]]; do
    common="${common:h}"
    up="../${up}"
  done
  print -- "${up}${to#${common}/}"
}

# _ai_test_bootstrap <ext> <file> <target> — print the paragraph that tells the
# model how the suite is going to load the code it is testing.
#
# This is the single most important part of the prompt. Without it the model
# writes a technically perfect suite that calls functions nobody ever sourced,
# and every test dies with "command not found" (exit code 127). The model can't
# guess it: it only ever sees the file *contents*, never the layout. Now that
# ai-test knows the exact path the suite will be saved at, it can dictate the
# bootstrap line instead of hoping.
_ai_test_bootstrap() {
  local ext="$1" file="$2" target="$3"
  local rel
  rel=$(_ai_relative_to "${target:h}" "$file")

  case "$ext" in
    sh|bash)
      cat <<EOT

IMPORTANT — the suite will be saved as "$(_ai_relpath "$target")". Bats runs every test in a fresh shell that has NOT loaded the file under test, so the suite MUST begin with a setup() function that sources it, exactly like this:

setup() {
  source "\$BATS_TEST_DIRNAME/${rel}"
}

Without that setup(), every single test fails with "command not found". Use it as written, and put any per-test fixtures after the source line.

Use ONLY plain Bash assertions: [ ... ] or [[ ... ]]. Do NOT use the bats-assert helpers (assert_success, assert_failure, assert_output, refute_output, ...): they come from an optional library that is not loaded here, and every test calling them fails with "command not found".

Do not hard-code any value that depends on the current date. If the code computes something from today's date, compute the expected value the same way inside the test instead of writing a literal.
EOT
      ;;
    py)
      cat <<EOT

IMPORTANT — the suite will be saved as "$(_ai_relpath "$target")" and pytest is run with the project root on PYTHONPATH. Import the module under test directly, with "import ${file:t:r}" or "from ${file:t:r} import ...". Do not manipulate sys.path and do not use relative imports.
EOT
      ;;
    php)
      local namespace class="${file:t:r}"
      namespace=$(grep -m1 -E '^[[:space:]]*namespace[[:space:]]' "$file" 2>/dev/null \
        | sed -E 's/^[[:space:]]*namespace[[:space:]]+//; s/[[:space:]]*;.*$//')
      if [[ -n "$namespace" ]]; then
        cat <<EOT

IMPORTANT — the suite will be saved as "$(_ai_relpath "$target")". The class under test is ${namespace}\\${class} and is autoloaded by Composer, so reference it with a "use ${namespace}\\${class};" statement. Do not require the file manually.
EOT
      else
        cat <<EOT

IMPORTANT — the suite will be saved as "$(_ai_relpath "$target")". The file under test declares no namespace, so load it explicitly with: require_once __DIR__ . '/${rel}';
EOT
      fi
      ;;
  esac
}

# _ai_test_lint_existing <ext> <file> — warn about a suite that is already
# broken before we add anything to it.
#
# The classic one: a Bats file calling assert_success / assert_output without
# ever loading bats-assert. Those helpers are an optional library, so every
# such test dies with "command not found" — and since gap-fill mode asks the
# model to match the existing style, the new cases inherit the breakage.
_ai_test_lint_existing() {
  local ext="$1" file="$2"

  [[ "$ext" == sh || "$ext" == bash ]] || return 0

  if grep -qE '(^|[^[:alnum:]_])(assert|refute)_[a-z]' "$file" 2>/dev/null \
    && ! grep -qE 'load[[:space:]].*bats-(assert|support)' "$file" 2>/dev/null; then
    echo "→ Warning: $(_ai_relpath "$file") calls bats-assert helpers but never loads them." >&2
    echo "  Those tests already fail with 'command not found'; add to setup():" >&2
    echo "    load '/usr/lib/bats/bats-support/load'" >&2
    echo "    load '/usr/lib/bats/bats-assert/load'" >&2
  fi
}

# _ai_test_run <ext> <root> <relative_test_path> — offer to run the suite in a
# disposable container. Nothing is installed on the host and the container is
# removed on exit; only the project folder is mounted.
_ai_test_run() {
  local ext="$1" root="$2" rel="$3"

  if ! command -v docker >/dev/null 2>&1; then
    echo "→ Docker not available — skipping the test run." >&2
    return 0
  fi

  _ai_confirm "→ Run the suite now, in Docker?" || return 0

  case "$ext" in
    sh|bash)
      # The working directory is a scratch folder *inside* the container, not
      # the mounted project. Any test that calls the code under test with a
      # default "current directory" destination then writes its artifacts to a
      # path that disappears with --rm, instead of littering the repository
      # with half-cleaned-up files. Tests that need real files on disk use
      # $BATS_TEST_DIRNAME, which still points into /code.
      docker run --rm --user "$(id -u):$(id -g)" \
        --volume "${root}:/code" --workdir /tmp \
        "$AI_TEST_BATS_IMAGE" "/code/${rel}"
      ;;
    php)
      if [[ ! -x "${root}/vendor/bin/pest" ]]; then
        echo "ai-test: ${root}/vendor/bin/pest not found — run 'composer install' first." >&2
        return 1
      fi
      docker run --rm --user "$(id -u):$(id -g)" \
        --volume "${root}:/code" --workdir /code \
        "$AI_TEST_PHP_IMAGE" vendor/bin/pest "$rel"
      ;;
    py)
      # Runs as root so "pip install" can reach the system site-packages; the
      # two cache flags are what stop it from leaving root-owned folders behind.
      # PYTHONPATH=/code is what makes a plain "import backup" work from
      # tests/test_backup.py, so the suite needs no sys.path gymnastics.
      docker run --rm --env PYTHONDONTWRITEBYTECODE=1 --env PYTHONPATH=/code \
        --volume "${root}:/code" --workdir /code \
        "$AI_TEST_PY_IMAGE" \
        sh -c "pip install --quiet --root-user-action=ignore pytest && pytest -p no:cacheprovider '${rel}'"
      ;;
  esac
}

ai-test() {
  local file="$1"

  if [[ -z "$file" || ! -f "$file" ]]; then
    echo "Usage: ai-test <file.sh|file.php|file.py>" >&2
    return 1
  fi

  local ext="${file:e}"
  local lang framework bat_lang
  case "$ext" in
    sh|bash)  lang="Bash";   framework="Bats";   bat_lang="bash"   ;;
    php)      lang="PHP";    framework="Pest";   bat_lang="php"    ;;
    py)       lang="Python"; framework="Pytest"; bat_lang="python" ;;
    *)
      echo "ai-test: unsupported extension .$ext (expected .sh, .php or .py)" >&2
      return 1
      ;;
  esac

  local dir="${file:h}"
  local base="${file:t:r}"
  local root target
  root=$(_ai_test_root "$ext" "$dir")
  target=$(_ai_test_target "$ext" "$root" "$base")
  local existing=""

  case "$ext" in
    sh|bash)
      existing=$(find "$dir" "$dir/tests" "$root/tests" -maxdepth 2 \
        -iname "${base}.bats" 2>/dev/null | head -1)
      ;;
    php)
      existing=$(find "$dir" "$dir/tests" "$root/tests" -maxdepth 3 \
        -iregex ".*/${base}Test\.php" 2>/dev/null | head -1)
      ;;
    py)
      existing=$(find "$dir" "$dir/tests" "$root/tests" -maxdepth 2 \
        \( -iname "test_${base}.py" -o -iname "${base}_test.py" \) 2>/dev/null | head -1)
      ;;
  esac

  local source_code
  source_code=$(<"$file")

  local prompt
  if [[ -n "$existing" ]]; then
    echo "→ Found existing tests: $(_ai_relpath "$existing") — asking only for the coverage gaps." >&2
    _ai_test_lint_existing "$ext" "$existing"
    local existing_tests
    existing_tests=$(<"$existing")
    prompt="You are a senior $lang test engineer. Below is a source file and its CURRENT $framework test suite. Compare them, identify every function, branch and edge case in the source that is NOT exercised by the current tests, and output ONLY the additional $framework test cases needed to reach 100% coverage. Do not repeat any existing test. Output raw $framework code only — no explanations, no markdown fences.

The new cases are appended to the existing file, so they inherit its setup/fixtures: do not repeat them. Use only constructs and helpers that already appear in the current suite, and do not hard-code any value derived from today's date.

--- SOURCE: $file ---
$source_code

--- EXISTING TESTS: $existing ---
$existing_tests"
  else
    echo "→ No test file found for '$base' — generating a full $framework suite." >&2
    local bootstrap
    bootstrap=$(_ai_test_bootstrap "$ext" "$file" "$target")
    prompt="You are a senior $lang test engineer. Write a complete $framework test suite for the file below: happy path, edge cases, and error conditions. Output raw $framework code only — no explanations, no markdown fences.
${bootstrap}

--- SOURCE: $file ---
$source_code"
  fi

  local result
  result=$(_ollama_query "$prompt") || return 1

  # The prompt says "no markdown fences"; models add them anyway often enough
  # that stripping is the only reliable way to get paste-ready code.
  result=$(_ai_strip_fences "$result")

  if [[ -z "$result" ]]; then
    echo "ai-test: the model returned an empty response." >&2
    return 1
  fi

  local bat_bin
  if bat_bin=$(_ai_bat); then
    print -r -- "$result" \
      | "$bat_bin" --language="$bat_lang" --style=plain --paging=never --color=always
  else
    print -r -- "$result"
  fi

  # --- Save --------------------------------------------------------------
  echo

  local shown
  if [[ -n "$existing" ]]; then
    shown=$(_ai_relpath "$existing")
    _ai_confirm "→ Append these cases to ${shown}?" || { echo "→ Not saved."; return 0; }
    print -r -- "" >> "$existing"
    print -r -- "$result" >> "$existing"
    echo "→ Appended to ${shown}"
    target="$existing"
  else
    shown=$(_ai_relpath "$target")
    if [[ -e "$target" ]]; then
      _ai_confirm "→ ${shown} already exists. Overwrite it?" || { echo "→ Not saved."; return 0; }
    else
      _ai_confirm "→ Save this suite as ${shown}?" || { echo "→ Not saved."; return 0; }
    fi
    mkdir -p "${target:h}"
    print -r -- "$result" > "$target"
    echo "→ Written to ${shown}"
  fi

  # --- Run ---------------------------------------------------------------
  local abs_target="${target:A}"
  _ai_test_run "$ext" "$root" "${abs_target#${root}/}"
}
```

If you already set up the `~/.zsh/fns/` autoloader from [my ripgrep article](/blog/ripgrep), you're done: open a new shell. If not, here's what to add to your existing `~/.zshrc`:

```bash title="~/.zshrc"
export OLLAMA_MODEL="qwen3-coder:30b"       # optional, this is already the default
export AI_TEST_PHP_IMAGE="php:8.4-cli"      # optional, override to match your project's PHP
export AI_TEST_PY_IMAGE="python:3.14-slim"  # optional, same idea for Python

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done
```

The exports go *above* the loop on purpose: the `AI_TEST_*` defaults are applied at source time, so anything you set afterwards would arrive too late.

### One Entry Point: `ai`

Open a new shell and type `ai`, with no argument. Instead of having to remember what you called your functions six months ago, you get an `fzf` picker listing every command that registered itself — today just `test`, tomorrow whatever else the series adds:

![ai-test](./images/ai-test.gif)

Pick one and it runs. If you already know what you want, `ai test greet.sh` dispatches straight to `ai-test` and skips the menu entirely — the two forms are equivalent, one is discoverable and, the other is fast.

> **Read before you trust:**
>
> Generated tests are a draft, not a guarantee — read them like a pull request from a junior contributor. Running the suite proves it *executes*; only reading it proves it *checks* something.

## More Demos

### A Real Script, and the Gaps It Fills

`greet.sh` was a warm-up. `backup.sh` is a different beast — an external command, a timestamp, and real filesystem side effects:

**backup.sh**

```bash
#!/usr/bin/env bash
# backup.sh — tar+gzip a directory into a timestamped archive

backup_dir() {
  local src="$1"
  local dest_dir="${2:-.}"

  if [[ -z "$src" ]]; then
    echo "Usage: backup_dir <source_dir> [dest_dir]" >&2
    return 1
  fi

  if [[ ! -d "$src" ]]; then
    echo "Error: '$src' is not a directory" >&2
    return 1
  fi

  local timestamp
  timestamp=$(date +%Y%m%d-%H%M%S)
  local archive_name
  archive_name="$(basename "$src")-${timestamp}.tar.gz"

  mkdir -p "$dest_dir"

  if tar -czf "${dest_dir}/${archive_name}" -C "$(dirname "$src")" "$(basename "$src")" 2>/dev/null; then
    echo "${dest_dir}/${archive_name}"
    return 0
  else
    echo "Error: tar failed for '$src'" >&2
    return 1
  fi
}
```

`ai-test backup.sh` came back with ten tests, all green. Here are the first three:

```bash
❯ ai-test backup.sh

→ No test file found for 'backup' — generating a full Bats suite.

setup() {
  source "$BATS_TEST_DIRNAME/../backup.sh"
}

@test "happy path: backup a directory with default destination" {
  local test_dir="$BATS_TEST_DIRNAME/test_dir"
  local archive_name
  mkdir -p "$test_dir"
  echo "test content" > "$test_dir/file1.txt"
  mkdir -p "$test_dir/subdir"
  echo "sub content" > "$test_dir/subdir/file2.txt"

  archive_name=$(backup_dir "$test_dir")
  [ -f "$archive_name" ]
  [ -n "$archive_name" ]
  [[ "$archive_name" == *.tar.gz ]]
}

@test "happy path: backup a directory with custom destination" {
  local test_dir="$BATS_TEST_DIRNAME/test_dir"
  local dest_dir="$BATS_TEST_DIRNAME/dest"
  local archive_name
  mkdir -p "$test_dir"
  echo "test content" > "$test_dir/file1.txt"

  archive_name=$(backup_dir "$test_dir" "$dest_dir")
  [ -f "$archive_name" ]
  [ -n "$archive_name" ]
  [[ "$archive_name" == "$dest_dir"/* ]]
  [[ "$archive_name" == *.tar.gz ]]
}

@test "edge case: backup directory with special characters in name" {
  local test_dir="$BATS_TEST_DIRNAME/test dir with spaces"
  local archive_name
  mkdir -p "$test_dir"
  echo "test content" > "$test_dir/file.txt"

  archive_name=$(backup_dir "$test_dir")
  [ -f "$archive_name" ]
  [ -n "$archive_name" ]
}

→ Save this suite as tests/backup.bats? [y/N] y

→ Written to tests/backup.bats

→ Run the suite now, in Docker? [y/N] y
1..3
ok 1 happy path: backup a directory with default destination
ok 2 happy path: backup a directory with custom destination
ok 3 edge case: backup directory with special characters in name
```

Now run the very same command a second time:

```bash
$ ai-test backup.sh

→ Found existing tests: tests/backup.bats — asking only for the coverage gaps.

@test "error condition: tar fails when source directory is empty" {
  local test_dir="$BATS_TEST_DIRNAME/empty_dir"
  local archive_name
  mkdir -p "$test_dir"

  archive_name=$(backup_dir "$test_dir" 2>&1)
  [ -n "$archive_name" ]
  [[ "$archive_name" == *"Error: tar failed"* ]]
}
```

`ai-test` found the `tests/backup.bats` it wrote a minute ago, sent it to the model along with the source, and asked for the missing cases only. Instead of re-reading ten tests I already trust, I'm reviewing one new, focused addition — and it gets **appended** to the existing file, not written to a second one that would duplicate the `setup()`.

That's the mode you'll use the most: every time you add a branch to a function, a second run asks the model for what changed and nothing else.

### The Same Command, in PHP and in Python

Two Bash demos might give the impression this is a shell-scripting toy, so let's be explicit: the only thing that changes between languages is the extension you type. Here's a PHP class small enough to keep in your head, doing the one thing every project ends up rewriting:

**src/Slug.php**

```php
<?php

declare(strict_types=1);

namespace App\Support;

/**
 * Turn a human title into a URL-friendly slug.
 */
final class Slug
{
    public static function make(string $title): string
    {
        $slug = strtolower(trim($title));

        // Everything that is not a letter or a digit becomes a separator,
        // then repeated separators are collapsed into a single dash.
        $slug = preg_replace('/[^a-z0-9]+/', '-', $slug);
        $slug = trim((string) $slug, '-');

        if ($slug === '') {
            throw new \InvalidArgumentException('Title produces an empty slug');
        }

        return $slug;
    }
}
```

And its Python equivalent in spirit — two pure functions, a few guard clauses, no I/O:

**src/prices.py**

```python
"""Tiny pricing helpers — small enough to check the generated tests by hand."""


def apply_discount(price: float, percent: float) -> float:
    """Return `price` reduced by `percent`, rounded to the cent.

    A 0% discount returns the price unchanged; 100% returns 0.0.
    """
    if price < 0:
        raise ValueError("price cannot be negative")

    if not 0 <= percent <= 100:
        raise ValueError("percent must be between 0 and 100")

    return round(price * (1 - percent / 100), 2)


def cheapest(offers: dict[str, float]) -> str:
    """Return the name of the cheapest offer.

    Ties are resolved by name, so the result never depends on dict ordering.
    """
    if not offers:
        raise ValueError("no offer given")

    return min(sorted(offers), key=offers.__getitem__)
```

Run `ai-test src/Slug.php` and `ai-test src/prices.py`, and everything behaves the same way: same prompt, same two confirmations, same throw-away container. Only the destination changes — `tests/Unit/SlugTest.php` and `tests/test_prices.py`, both resolved from the project root (`composer.json` for PHP, `pyproject.toml` or `setup.py` for Python) rather than from `src/`.

## Under the Hood (skip this if you just want to use it)

### The Logic, Step by Step

1. Register itself with `AI_COMMANDS[test]=...` — the one line that puts `ai-test` in the `ai` menu.
2. Walk up to the project root (`.git`, `composer.json`, `pyproject.toml`…), derive where the suite *should* live, and look for an existing test file using each ecosystem's naming convention: `<name>.bats`, `<Name>Test.php`, `test_<name>.py` / `<name>_test.py`.
3. Build one of two prompts — "write a full suite", or "here's the source *and* the current tests, give me only what's missing" — and, in the first case, append the **bootstrap paragraph**.
4. Send it through `_ollama_query`, strip the Markdown fences the model adds despite being told not to, and pretty-print the result with `bat` if it's available.

Three things worth calling out in `_ollama.zsh` itself:

* The leading underscore is deliberate: the loader (`for fn_file in ~/.zsh/fns/*.zsh`) sources files alphabetically and `_` sorts before any letter, so `AI_COMMANDS` and `ai()` always exist before an `ai-*.zsh` file tries to register itself into them.
* `_ollama_query` pings `${host}/api/tags` first, with a two-second timeout, and fails loudly if Ollama isn't reachable — better an immediate error than a `curl` hanging for thirty seconds against a stopped container. It also builds its JSON payload with `jq`, so quotes, backslashes and newlines in the source code I'm about to paste into the prompt are escaped for me. Note that the prompt is *piped* into `jq` rather than passed as a `--arg` value: Linux caps a single command-line argument at 128 KB, and a big file or a long diff would otherwise blow up with `argument list too long`.
* `AI_COMMANDS` is a plain associative array, and that is why one line of registration is enough to make a new function show up in the `ai` menu — no central list to maintain, no file to edit when the series grows.

### The One Instruction That Makes the Difference

That bootstrap paragraph in step 3 is what decides whether a generated suite works or is completely inert.

The rule is simple: **a test can only call code it has loaded, and the model never sees where that code lives.** It receives a blob of text, never a path. Ask for a suite without saying anything else, and you get well-named tests with sensible assertions that all fail the same way — `command not found`, exit code 127 — because nothing ever loaded the file under test.

`ai-test` computed the save path a step earlier, so it doesn't hope: `_ai_test_bootstrap` dictates the loading line, in the form each ecosystem expects.

* **[Bats](/blog/bats-unit-tests)** — each test runs in a fresh shell that has loaded nothing but the `.bats` file, so the suite must open with a `setup()` that sources the script. `_ai_relative_to` computes the path from the test's folder to the source, so `src/lib/tool.sh` saved as `tests/tool.bats` yields `source "$BATS_TEST_DIRNAME/../src/lib/tool.sh"`.
* **Pytest** — `tests/test_tool.py` can't `import tool` unless the project root is on the path. Rather than let the model write `sys.path` incantations, the Docker run sets `PYTHONPATH=/code` and the prompt says *"import the module directly, do not touch sys.path"*.
* **Pest** — the class is autoloaded by Composer, so what the model needs is the **namespace**: `_ai_test_bootstrap` greps the `namespace` line out of the source and hands over a ready-made `use` statement. No namespace declared? It falls back to a `require_once` with the computed relative path.

> **Give the model the layout, not just the code:**
>
> This generalizes well beyond tests. When an LLM writes code that will live in a *specific place* in a *specific project*, most of its mistakes come from the context you didn't give it — file paths, import roots, namespaces, conventions. Those are things your script already knows, and every fact you hand over is a fact the model no longer has to guess wrong.

### Where the File Gets Saved

The suite is printed in your console first: you read it there, and nothing has touched your disk yet. Then `ai-test` asks if you want to keep it — and since it knows the framework, it proposes the path that framework expects, so you never have to remember whether Pest wants `tests/Unit/` or `tests/Feature/`:

| Source           | Framework | Proposed path               |
| ---------------- | --------- | --------------------------- |
| `backup.sh`      | Bats      | `tests/backup.bats`         |
| `src/Backup.php` | Pest      | `tests/Unit/BackupTest.php` |
| `src/backup.py`  | Pytest    | `tests/test_backup.py`      |

Note that `tests/` hangs off the **project root**, not off the source file's folder: `src/Backup.php` proposes `tests/Unit/BackupTest.php` at the top of the repository, not the nonsensical `src/tests/Unit/BackupTest.php`.

> **It still asks first:**
>
> Nothing is written without an explicit `y`, and if the target file already exists the question becomes an unambiguous *"… already exists. Overwrite it?"*. Anything else — including just pressing Enter — prints `→ Not saved.` and stops there. Generated code shouldn't land in your repository by accident.

### Running the Suite Without Installing a Test Runner

Installing a test runner for code I might delete thirty seconds later is an absurd amount of setup, so `ai-test` runs the suite in a container instead. Bats [publishes an official image](https://hub.docker.com/r/bats/bats) whose entrypoint is `bats` itself, which makes it a one-liner:

```bash
$ docker run --rm --user "$(id -u):$(id -g)" --volume "${root}:/code" --workdir /tmp bats/bats:latest /code/tests/backup.bats
```

The three images are overridable through `AI_TEST_BATS_IMAGE`, `AI_TEST_PHP_IMAGE` and `AI_TEST_PY_IMAGE` — see the `~/.zshrc` block above.

> **Your code is mounted read-write:**
>
> The container gets the project folder, not a copy of it, because the tests have to create temporary files next to the code. It's a throw-away container (`--rm`), but it *is* running generated code against your working tree — one more reason to read the output before answering `y`.

### Write for the Test You Haven't Written Yet

Here's the `greet.sh` from the top of this article:

**greet.sh**

```bash
#!/usr/bin/env bash
# greet.sh — ask for a name and a language, then print the greeting.

# normalize_name <name> — trim the surrounding spaces and capitalize the first
# letter, so " christophe " and "Christophe" end up as the same thing.
normalize_name() {
  local name="$1"

  # Strip leading, then trailing whitespace — pure parameter expansion, no
  # external command involved.
  name="${name#"${name%%[![:space:]]*}"}"
  name="${name%"${name##*[![:space:]]}"}"

  if [[ -z "$name" ]]; then
    echo "Error: no name given" >&2
    return 1
  fi

  echo "${name^}"
}

# greet <name> [lang] — print the greeting line. The language defaults to
# English and is case-insensitive.
greet() {
  local name="$1"
  local lang="${2:-en}"

  local clean
  clean=$(normalize_name "$name") || return 1

  case "${lang,,}" in
    en) echo "Hello ${clean}!" ;;
    fr) echo "Bonjour ${clean} !" ;;
    nl) echo "Hallo ${clean}!" ;;
    *)
      echo "Error: unsupported language '${lang}' (expected en, fr or nl)" >&2
      return 1
      ;;
  esac
}

main() {
  local name lang
  read -rp "What is your first name? " name
  read -rp "Which language (en/fr/nl)? " lang
  greet "$name" "$lang"
}

# Only run main() when the script is executed, never when it is sourced —
# this is what lets a test suite load the functions without triggering the
# interactive prompts.
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  main "$@"
fi
```

It's tiny, but it already has everything a test suite cares about: two functions, a default value, and three ways to fail. Run on its own, it's just an interactive prompt:

```bash
$ ./greet.sh
What is your first name? christophe
Which language (en/fr/nl)? fr
Bonjour Christophe !
```

The last three lines are what makes the whole exercise possible:

```bash
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  main "$@"
fi
```

`main` runs only when the script is *executed*, never when it is *sourced*. Without that guard, the `setup()` of the generated suite would `source greet.sh`, hit `read -rp "What is your first name? "`, and hang forever on input that never comes.

Which gives the two habits that make any script testable: put the logic in functions that take arguments and print results, and wrap the interactive part in a `BASH_SOURCE` guard. Skip them, and the best model in the world can only generate tests that hang.

### Choosing Your Model

This isn't a one-model-fits-all situation. On a 24GB card, `qwen3-coder:30b` gives noticeably better test coverage reasoning than the smaller `1.5b`/`7b` variants I compared in my [network access article](/blog/accessing-ollama-across-your-local-network) — it's slower, but for a task you run a handful of times a day, not thousands, the extra ten seconds don't matter. If you're VRAM-constrained, drop to `qwen2.5-coder:7b` and expect a good happy-path suite with weaker edge-case coverage; you'll do more of the thinking yourself.

## Conclusion

Two files to copy into `~/.zsh/fns/`, one new shell, and the script you were never going to test becomes `ai-test greet.sh`: a full suite, green, in the time it takes to make coffee — nothing installed, nothing leaving your machine.

Grab `greet.sh` above and try it on your own scripts. Then look at the one you've been avoiding for months, the `backup.sh` of your repository, and run it there too: worst case you throw the output away, best case you finally have a suite.
