How to run the tests

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# How to run the tests

This guide shows how to check the project before you commit or open a merge request. It assumes the development prerequisites are installed (see [How to develop the application](develop-the-application.md)) and a terminal at the root of the repository.

## Run what the CI runs

```bash
make check
```

It runs the linters (`make lint`), then every test that needs no real agent, no model and no network (`make test`). A green run ends with:

```text
14 passed, 0 failed
all licence header tests passed
```

The CI (`.github/workflows/ci.yml`) runs the same command, plus `make bindings-check`.

## Run one part

| To check | Command |
| --- | --- |
| Go packages | `make test-go`, or `go test -race ./internal/agents -run Limit -v` for one test |
| Frontend (vitest), including the WCAG contrast of the theme's colours | `make test-frontend` |
| Shell tooling (agents.sh, licence headers, package names, release tag) | `make test-scripts` |
| Go lint (golangci-lint, pinned in `tools/go.mod`) | `make lint-go` |
| Frontend types and Svelte warnings | `make lint-frontend` |
| Licence headers | `make lint-headers` |
| Committed TypeScript bindings are up to date | `make bindings-check` |

## Run the tests against the real agents

```bash
make test-real
```

It runs the tests built with the `realagents` tag: the ACP handshake with Alice, Riker asking permission before running a command, Bob reading Alice's answer in a channel, and Alice remembering a conversation after a restart (`internal/acp`, `internal/channels`). Allow about a minute. They need `mm` (or `MM_BIN`) and llmman, and start agents only through `scripts/agents.sh`, so the two-agents limit and the unloading apply.

## Run the workspace tests in a container

The workspace contract tests (`internal/workspace`) also run inside a real container when Docker and the `alpine:3.22` image are present; otherwise those tests are skipped. To include them:

```bash
docker pull alpine:3.22
go test ./internal/workspace
```

To run them in an sbx sandbox too, name a running one:

```bash
SIDEKICKS_TEST_SBX=<sandbox> go test -count=1 -run TestSandboxWorkspace ./internal/workspace
```

## Variants

- **`go test` complains about `frontend/dist`**: the Go binary embeds the built frontend. `make test-go` builds it when missing; with plain `go test`, run `make frontend` once.
- **The spikes** (`spikes/`) are separate modules and are not tested; check them with `go vet .` inside each folder.
- **`make: warning: Clock skew detected`** appears when the repository is on a folder shared with another machine; it does not change the result.

## See also

- Every target → [Reference: commands](../reference/commands.md)
- The tooling under test → [Reference: scripts/agents.sh](../reference/agents-script.md)