clawker / test
AGENTS.md59 starsChanged 12 days agoMITView on GitHub
Test infrastructure for all non-unit tests. Uses directory separation instead of build tags. Some nil fields use test fakes (configmocks.NewBlankConfig, mocks.NewFakeClient, hostproxytest.NewMockManager, adminv1mocks.AdminServiceClientMock, the controlplane/manager ManagerMock). Logger is always production-mirroring: once-cached and settings-driven (file switch, rotation knobs, OTEL), replicating newLogger in internal/cmd/factory/default.go. ProjectManager and GitManager left nil return a descriptive harness error — never (nil, nil), a state production cannot produce. Set a field to the real constructor for integration tests.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- clawkerd/AGENTS.mdAGENTS.md
- controlplane/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- agent-filesSkill
- audit-memorySkill
- cli-outputSkill
- dev-checksSkill
- firewall-uatSkill
- initiativeSkill
- monitoring-checksSkill
- store-editorSkill
- test-hunterSkill
- wizard-commandsSkill
- writing-testsSkill
- code-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 3
Test infrastructure for all non-unit tests.
- Very specific: line 26
Cleanup: Always t.Cleanup() — never deferred functions
- Very specific: line 95
Stop daemons via CLI (firewall down, host-proxy stop)
- Very specific: line 96
Remove firewall infrastructure containers (by purpose=firewall label), then CP containers (by purpose=controlplane label)
- Very specific: line 97
Remove test-labeled containers, volumes, networks, then images (by the consts.LabelTestName label)
- Very specific: line 160
All test resources carry dev.clawker.test=true + dev.clawker.test.name=TestName.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Test Package
Test infrastructure for all non-unit tests. Uses directory separation instead of build tags.
Structure
test/
├── e2e/ # End-to-end integration tests (Docker + real infra)
│ └── harness/ # CLI test harness (harness.go, factory.go)
└── whail/ # Whail BuildKit integration tests (Docker + BuildKit)Running Tests
make test # Unit tests only (no Docker)
go test ./test/e2e/... -v -timeout 10m # E2E integration (firewall, mounts)
go test ./test/whail/... -v -timeout 5m # Whail BuildKit integrationConventions
- Golden files: Per-package strategies — whail recorded scenarios (
GOLDEN_UPDATE=1), firewall corefile golden (hand-edit), storage struct-literal golden (make storage-golden) - Fakes:
internal/docker/mocks/,pkg/whail/whailtest/ - Cleanup: Always
t.Cleanup()— never deferred functions - Labels:
dev.clawker.test=trueon all resources;dev.clawker.test.name=TestNameper test - Whail labels:
test/whail/usescom.whail.test.managed=true; self-contained cleanup
E2E Harness API (test/e2e/harness/)
Types
| Type | Fields | Purpose |
Harness | T *testing.T, Opts *FactoryOptions, Cleanup *CleanupReport | Isolated test environment with CLI execution; Cleanup is populated at teardown |
CleanupReport | FirewallContainers, CPContainers, AgentContainers int | Snapshot of what was running when cleanup ran — read via RequireServicesWereRunning |
RunResult | ExitCode int, Err error, Stdout string, Stderr string, Factory *cmdutil.Factory | Outcome of a CLI command |
SetupResult | embeds *testenv.Env, ProjectDir string | Resolved paths from NewIsolatedFS |
FSOptions | ProjectDir string | Override project dir name (default: "testproject") |
FactoryOptions | See below | Dependency constructor overrides for Factory |
FactoryOptions (factory.go)
Some nil fields use test fakes (configmocks.NewBlankConfig, mocks.NewFakeClient, hostproxytest.NewMockManager, adminv1mocks.AdminServiceClientMock, the controlplane/manager ManagerMock). Logger is always production-mirroring: once-cached and settings-driven (file switch, rotation knobs, OTEL), replicating newLogger in internal/cmd/factory/default.go. ProjectManager and GitManager left nil return a descriptive harness error — never (nil, nil), a state production cannot produce. Set a field to the real constructor for integration tests.
| Field | Signature | Default |
Config | func(...config.NewConfigOption) (config.Config, error) | configmocks.NewBlankConfig() |
Client | func(ctx, cfg, log, ...docker.ClientOption) (*docker.Client, error) | mocks.NewFakeClient; real constructors receive the shared harness Logger and docker.TestLabelConfig labels |
ProjectManager | func(log, project.GitManagerFactory, nameOverride, project.Registry) (project.ProjectManager, error) | nil (resolving f.ProjectManager() errors) |
GitManager | func(string) (*git.GitManager, error) | nil (resolving f.GitManager() errors) |
— (f.BundleManager) | always wired, mirrors bundleManagerFunc in internal/cmd/factory/default.go — real bundle.NewManager over the harness Config with the registry-roots GC provider attached unconditionally; with no ProjectManager wired a GC pass surfaces the harness error (fail-closed, loud) | derived, no option field |
— (f.CLIState, f.HttpClient) | always wired, production-mirroring: state.New() (resolves under the test's isolated XDG dirs) and a 30s-timeout stdlib *http.Client | derived, no option field |
HostProxy | func(cfg, log) (*hostproxy.Manager, error) | hostproxytest.NewMockManager; once-cached like production, so the stateful mock's EnsureRunning transition survives across resolutions |
SocketBridge | func(cfg, log) socketbridge.SocketBridgeManager | nil (no-op); once-cached |
UseRealAdminClient | bool — when true, wires a production-identical pure-dial AdminClient (mirrors adminClientFunc in internal/cmd/factory/default.go: mutex-guarded cache + cacheableState re-dial on TransientFailure/Shutdown + keepalive params via adminclient.Dial). Does not bootstrap the CP — CP lifecycle is owned by container-start and explicit controlplane up (see UseRealControlPlane below). When false, adminv1mocks.AdminServiceClientMock with only FirewallRemove wired as a no-op (cleanup's firewall down path); any other RPC panics loudly — opt into UseRealAdminClient to drive admin verbs. | |
UseRealControlPlane | bool — when true, wires the production CP manager exactly as controlPlaneFunc in internal/cmd/factory/default.go does: resolve Config, Logger, and the Docker client once, then cpmanager.NewManager(dc, cfg, log), sharing the Factory's cached Docker singleton (with test labels) and settings snapshot. When false, a controlplane/manager/mocks ManagerMock with every method returning zero values, so tests that don't touch CP verbs never panic on a nil moq func nor bootstrap a real CP. |
Functions
| Function | Signature | Purpose |
NewIsolatedFS | (h *Harness) NewIsolatedFS(opts *FSOptions) *SetupResult | Creates isolated XDG dirs, links the real ~/.docker/cli-plugins into the empty isolated DOCKER_CONFIG (Docker Desktop keeps docker compose only there), registers cleanup |
Chdir | (r *SetupResult) Chdir(t, dir) | Changes working directory with cleanup to restore |
Run | (h *Harness) Run(args ...string) *RunResult | Fresh Factory → root.NewCmdRoot → execute (full Cobra pipeline) |
RunInContainer | (h *Harness) RunInContainer(agent, cmd...) *RunResult | container run --rm --agent <agent> @ <cmd> |
ExecInContainer | (h *Harness) ExecInContainer(agent, cmd...) *RunResult | container exec --user <consts.ContainerUser> --agent <agent> <cmd> |
ExecInContainerAsRoot | (h *Harness) ExecInContainerAsRoot(agent, cmd...) *RunResult | container exec --agent <agent> <cmd> (root) |
NewFactory | NewFactory(t, opts) (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffer, *bytes.Buffer) | Constructs Factory with lazy singletons; returns in/out/err buffers |
EnsureNoControlPlane | EnsureNoControlPlane(t, timeout) | Removes any pre-existing CP so bring-up mints certs against this env's CA (a foreign CP passes the healthz reuse probe but fails every admin RPC). Call after NewIsolatedFS, before the first CP-bootstrapping command |
RequireServicesWereRunning | (h *Harness) RequireServicesWereRunning(t, services...) | Fails the test if the cleanup snapshot shows "firewall"/"controlplane" never ran. Register via t.Cleanup BEFORE NewIsolatedFS (LIFO) so it reads the populated report |
Usage Pattern
h := &harness.Harness{T: t, Opts: &harness.FactoryOptions{
Config: func(...config.NewConfigOption) (config.Config, error) { return testCfg, nil },
// Wire a real CP + admin client for firewall integration tests.
// Omit both to stay on the mocks.
UseRealControlPlane: true, // production manager over the Factory's own Client/Config/Logger
UseRealAdminClient: true, // production-identical pure-dial closure
}}
setup := h.NewIsolatedFS(nil)
// setup.Env has XDG dirs; setup.ProjectDir is cwd
result := h.Run("firewall", "status", "--json")
require.Equal(t, 0, result.ExitCode, "stderr: %s", result.Stderr)Cleanup
NewIsolatedFS registers a single cleanup chain:
- Snapshot running infrastructure into
h.Cleanup(CleanupReport) - Stop daemons via CLI (
firewall down,host-proxy stop) - Remove firewall infrastructure containers (by
purpose=firewalllabel), then CP containers (bypurpose=controlplanelabel) - Remove test-labeled containers, volumes, networks, then images (by the
consts.LabelTestNamelabel)
On failure, dumps clawker.log (logger.DefaultLogFileName), hostproxy.log, and clawker-controlplane.log from the test's state dir.
Internal Helpers
TestMain(test/e2e/main_test.go) — the e2e test binary acts as the clawker CLI when it is started withhost-proxy …. The host proxy manager starts its daemon from its own executable, which in e2e runs is this binary.cleanupTestEnvironment(t, h)— orchestrates cleanup chain abovedockerListByLabel(ctx, resourceType, label)— lists Docker resource IDs by label
Firewall E2E Tests (test/e2e/firewall_test.go)
Tests exercise the full Envoy+CoreDNS firewall stack with real Docker. Shared
preamble lives in newFirewallHarness / newFirewallYAMLHarness(t, projectYAML,
services...) (real wiring + services invariant + isolated FS + register +
build); pass fwNoServices for tests that deliberately end with the stack
down. NewIsolatedFS (requireNoLiveAgents in test/e2e/harness/harness.go) fails when a running agent without the test label exists:
the test CP shares the host's pinned BPF maps, and its cleanup firewall down
would open that agent's egress. Stop live agents before an e2e run.
fwSetup calls EnsureNoControlPlane after it creates the isolated
filesystem. Each test must start a CP that uses its own CA; an existing CP
can have a matching binary but certificates from another environment.
Highlights (not exhaustive — see the file):
| Test | Verifies |
TestFirewall_BlockedDomain / _AllowedDomain | Unlisted domains blocked; required domains reachable through Envoy |
TestFirewall_UpDown / _Bypass | Stack lifecycle verbs; bypass start/stop/expiry |
TestFirewall_AddRemove / _ConfigRules / _Prune | Dynamic rule management; config-rule sync; store reset (config floor survives prune, --all empties, non-interactive gate, CP-down fail-fast) |
TestFirewall_Status | firewall status --json reports health + rule count |
TestFirewall_PathRules* / _TLSPathRules* | HTTP and TLS MITM path rule enforcement |
TestFirewall_WildcardSANCerts | .clawker.dev admits three project-owned Worker Custom Domains with deep hostnames; one request per host verifies TLS, reaches upstream, and returns HTTP 200 |
TestFirewall_SSHTCPMapping / _HTTPDomainDetection / _ICMPBlocked | Non-TLS protocol routing and blocking |
TestFirewall_CPNameResolves | An enrolled agent resolves clawker-controlplane to the CP static IP; a TXT query gets an empty answer and a subdomain NXDOMAIN |
TestFirewall_Identity* | Route identities stable across rule churn and CP restart |
TestFirewall_SocketTypeAllowlist | The sock_create allowlist: an enrolled container can create TCP stream and UDP datagram sockets only (the test probes SCTP and UDP-Lite sockets, which are denied). Only socket creation is probed |
TestFirewall_RootEnforced | A root shell (container exec -u root) with unmarked sockets is enforced like other uids: an unlisted domain stays NXDOMAIN. |
TestFirewall_HostActionsBehindCP | Host actions go through the CP: a denied open/url host is refused before a browser opens, a callback session the agent does not own is refused, enable_host_proxy: false and forward_https: false are refused at the CP, and the host proxy reconnects after a CP restart |
TestFirewall_ControlPlaneDownFailsClosed | controlplane down with a running agent keeps the agent enrolled: the drain stops Envoy and CoreDNS but keeps the eBPF state of live cgroups, so the agent has no egress until controlplane up |
TestFirewall_DockerInternalDNS / _DockerDNSDirectPortDenied | DNS goes to CoreDNS; a direct dial to the random port of Docker's embedded resolver is denied |
TestFirewall_ExactAllowBlocksSubdomain / _DenySubdomainUnderWildcard / _WildcardAndExactCoexist | An exact rule resolves the apex only; a deny rule under a wildcard wins; wildcard and exact rules get separate Envoy filter chains |
TestFirewall_PathRuleNormalizationDefeatsSmuggling | URL-encoded .. sequences cannot pass a path-rule prefix match |
TestFirewall_IntraSubnetAllowlist / _FirewallDisabled | In-subnet allowlist (another container denied on TCP and UDP, CP agent + Hydra ports open, CP health port denied, DNS intact); disabled-firewall behavior (CP still boots — CP ≠ firewall) |
Tests drive the full CLI pipeline via h.Run(). The CP AdminService is reached indirectly through the production CLI code path. When Opts.UseRealAdminClient == true, the harness wires a production-identical pure-dial closure that mirrors adminClientFunc in internal/cmd/factory/default.go line-for-line (mutex-guarded cache, cacheableState re-dial on TransientFailure/Shutdown, keepalive params, adminclient.Dial). The closure does NOT bootstrap the CP — that's owned by container-start and explicit controlplane up. This is load-bearing for the fail-fast semantics: admin commands surface a clear error when the CP is down rather than silently spinning one up. Any divergence from production is a bug: E2E must exercise the code path the CLI ships with. Cleanup removes firewall and CP containers by purpose label before removing test resources.
Sandbox Hardening E2E Tests (test/e2e/sandbox_hardening_test.go)
| Test | Verifies |
TestSandbox_NoNewPrivileges_E2E | The agent process has the kernel no-new-privileges flag, so setuid binaries in the image cannot raise its privileges |
TestSandbox_DockerSocketGroup_E2E | With security.docker_socket, the boot step gives the mounted socket to the docker group, and the agent process is a member of that group |
Whail Network Integration Test (test/whail/container_network_test.go)
TestContainerCreateEnsureNetworkReplacesDefaultEndpoint sends the request the CLI sends when no --network flag is set (an endpoint under the default key). The container must start on the ensured network only.
Telemetry Relay E2E Test (test/e2e/telemetry_relay_internal_test.go)
TestTelemetryRelay_E2E runs monitor up, starts an agent container, and posts one OTLP metrics batch from inside it to the clawkerd relay (consts.AgentOTLPRelayAddr). The batch crosses the real path: relay, CP AgentService over mTLS (identity gate and registry), OTel gateway, collector agent lane. The batch resource claims a false project, agent, and container_id. The test queries Prometheus on the host for the batch's nonce and requires the CP-resolved values and ingest_source=cp_gateway. The file is package e2e (an _internal_test.go file) because it uses newFirewallHarness.
Debugging Resource Leaks
All test resources carry dev.clawker.test=true + dev.clawker.test.name=TestName. See the root AGENTS.md Testing rules section for lookup commands.
Dependencies
Imports: api/admin/v1 (+ mocks), controlplane/adminclient, controlplane/manager (+ mocks), internal/bundle (+ componentcheck), internal/cmdutil, internal/config (+ mocks), internal/consts, internal/docker (+ mocks), internal/git, internal/hostproxy (+ hostproxytest), internal/iostreams, internal/logger, internal/project, internal/prompter, internal/socketbridge, internal/state, internal/testenv, internal/tui
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

