refactor(testutil): consolidate Dolt readiness into enum

Expand from 3-state to 5-state doltReadiness enum:
- doltNoDocker (renamed from doltNoDaemon for clarity)
- doltNoImage (no image at all)
- doltWrongVersion (repo cached but wrong tag)
- doltSkipped (explicit BEADS_TEST_SKIP=dolt opt-out)
- doltReady

Add isDoltRepoImageCached() to distinguish "no image" from "wrong
version". Add hasTestSkip() for comma-separated BEADS_TEST_SKIP
parsing. Silent skip for explicit opt-out avoids ~1s docker info
overhead.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Pablo LION 2026-03-03 10:50:36 +01:00
commit ddfc5e9407
2 changed files with 136 additions and 39 deletions

View file

@ -48,6 +48,51 @@ TEST_VERBOSE=1 ./scripts/test.sh
TEST_RUN=TestCreate ./scripts/test.sh
```
### Docker (Dolt Integration Tests)
Dolt integration tests require Docker with the exact Dolt image cached locally.
Tests auto-detect the environment and skip gracefully — no manual configuration
needed.
#### Readiness states
```csv
State,Condition,Behavior
doltSkipped,BEADS_TEST_SKIP contains "dolt",Silent skip (no warning)
doltNoDocker,Docker daemon not reachable,WARN + skip
doltNoImage,No Dolt image at all,WARN + skip with pull instruction
doltWrongVersion,Image repo cached but wrong tag,WARN + skip with pull instruction
doltReady,Exact image cached and Docker running,Run tests
```
States are checked once per test binary and cached. Order of evaluation:
`BEADS_TEST_SKIP` → Docker availability → exact image → any image version.
#### Skipping Dolt tests explicitly
Set `BEADS_TEST_SKIP` to opt out without Docker overhead (~1s `docker info`):
```bash
# Skip Dolt tests silently
BEADS_TEST_SKIP=dolt ./scripts/test.sh
# Skip multiple services (comma-separated)
BEADS_TEST_SKIP=dolt,slow ./scripts/test.sh
```
#### Enabling Dolt tests
```bash
# Pull the exact Dolt image to enable integration tests
docker pull dolthub/dolt-sql-server:1.43.0
# Point tests at an existing Dolt server (skips container startup)
BEADS_DOLT_PORT=3308 ./scripts/test.sh
```
`BEADS_DOLT_PORT` — when set, tests reuse the server at that port instead of
starting a container. Port 3307 is hardcoded as production and always rejected.
### Advanced Usage
```bash

View file

