agentleFS
schmitthubschmitthub/clawker/test/AGENTS.md

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.

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
  1. Distinctive:

    Test infrastructure for all non-unit tests.

    line 3
  2. Very specific:

    Cleanup: Always t.Cleanup() — never deferred functions

    line 26
  3. Very specific:

    Stop daemons via CLI (firewall down, host-proxy stop)

    line 95
  4. Very specific:

    Remove firewall infrastructure containers (by purpose=firewall label), then CP containers (by purpose=controlplane label)

    line 96
  5. Very specific:

    Remove test-labeled containers, volumes, networks, then images (by the consts.LabelTestName label)

    line 97
  6. Very specific:

    All test resources carry dev.clawker.test=true + dev.clawker.test.name=TestName.

    line 160

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 integration

Conventions

  • 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=true on all resources; dev.clawker.test.name=TestName per test
  • Whail labels: test/whail/ uses com.whail.test.managed=true; self-contained cleanup

E2E Harness API (test/e2e/harness/)

Types

TypeFieldsPurpose
HarnessT *testing.T, Opts *FactoryOptions, Cleanup *CleanupReportIsolated test environment with CLI execution; Cleanup is populated at teardown
CleanupReportFirewallContainers, CPContainers, AgentContainers intSnapshot of what was running when cleanup ran — read via RequireServicesWereRunning
RunResultExitCode int, Err error, Stdout string, Stderr string, Factory *cmdutil.FactoryOutcome of a CLI command
SetupResultembeds *testenv.Env, ProjectDir stringResolved paths from NewIsolatedFS
FSOptionsProjectDir stringOverride project dir name (default: "testproject")
FactoryOptionsSee belowDependency 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.

FieldSignatureDefault
Configfunc(...config.NewConfigOption) (config.Config, error)configmocks.NewBlankConfig()
Clientfunc(ctx, cfg, log, ...docker.ClientOption) (*docker.Client, error)mocks.NewFakeClient; real constructors receive the shared harness Logger and docker.TestLabelConfig labels
ProjectManagerfunc(log, project.GitManagerFactory, nameOverride, project.Registry) (project.ProjectManager, error)nil (resolving f.ProjectManager() errors)
GitManagerfunc(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.Clientderived, no option field
HostProxyfunc(cfg, log) (*hostproxy.Manager, error)hostproxytest.NewMockManager; once-cached like production, so the stateful mock's EnsureRunning transition survives across resolutions
SocketBridgefunc(cfg, log) socketbridge.SocketBridgeManagernil (no-op); once-cached
UseRealAdminClientbool — 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.
UseRealControlPlanebool — 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

FunctionSignaturePurpose
NewIsolatedFS(h *Harness) NewIsolatedFS(opts *FSOptions) *SetupResultCreates 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) *RunResultFresh Factory → root.NewCmdRoot → execute (full Cobra pipeline)
RunInContainer(h *Harness) RunInContainer(agent, cmd...) *RunResultcontainer run --rm --agent <agent> @ <cmd>
ExecInContainer(h *Harness) ExecInContainer(agent, cmd...) *RunResultcontainer exec --user <consts.ContainerUser> --agent <agent> <cmd>
ExecInContainerAsRoot(h *Harness) ExecInContainerAsRoot(agent, cmd...) *RunResultcontainer exec --agent <agent> <cmd> (root)
NewFactoryNewFactory(t, opts) (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffer, *bytes.Buffer)Constructs Factory with lazy singletons; returns in/out/err buffers
EnsureNoControlPlaneEnsureNoControlPlane(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:

  1. Snapshot running infrastructure into h.Cleanup (CleanupReport)
  2. Stop daemons via CLI (firewall down, host-proxy stop)
  3. Remove firewall infrastructure containers (by purpose=firewall label), then CP containers (by purpose=controlplane label)
  4. Remove test-labeled containers, volumes, networks, then images (by the consts.LabelTestName label)

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 with host-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 above
  • dockerListByLabel(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):

TestVerifies
TestFirewall_BlockedDomain / _AllowedDomainUnlisted domains blocked; required domains reachable through Envoy
TestFirewall_UpDown / _BypassStack lifecycle verbs; bypass start/stop/expiry
TestFirewall_AddRemove / _ConfigRules / _PruneDynamic rule management; config-rule sync; store reset (config floor survives prune, --all empties, non-interactive gate, CP-down fail-fast)
TestFirewall_Statusfirewall 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 / _ICMPBlockedNon-TLS protocol routing and blocking
TestFirewall_CPNameResolvesAn 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_SocketTypeAllowlistThe 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_RootEnforcedA root shell (container exec -u root) with unmarked sockets is enforced like other uids: an unlisted domain stays NXDOMAIN.
TestFirewall_HostActionsBehindCPHost 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_ControlPlaneDownFailsClosedcontrolplane 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 / _DockerDNSDirectPortDeniedDNS goes to CoreDNS; a direct dial to the random port of Docker's embedded resolver is denied
TestFirewall_ExactAllowBlocksSubdomain / _DenySubdomainUnderWildcard / _WildcardAndExactCoexistAn exact rule resolves the apex only; a deny rule under a wildcard wins; wildcard and exact rules get separate Envoy filter chains
TestFirewall_PathRuleNormalizationDefeatsSmugglingURL-encoded .. sequences cannot pass a path-rule prefix match
TestFirewall_IntraSubnetAllowlist / _FirewallDisabledIn-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)

TestVerifies
TestSandbox_NoNewPrivileges_E2EThe agent process has the kernel no-new-privileges flag, so setuid binaries in the image cannot raise its privileges
TestSandbox_DockerSocketGroup_E2EWith 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.