go-internal

go-internal is a curated re-export of packages originally written inside the Go standard library and toolchain, made importable by projects that aren’t part of the Go distribution itself. The flagship package, testscript, is extracted directly from the go command’s own internal test harness (cmd/go/internal/script) — the same shell-like, txtar-driven scripting engine the Go core team uses to test the go command against real CLI behavior, stdout/stderr assertions, and golden-file comparisons.

Alongside testscript, the module bundles a set of smaller, independently useful packages: txtar (a trivial text archive format for embedding multi-file test fixtures in a single readable block), par (a simple parallel work-cache primitive), dirhash, module, modfile, and semver (thin, migration-friendly forwarding layers over their golang.org/x/mod/x/tools equivalents), plus lower-level filesystem helpers like lockedfile, renameio, and robustio for safe concurrent file access. gotooltest and goproxytest extend testscript specifically for testing code that shells out to the go tool or needs a local module proxy.

Because every package here started life inside the Go project, they carry the same testing discipline the toolchain itself is held to — the repo’s own CI runs the full suite with the race detector on Linux, macOS, and Windows across two Go versions, and enforces gofmt/go mod tidy cleanliness on every push.

What You Get

• testscript: a txtar-driven, shell-like scripting engine for testing CLI programs, including stdout/stderr assertions, exit-status checks, and automatic golden-file updates
• txtar: a trivial text-archive format for packing multiple test fixture files into one readable, diff-friendly block
• gotooltest and goproxytest: testscript extensions for testing code that invokes the go tool or needs a local GOPROXY
• dirhash, module, modfile, semver: forwarding-compatible packages mirroring golang.org/x/mod APIs for module- and version-related logic
• lockedfile, renameio, robustio: cross-platform helpers for safe, concurrent, atomic file access
• par: a minimal work-parallelization cache primitive used internally by the Go toolchain

Common Use Cases

• Testing a Go CLI tool end-to-end by scripting real command invocations, environment variables, and file trees inside .txtar/.txt script files
• Packing a directory tree of test fixtures into a single portable txtar archive for use as golden test data
• Writing tests that need to shell out to go build/go test/go mod and assert on the tool’s exact behavior
• Safely reading/writing shared files (like on-disk caches) from multiple processes without corruption
• Parsing or comparing Go module versions and go.mod files with the same logic the go command itself uses

Under The Hood

Architecture The repository is a flat collection of independently focused packages rather than a single cohesive framework: testscript (the flagship package, built around a TestScript/Params engine that drives txtar-defined scripts through cmd.go’s builtin command set), txtar (its own minimal archive parser), and a handful of stdlib-adjacent utilities (par, semver, dirhash, module, modfile, lockedfile, renameio, robustio) that each solve one narrow problem. testscript itself pulls in imports, par, and testenv as internal dependencies and drives command execution and PTY support through testscript/internal/pty and testscript/exe.go, but there is no shared framework layer binding the packages together — swapping out any one (e.g. replacing the vendored txtar with golang.org/x/tools/txtar, already flagged as a TODO in txtar/archive.go) would have no ripple effect on the others.

Tech Stack A modern Go module (go 1.25) with a deliberately minimal dependency graph — only golang.org/x/mod, golang.org/x/sys, and golang.org/x/tools — consistent with its role as a low-level, dependency-light building block rather than an application framework. There’s no database, web layer, or ORM; the closest thing to a runtime target is the go/build and os/exec machinery testscript uses to shell out to real processes during test execution. CI (GitHub Actions) runs the full suite plus -race across Go 1.25.x/1.26.x on Ubuntu, macOS, and Windows, and separately enforces go mod tidy and gofmt -d cleanliness.

Code Quality 23 _test.go files, but the more telling signal is the extensive testdata/*.txt corpus (dozens of scripts covering interrupts, symlinks, stdout/stderr capture, kill signals, and more) that exercises testscript by using testscript on itself. Error handling follows idiomatic Go — explicit returns wrapped with fmt.Errorf, with panics reserved for programmer-error cases like an invalid environment-variable key in Env.Setenv. Type aliases (e.g. Archive = txtar.Archive) are used deliberately to preserve API compatibility during an in-progress migration to an upstream package. No dedicated linter config was found beyond the CI’s gofmt/tidy checks.

API Design The public surface favors small, composable entry points over configuration sprawl: testscript.Run(t, testscript.Params{...}) is the only call most consumers need, with Setup, Cmds, and Condition hooks in Params covering customization rather than subclassing or interfaces. Getting started requires near-zero boilerplate — a TestMain plus a testdata/ directory of scripts is enough to begin, and the extensive doc.go (369 lines) doubles as both API reference and a full specification of the script language itself.