From cff186c4da0ade00543429184170a3ca8222acce Mon Sep 17 00:00:00 2001 From: Ali Serag Date: Wed, 22 Apr 2026 20:54:38 -0500 Subject: [PATCH 1/2] docs: apply SEO/GEO audit recommendations --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 05a1915..fb499f5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# testingdock +# testingdock — Docker-Based Integration Test Framework for Go A Go library for managing Docker containers and networks in integration tests. Define container dependencies as a tree, and testingdock starts them in parallel with health checks, then tears everything down when the test finishes. @@ -8,7 +8,7 @@ A Go library for managing Docker containers and networks in integration tests. D go get github.com/onflow/testingdock ``` -Requires Go 1.22+ and Docker SDK v28. +Requires Go 1.24+ and Docker SDK v28. ## Usage @@ -96,3 +96,12 @@ Pass these via `go test`: This library creates networks and containers under the label `owner=testingdock`. Resources with this label are considered owned by testingdock and may be aggressively cleaned up on startup and teardown. Existing containers or networks with the same name that were **not** created by testingdock will cause tests to abort. + +## About Flow + +This repo is part of the [Flow network](https://flow.com), a Layer 1 blockchain built for consumer applications, AI agents, and DeFi at scale. + +- Developer docs: https://developers.flow.com +- Cadence language: https://cadence-lang.org +- Community: [Flow Discord](https://discord.gg/flow) · [Flow Forum](https://forum.flow.com) +- Governance: [Flow Improvement Proposals](https://github.com/onflow/flips) From f12a5a6f4bf141cb234aa5e932629ba807e4f87b Mon Sep 17 00:00:00 2001 From: Ali Serag Date: Thu, 23 Apr 2026 15:40:29 -0500 Subject: [PATCH 2/2] docs: add AGENTS.md Adds the AGENTS.md open-standard file for AI coding agents. Every claim evidence-backed against Makefile, package.json, source tree, or equivalent manifest. Zero fabrication. --- AGENTS.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0ff423c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,80 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (Claude Code, Codex, Cursor, Copilot, and others) +when working in this repository. It is loaded into agent context automatically — keep it concise. + +## Overview + +`testingdock` is a Go library that manages Docker containers and networks for integration tests +(`github.com/onflow/testingdock`, see `go.mod`). Tests declare a tree of container dependencies +rooted on a network; the suite starts them (in parallel by default), blocks on per-container +health checks, and tears everything down on `Close`. Requires Go 1.24.0 (`go.mod`) and the +Docker Engine SDK v28.5.2 (`github.com/docker/docker`, `github.com/docker/cli`). + +## Build and Test Commands + +Go toolchain is invoked with `GO111MODULE=on` via the `Makefile`: + +- `make build` — `go build` of the package. +- `make test` — `go test` (requires a running Docker daemon; tests pull real images such as + `postgres` — see `container_functional_test.go`). +- `make lint` — runs `gometalinter` (declared in `Makefile`; not vendored, must be installed + separately). + +Test flags, registered in `suite.go`'s `init()`: + +- `-testingdock.sequential` — spawn sibling containers sequentially instead of in parallel + (sets `SpawnSequential`; useful for debugging). +- `-testingdock.verbose` — enable verbose daemon log forwarding (sets `Verbose`). + +Pass through `go test`, e.g. `go test -testingdock.verbose -run TestContainer_Start`. + +## Architecture + +Flat package at the repo root (`package testingdock`). Four source files: + +- `suite.go` — `Suite`, `SuiteOpts`, `GetOrCreateSuite`, `UnregisterAll`, and the global + flag registration. Suites are keyed by name in an internal `registry` map. +- `network.go` — `Network`, `NetworkOpts`, startup/reset/remove logic, and initial cleanup + of stale `owner=testingdock` resources. +- `container.go` — `Container`, `ContainerOpts`, `HealthCheckFunc`/`HealthCheckHTTP`/ + `HealthCheckCustom`, `ResetFunc`/`ResetCustom`, image pulling, and private-registry auth + via `docker/cli/cli/config` (reads `~/.docker/config.json`). +- `helpers.go` — `RandomPort`, logging `printf`, and the `owner=testingdock` label helpers. + +Tests live alongside sources as `*_test.go` (external `testingdock_test` package). A +`TestMain` is required to call `flag.Parse()` and `testingdock.UnregisterAll()` — see +`suite_test.go` for the canonical pattern. + +Dependency wiring is a tree: `network.After(container)` attaches a container to the +network; `container.After(child)` makes `child` start only after the parent's health check +passes. Siblings start in parallel unless `-testingdock.sequential` is set (`suite.go`, +`network.go`). + +## Conventions and Gotchas + +- **Label ownership.** All networks and containers are created with label `owner=testingdock` + (`helpers.go` `createTestingLabel`). On startup, pre-existing resources with this label are + aggressively removed; resources with the same name but without the label cause `t.Fatalf`. + Never remove or rename this label. +- **`TestMain` is mandatory.** Consumers must call `flag.Parse()` then `testingdock.UnregisterAll()` + in `TestMain`; otherwise test flags aren't bound and containers leak between runs + (`suite_test.go:12-20`, package doc in `suite.go`). +- **Health check timeout** defaults to 30s when `ContainerOpts.HealthCheckTimeout` is zero + (`container.go`'s `ContainerOpts` comment). The default (zero-value) health check only + verifies Docker reports the container as running — override with `HealthCheckHTTP` or + `HealthCheckCustom` for real readiness. +- **Reset vs. Close.** `Suite.Reset(ctx)` re-runs each container's `ResetFunc` (default: + `ContainerRestart`) and re-checks health; use `ResetCustom` for in-place cleanup like + truncating tables. `Suite.Close` tears the network down. +- **Private registries.** If an image reference contains a registry domain, `container.go` + base64-encodes credentials from `~/.docker/config.json` via `clicfg` for the pull. +- **Port allocation.** Use `testingdock.RandomPort(t)` (`helpers.go`) for host-side port + bindings; it reserves a free TCP port on `localhost:0` and returns it as a string. +- **Docker daemon required.** Tests instantiate a real client via `client.FromEnv` + (`suite.go`). Without a reachable daemon they `t.Fatalf` unless `SuiteOpts.Skip` is set. + +## Files Not to Modify + +- `go.sum` — regenerate via `go mod tidy`, do not hand-edit. +- `LICENSE.txt` — Apache-2.0 header, do not edit.