Documentation
¶
Overview ¶
Package sbx registers a Docker Sandbox runtime for Testcontainers. The sbx CLI must be installed and authenticated with sbx login before provider initialization. Importing the package does not start a sandbox. The sandbox's Docker API is unauthenticated on host loopback; use a host with trusted local users and processes.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrProviderStarted = errors.New("sbx provider initialization has started; configure before the first Testcontainers operation")
ErrProviderStarted is returned when configuration is attempted after provider initialization has begun, including after failed initialization or cleanup.
Functions ¶
func Cleanup ¶
Cleanup removes the sandbox managed by the default provider. It does nothing if initialization has not started.
func Configure ¶
Configure configures the registered default provider without starting or selecting it. Call it before any Testcontainers operation, typically in TestMain before m.Run or provider health checks. Select sbx separately through TESTCONTAINERS_PROVIDER or the provider property. Each call applies all its options atomically or leaves configuration unchanged. Explicit settings override TESTCONTAINERS_SBX_* environment variables, which are read when initialization begins.
Example ¶
These examples omit Output directives so they compile without changing the process-wide provider configuration used by the integration tests.
package main
import (
"log"
"time"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// configureProvider {
// Save the documented example kit as testdata/test-tools/test-tools.yaml first.
if err := sbx.Configure(
sbx.WithStartupTimeout(8*time.Minute),
sbx.WithKits("./testdata/test-tools"),
sbx.WithKitArgs(map[string]string{
"test-tools.mode": "integration",
}),
); err != nil {
log.Fatal(err)
}
// }
}
Output:
Types ¶
type Option ¶
type Option func(*options) error
Option configures a sandbox before provider initialization. These options apply to the sandbox, not to containers running inside it.
func WithAppName ¶
WithAppName sets the sbx CLI namespace for every command, overriding TESTCONTAINERS_SBX_APP_NAME. An empty name selects the CLI's default namespace. Names accept up to 20 ASCII letters, digits, hyphens, and underscores. Authenticate the selected namespace with sbx login before initialization.
Example ¶
package main
import (
"log"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withAppName {
if err := sbx.Configure(sbx.WithAppName("tc-tests")); err != nil {
log.Fatal(err)
}
// }
}
Output:
func WithBinary ¶
WithBinary sets the sbx executable path or name, overriding TESTCONTAINERS_SBX_BINARY. The executable is resolved when initialization begins.
Example ¶
package main
import (
"log"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withBinary {
if err := sbx.Configure(sbx.WithBinary("/usr/local/bin/sbx")); err != nil {
log.Fatal(err)
}
// }
}
Output:
func WithBindRoots ¶
WithBindRoots replaces the additional allowed host bind roots, overriding TESTCONTAINERS_SBX_BIND_ROOTS and any earlier WithBindRoots option. Paths must be absolute directories that exist at startup. WithBindRoots() clears additional roots; the workspace is always allowed. Input paths are copied.
Example ¶
package main
import (
"log"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withBindRoots {
if err := sbx.Configure(sbx.WithBindRoots("/opt/test-fixtures", "/srv/shared-fixtures")); err != nil {
log.Fatal(err)
}
// }
}
Output:
func WithKitArgs ¶
WithKitArgs merges kit arguments. Later values override earlier values for the same key. Use "name" for a shared argument or "kit-handle.name" to target one kit. sbx validates declared arguments and their values. Empty values are valid. Arguments are plain text recorded by sbx; use sbx credentials for secrets.
Example ¶
package main
import (
"log"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withKitArgs {
if err := sbx.Configure(sbx.WithKitArgs(map[string]string{
"test-tools.mode": "integration",
})); err != nil {
log.Fatal(err)
}
// }
}
Output:
func WithKits ¶
WithKits appends mixin references to the sandbox's creation request, in order. The required Docker TCP kit is always included automatically. sbx validates source references, duplicate kits, dependencies, and compatibility. References may be OCI images, local directories, or Git sources. Relative paths are resolved by the CLI against the process working directory at startup, independently of WithWorkspace or TESTCONTAINERS_SBX_WORKSPACE.
Example ¶
package main
import (
"log"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withKits {
// Save the documented example kit as testdata/test-tools/test-tools.yaml first.
if err := sbx.Configure(sbx.WithKits("./testdata/test-tools")); err != nil {
log.Fatal(err)
}
// }
}
Output:
func WithStartupTimeout ¶
WithStartupTimeout sets the positive timeout for sandbox initialization, including kit installation, overriding TESTCONTAINERS_SBX_TIMEOUT.
Example ¶
package main
import (
"log"
"time"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withStartupTimeout {
if err := sbx.Configure(sbx.WithStartupTimeout(8 * time.Minute)); err != nil {
log.Fatal(err)
}
// }
}
Output:
func WithWorkspace ¶
WithWorkspace sets the sandbox workspace, overriding TESTCONTAINERS_SBX_WORKSPACE. Relative paths are resolved against the process working directory at startup. The directory must exist when initialization begins.
Example ¶
package main
import (
"log"
"github.com/testcontainers/testcontainers-go/modules/sbx"
)
func main() {
// withWorkspace {
if err := sbx.Configure(sbx.WithWorkspace(".")); err != nil {
log.Fatal(err)
}
// }
}
Output:
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider manages one Docker Sandbox. Its zero value is ready for use.
func (*Provider) Cleanup ¶
Cleanup waits for any active initialization and removes this provider's sandbox. It does nothing before initialization and can be retried after failure.
func (*Provider) Configure ¶
Configure configures this provider without starting it. Repeated calls compose until initialization begins; later calls return ErrProviderStarted. Each call applies all its options atomically or leaves configuration unchanged.
func (*Provider) Initialize ¶
func (p *Provider) Initialize(ctx context.Context) (testcontainers.RuntimeConfig, error)
Initialize starts a sandbox and returns its runtime configuration. The sbx CLI must already be authenticated with sbx login. Host binds are limited to the workspace and absolute directories configured with WithBindRoots or TESTCONTAINERS_SBX_BIND_ROOTS. Initialization is attempted once per Provider.
Source Files