# Testing Infrastructure + Documentation

## Architecture

```mermaid
flowchart TD
    subgraph TEST["GoClaw Testing Infrastructure"]
        RUN["<b>go test ./... (tests beside the code)</b><br/>Colocated *_test.go · Table-driven tests<br/>go test -race · go test -cover"]

        UNIT["<b>Unit Tests</b><br/>Per package · Pure Go"]
        SEC["<b>Security</b><br/>Scanner · SAST tests"]
        INT["<b>Integration</b><br/>Gateway · API tests"]

        RUN --> UNIT
        RUN --> SEC
        RUN --> INT
    end
```

## Testing (Section 23)

| # | Feature | OpenClaw | GoClaw | Status |
|---|---------|----------|---------|--------|
| 23.1 | Unit tests | Vitest `*.test.ts` | `go test` colocated `*_test.go` | Done |
| 23.2 | Test runner | Vitest (V8) | `go test` (stdlib) | Done |
| 23.3 | Table-driven tests | — | ✅ Go idiomatic pattern | **GoClaw only** |
| 23.4 | Race detection | — | `go test -race` | **GoClaw only** |
| 23.5 | Coverage reporting | `pnpm test:coverage` | `go test -cover` | Done |
| 23.6 | Coverage thresholds | 70% lines/functions/statements | — | **TODO** |
| 23.7 | E2E tests | `*.e2e.test.ts` | — | **TODO** |
| 23.8 | Live tests (real API) | `LIVE=1 pnpm test:live` | Embedding search and RAG embedding tests call a real provider when `GEMINI_API_KEY` or `OPENAI_API_KEY` is set, and skip otherwise | Partial |
| 23.9 | Docker test runners | `test:docker:live-models` etc. | — | **TODO** |
| 23.10 | Install smoke tests | `test:install:smoke` | — | **TODO** |
| 23.11 | CI pipeline | GitHub Actions | `.github/workflows/ci.yml`: gofmt, `go vet`, `go build`, `go test`, `go test -race`, on `v*.*.*` tags and manual dispatch, not on pull requests or pushes. `release.yml` also runs `govulncheck` | Partial |
| 23.12 | Pre-commit hooks | `prek install` | — | **TODO** |

### Other Test Environments

- **Postgres:** `GOCLAW_TEST_POSTGRES_DSN` runs the database tests against Postgres instead of per-test SQLite files; each test gets its own schema (see `AGENTS.md`, Build & Development).
- **MySQL, MariaDB, ClickHouse:** the `db_write` tests run against these when `GOCLAW_TEST_MYSQL_DSN`, `GOCLAW_TEST_MARIADB_DSN` or `GOCLAW_TEST_CLICKHOUSE_DSN` is set, and skip otherwise.
- **Repository checks:** `internal/repoguard` runs with `go test ./...`. `TestNoPilotOrCustomerData` fails on customer data in tracked files, and `TestPublishedDocsAreReachable` fails on a published page that the docs site's sidebar and links do not reach.

## Test Files by Package

Most packages under `internal/` have tests, colocated as `*_test.go`. The main areas:

| Package | Test Scope |
|---------|------------|
| `internal/agent` | Tools (shell, git, cron, calc, datetime, memory, document, text, read_lines, search_files, gitlab, linter, AST, core_instruction, db_write), RAG engine, fallback, cooldown, cache, skills, session memory, memory flush, subagent, registry, safe client, user errors, cron migration |
| `internal/config` | Config loading, agents CRUD, config diff, AST update preservation, non-interactive wizard |
| `internal/secrets` | Credentials store, secret vault store, `${env:}`/`${secret:}`/`${file:}` resolution |
| `internal/gateway` | Server routes + auth, media upload/serve, pending work queue |
| `internal/channel/msteams` | MS Teams webhook handling, Graph API client |
| `internal/memory` | Search (keyword, vector, hybrid, RRF), indexer |
| `internal/channel/discord` | Discord markdown formatting |
| `internal/cli` | CLI commands (config get/set/append/remove) |
| `internal/media` | Media store (save, retrieve, metadata) |
| `internal/pairing` | Pairing store (approve, revoke, list, expiry) |
| `internal/routing` | Multi-agent routing (bindings, platform roles, peer matching) |
| `internal/session` | Session lifecycle (create, get, reset, cleanup) |
| `internal/repoguard` | Customer data in tracked files, docs reachability |

