Clyde Testing Guide

How to test Clyde's repository scanning, bundling, CLI, config, Ollama, NotebookLM, protocol, and cross-platform behavior.

Clyde terminal showing doctor diagnostics and repository scan report output — Clyde in action: local diagnostics and scan reports give humans and agents a compact repository readiness picture.

Default suitego test ./...

Test files13 Go test files

CI platformsLinux, macOS, Windows

Quick Start#

Run the full suite from the repository root.

go test ./...

For normal Go changes, format the touched files first.

gofmt -w <changed .go files>
go test ./...

For release or feature work, include command smoke checks.

go test ./...
go run ./cmd/clyde --about
go run ./cmd/clyde help --json
go run ./cmd/clyde doctor --json
go run ./cmd/clyde scan-report . --json

CI Matrix#

Clyde's GitHub Actions test workflow runs go test ./... on Ubuntu, macOS, and Windows. That validates portable Go behavior. External tools such as Git, Ollama, Node/npm, NotebookLM MCP, and nlm are still local dependencies for workflows that use them.

Suite Map#

Area	What It Protects
Repository scanner	Secret skips, include/exclude matching, invalid paths, size limits, and symlink skipping.
Bundler	Chunk boundaries, text preservation, manifest/chunks output, book metadata, skip records, and invalid output paths.
CLI	Preview, scan-report, bundle, sync guards, help, JSON command catalog, doctor, about links, completions, numeric flags, and prompt limits.
Configuration	Config file loading, env overrides, URL validation, NUL rejection, numeric limits, permissions, defaults, and config commands.
Ollama and agent	Model listing, generation, streaming, input hardening, remote URL guard, prompt ordering, and UTF-8-safe truncation.
NotebookLM, MCP, JSON-RPC	Redacted subprocess errors, bounded buffers, MCP frames, JSON-RPC failures, and request body limits.

Focused Commands#

go test ./internal/clyde -run 'TestScanRepo'
go test ./internal/clyde -run 'TestMakeChunks|TestWriteBundle|TestSplitText'
go test ./internal/clyde -run 'Test.*Help|Test.*Doctor|Test.*Completion|TestPreview|TestScanReport|TestBundle'
go test ./internal/clyde -run 'TestLoadConfig|TestConfigCommand'
go test ./internal/clyde -run 'TestOllama|TestCLIAsk|TestCLIModels|TestAgentRejectsRemote'
go test ./internal/clyde -run 'TestMCP|TestRPC|TestCommandSummary|TestRunCommand|TestLimitedBuffer'

Cross-Platform#

Clyde is portable Go intended for macOS, Linux, and Windows. Cross-building proves compilation for a target; native testing still matters for terminal behavior and external dependencies.

for target in darwin/amd64 darwin/arm64 linux/amd64 linux/arm64 windows/amd64 windows/arm64; do
  os="${target%/*}"
  arch="${target#*/}"
  suffix=""
  if [ "$os" = windows ]; then suffix=".exe"; fi
  GOOS="$os" GOARCH="$arch" go build -o "/tmp/clyde-${os}-${arch}${suffix}" ./cmd/clyde
done

Release Verification#

git status --short
gofmt -w <changed .go files>
go test ./...
go run ./cmd/clyde --about
go run ./cmd/clyde help --json
go run ./cmd/clyde doctor --json
go run ./cmd/clyde scan-report . --json

Release checks should also generate every completion target: Bash, Zsh, Fish, PowerShell, Elvish, Nushell, Xonsh, Tcsh, Clink, Yash, and Oil-family shells.

Common Failures#

Windows-only failure: check path separators, executable suffixes, file permissions, shell assumptions, and hard-coded temp paths.
Config hardening failure: Clyde deliberately rejects unsafe config values and overly writable config files.
Ollama failure: tests should use local test servers, not a real daemon; inspect request shape and stream parsing.
NotebookLM failure: error paths must stay bounded and redacted.
Completion failure: keep human help, help --json, and generated completions aligned.