@ -8,6 +8,7 @@ import (
"os"
"os/exec"
"strconv"
"strings"
"sync"
"testing"
"time"
@ -38,40 +39,104 @@ var (
doltTerminateOnce sync.Once
dockerOnce sync.Once
dockerAvail bool
doltCheckOnce sync.Once
doltCached doltReadiness
)
// isDockerAvailable returns true if the Docker daemon is reachable and
// the Dolt image is cached locally. If the daemon is up but the image
// is not cached, it returns false so tests skip gracefully instead of
// pulling from Docker Hub (which triggers network alarms, fails offline,
// and adds latency). See GH#2277.
//
// Set BEADS_SKIP_DOCKER=1 to force-skip all Docker-based tests.
// doltReadiness describes why Dolt integration tests can or cannot run.
type doltReadiness int
// doltDockerRepo is the repository portion of DoltDockerImage (without the tag).
var doltDockerRepo, _, _ = strings.Cut(DoltDockerImage, ":")
const (
doltNoDocker doltReadiness = iota // Docker daemon not reachable
doltNoImage // no Dolt image at all
doltWrongVersion // image exists but wrong tag
doltSkipped // explicit opt-out via BEADS_TEST_SKIP
doltReady // ready to start containers
)
func (d doltReadiness) String() string {
switch d {
case doltNoDocker:
return "Docker not available"
case doltNoImage:
return fmt.Sprintf("Docker image %s not cached locally (run 'docker pull %s')", DoltDockerImage, DoltDockerImage)
case doltWrongVersion:
return fmt.Sprintf("Docker image %s cached but wrong version (run 'docker pull %s')", doltDockerRepo, DoltDockerImage)
case doltSkipped:
return "Dolt tests skipped (BEADS_TEST_SKIP=dolt)"
case doltReady:
return "Dolt ready"
default:
return fmt.Sprintf("unknown dolt readiness state: %d", int(d))
}
}
// isDockerAvailable returns true if the Docker daemon is reachable.
// The result is cached after the first call.
func isDockerAvailable() bool {
dockerOnce.Do(func() {
if os.Getenv("BEADS_SKIP_DOCKER") == "1" {
fmt.Fprintf(os.Stderr, "WARN: BEADS_SKIP_DOCKER=1 set, skipping Docker-based tests\n")
return
}
if exec.Command("docker", "info").Run() != nil {
return
}
if exec.Command("docker", "image", "inspect", DoltDockerImage).Run() != nil {
fmt.Fprintf(os.Stderr, "WARN: Docker image %s not cached locally, skipping Docker-based tests. Run 'docker pull %s' to enable them.\n", DoltDockerImage, DoltDockerImage)
return
}
dockerAvail = true
dockerAvail = exec.Command("docker", "info").Run() == nil
})
return dockerAvail
}
// isDoltImageCached returns true if the Dolt Docker image is already
// available locally, avoiding unnecessary network calls to Docker Hub.
// hasTestSkip returns true if the given service appears in the BEADS_TEST_SKIP
// env var (comma-separated list). Example: BEADS_TEST_SKIP=dolt,slow
func hasTestSkip(service string) bool {
val := os.Getenv("BEADS_TEST_SKIP")
if val == "" {
return false
}
for _, s := range strings.Split(val, ",") {
if strings.TrimSpace(s) == service {
return true
}
}
return false
}
// checkDolt returns the readiness state for Dolt integration tests.
// It composes hasTestSkip, isDockerAvailable, isDoltImageCached, and
// isDoltRepoImageCached, caching the result.
func checkDolt() doltReadiness {
doltCheckOnce.Do(func() {
// Explicit skip checked first to avoid ~1s docker info cost.
if hasTestSkip("dolt") {
doltCached = doltSkipped
return
}
if !isDockerAvailable() {
return // doltCached zero value is doltNoDocker
}
if isDoltImageCached() {
doltCached = doltReady
return
}
if isDoltRepoImageCached() {
doltCached = doltWrongVersion
return
}
doltCached = doltNoImage
})
return doltCached
}
// isDoltImageCached returns true if the exact Dolt Docker image (repo:tag)
// is available locally, avoiding unnecessary network calls to Docker Hub.
func isDoltImageCached() bool {
return exec.Command("docker", "image", "inspect", DoltDockerImage).Run() == nil
}
// isDoltRepoImageCached returns true if ANY version of the Dolt image repo
// exists locally (e.g. dolthub/dolt-sql-server with a different tag).
func isDoltRepoImageCached() bool {
out, err := exec.Command("docker", "images", doltDockerRepo, "-q").Output()
return err == nil && len(strings.TrimSpace(string(out))) > 0
}
// StartTestDoltServer starts a Dolt SQL server in a Docker container on a
// dynamic port. Uses testcontainers-go for clean lifecycle management.
//
@ -101,16 +166,12 @@ func StartTestDoltServer(tmpDirPrefix string) (*TestDoltServer, func()) {
// Singleton: start at most one container per test binary.
doltServerOnce.Do(func() {
if !isDockerAvailable() {
fmt.Fprintf(os.Stderr, "WARN: Docker not available, skipping test server\n")
if state := checkDolt(); state != doltReady {
if state != doltSkipped {
fmt.Fprintf(os.Stderr, "WARN: %s, skipping test server\n", state)
}
return
}
if !isDoltImageCached() {
fmt.Fprintf(os.Stderr, "WARN: Docker image %s not cached locally, skipping test server\n", DoltDockerImage)
fmt.Fprintf(os.Stderr, " Run 'docker pull %s' to enable Dolt integration tests\n", DoltDockerImage)
return
}
doltServerErr = startDoltContainer()
})
@ -205,11 +266,8 @@ func (s *TestDoltServer) CrashError() error {
// mapped host port. The container is terminated automatically when the test finishes.
func StartIsolatedDoltContainer(t *testing.T) string {
t.Helper()
if !isDockerAvailable() {
t.Skip("Docker not available, skipping test")
}
if !isDoltImageCached() {
t.Skipf("Docker image %s not cached locally, skipping test (run 'docker pull %s')", DoltDockerImage, DoltDockerImage)
if state := checkDolt(); state != doltReady {
t.Skipf("skipping test: %s", state)
}
ctx, cancel := context.WithTimeout(context.Background(), serverStartTimeout)
@ -252,11 +310,8 @@ func ensureSharedContainer() {
// TestMain functions. Call TerminateDoltContainer() after m.Run() to clean up.
// Sets BEADS_DOLT_PORT process-wide.
func EnsureDoltContainerForTestMain() error {
if !isDockerAvailable() {
return fmt.Errorf("Docker not available")
}
if !isDoltImageCached() {
return fmt.Errorf("Docker image %s not cached locally (run 'docker pull %s')", DoltDockerImage, DoltDockerImage)
if state := checkDolt(); state != doltReady {
return fmt.Errorf("%s", state)
}
ensureSharedContainer()
@ -267,11 +322,8 @@ func EnsureDoltContainerForTestMain() error {
// test if Docker is not available.
func RequireDoltContainer(t *testing.T) {
t.Helper()
if !isDockerAvailable() {
t.Skip("Docker not available, skipping test")
}
if !isDoltImageCached() {
t.Skipf("Docker image %s not cached locally, skipping test (run 'docker pull %s')", DoltDockerImage, DoltDockerImage)
if state := checkDolt(); state != doltReady {
t.Skipf("skipping test: %s", state)
}
ensureSharedContainer()