### Test Highlights

| Area | Notable Tests |
|------|--------------|
| **RAG engine** | Keyword extraction, score calculation, core tool/skill injection |
| **Provider fallback** | Error classification, cooldown backoff, probe throttle, moving to the next provider (`fallbackAgent`) |
| **Security** | Shell allow/deny, path sandboxing, secret resolution, file edit safety |
| **Config** | AST-preserving YAML update (comments + blank lines survive), diff detection |
| **Cron** | Job add/remove/toggle, persistence, migration from legacy format |
| **AST tools** | Go AST declaration search, context extraction, diff analysis |
| **GitLab** | API operations (issues, MRs, pipelines, files) |
| **Memory** | Hybrid search (keyword × vector × RRF), temporal decay, consolidation |

---

## Documentation (Section 13)

GoClaw has a `docs/` directory, published at goclaw.ulab.mn.

| # | Document | Status | Notes |
|---|----------|--------|-------|
| 13.1 | `docs/index.md` | Done | Navigation hub, architecture diagram, state directory layout |
| 13.2 | `docs/api-reference/gateway_endpoints.md` | Done | WebSocket protocol, REST endpoints, Web UI |
| 13.3 | `docs/user-guide/configuration.md` | Done | Full YAML config reference, env var overrides, hot reload |
| 13.4 | `docs/user-guide/channels/index.md` | Done | Channel overview, session keys, access control, interface spec |
| 13.5 | `docs/user-guide/channels/discord.md` | Done | Setup, intents, slash commands, guild behavior, pairing |
| 13.6 | `docs/user-guide/channels/msteams.md` | Done | Azure Bot setup, webhook, OAuth, Graph API, team allowlist |
| 13.7 | `docs/user-guide/channels/pairing.md` | Done | Pairing flow, DM policies, approve/revoke via CLI/API/Web UI |
| 13.8 | `docs/architecture/concepts/agent.md` | Done | Agent loop, providers, system prompt, workspace, canvas |
| 13.9 | `docs/architecture/concepts/sessions.md` | Done | SQLite (GORM) storage, session keys, history, lifecycle, cleanup |
| 13.10 | `docs/architecture/concepts/model-failover.md` | Done | Fallback order, cooldown, probe throttle, error classification |
| 13.11 | `docs/user-guide/tools_and_mcp.md` | Done | Tools and MCP servers, with config examples |
| 13.12 | `docs/user-guide/tools_and_mcp.md` (Skills) | Done | Built-in skills, custom skill creation, allow/deny config |
| 13.13 | `docs/user-guide/automation/cron-jobs.md` | Done | 6-field cron syntax, persistence, auto-migration, error tracking |

---

## OpenClaw vs GoClaw Testing Comparison

| Aspect | OpenClaw | GoClaw |
|--------|----------|---------|
| **Framework** | Vitest (V8) | `go test` (stdlib) |
| **Test files** | Hundreds | Colocated `*_test.go` |
| **Packages** | ~30 | Most packages under `internal/` |
| **Coverage** | 70% threshold | `go test -cover` (no threshold) |
| **Race detection** | — | ✅ `go test -race` |
| **Table-driven** | — | ✅ Go idiomatic |
| **CI** | GitHub Actions | GitHub Actions on release tags and manual runs (not on pull requests) |
| **E2E** | ✅ | — (TODO) |
| **Docs** | Mintlify hosted | `docs/`, published at goclaw.ulab.mn |

**Coverage:** unit, race and coverage runs, live provider tests and a release-time CI pipeline are in place; coverage thresholds, E2E tests, Docker test runners, install smoke tests and pre-commit hooks are not.