README
¶
testscript
Package testscript integrates Go's testing framework with scripttest tests.
This package makes it easy to run scripttest tests as part of your standard Go test suite,
letting you combine traditional Go unit tests with scripttest-based integration tests.
Installation
go get github.com/tmc/scripttestutil/testscript
Basic Usage
package myapp_test
import (
"testing"
"github.com/tmc/scripttestutil/testscript"
)
func TestApp(t *testing.T) {
// Run all scripttest tests in the testdata directory
opts := testscript.DefaultOptions()
testscript.RunDir(t, "testdata", opts)
}
Features
- Run scripttest tests as standard Go tests
- Simple API with smart defaults
- Supports Docker-based testing
- Manages snapshots for verification testing
- Provides clean integration with Go's testing package
Running Methods
// Run a single test file
testscript.RunFile(t, "testdata/single.txt", opts)
// Run all tests in a directory
testscript.RunDir(t, "testdata", opts)
// Run tests matching a pattern
testscript.Run(t, "testdata/api/*.txt", opts)
Running Tests in This Repository
This repository contains several test files in the testscript package:
# Run all tests in all categories
go test -v ./testscript -run TestAll
# Run tests by category
go test -v ./testscript -run TestWithTag/gotools # Run all Go tools tests
go test -v ./testscript -run TestWithTag/spinner # Run all spinner tests
# Run individual test groups
go test -v ./testscript -run TestGoTools # Run all Go tools tests
go test -v ./testscript -run TestSpinner # Run all spinner tests
# Run specific tests
go test -v ./testscript -run TestSpecificGoTool # Run a specific Go tool test
go test -v ./testscript -run TestIndividualSpinnerTests/Basic # Run basic spinner test
# Update snapshots
UPDATE_SNAPSHOTS=1 go test -v ./testscript -run TestAll
Options
opts := testscript.DefaultOptions()
// Enable verbose output (respects `go test -v`)
opts.Verbose = testing.Verbose()
// Update test snapshots
opts.UpdateSnapshots = true
// Set environment variables
opts.EnvVars = map[string]string{
"API_URL": "http://localhost:8080",
}
// Use Docker for testing
opts.UseDocker = true
opts.DockerImage = "golang:latest"
Example Test Files
Create scripttest files in your testdata directory:
# testdata/basic.txt
echo "Hello, World!"
stdout 'Hello, World!'
! stderr .
env TEST_VAR=test_value
env | grep TEST_VAR
stdout 'TEST_VAR=test_value'
Advanced Usage
For more control, use the Runner API directly:
runner := testscript.NewRunner(testscript.Options{
Pattern: "testdata/*.txt",
Verbose: true,
})
runner.Run(t)
Testing CLI Applications
func TestMain(m *testing.M) {
// Build your CLI application
os.MkdirAll("bin", 0755)
exec.Command("go", "build", "-o", "bin/myapp", ".").Run()
// Run tests
os.Exit(m.Run())
}
func TestCLI(t *testing.T) {
testscript.RunDir(t, "testdata", testscript.DefaultOptions())
}
Your test files can then use your CLI application:
# testdata/cli.txt
bin/myapp --version
stdout 'v1.0.0'
! stderr .
bin/myapp calculate 2 + 3
stdout '5'
License
MIT - See the LICENSE file for details.
Documentation
¶
Overview ¶
Package testscript provides integration between Go's testing package and scripttest.
The testscript package makes it easy to run scripttest tests as part of standard Go test suites, combining traditional Go tests and scripttest-based integration tests.
Basic Usage ¶
Here's a simple example:
package mypackage_test
import (
"testing"
"github.com/tmc/scripttestutil/testscript"
)
func TestCLI(t *testing.T) {
// Run all scripttest tests in the testdata directory
opts := testscript.DefaultOptions()
opts.Verbose = testing.Verbose()
testscript.RunDir(t, "testdata", opts)
}
Features ¶
The testscript package supports:
- Running individual test files or patterns - Docker-based tests - Snapshot creation and verification - Custom environment variables - Organized sub-tests for each scripttest file
Running Tests ¶
The package provides several ways to run tests:
// Run a single test file testscript.RunFile(t, "testdata/basic.txt", opts) // Run all tests in a directory testscript.RunDir(t, "testdata", opts) // Run tests matching a pattern testscript.Run(t, "testdata/cli/*.txt", opts)
Options ¶
Configure test behavior with Options:
opts := testscript.DefaultOptions()
opts.Verbose = true // Enable verbose output
opts.UpdateSnapshots = true // Update test snapshots
opts.EnvVars = map[string]string{ // Set environment variables
"DEBUG": "true",
"API_URL": "http://localhost:8080",
}
Example with Docker ¶
To run tests in Docker containers:
func TestInDocker(t *testing.T) {
opts := testscript.DefaultOptions()
opts.UseDocker = true
opts.DockerImage = "golang:1.22"
testscript.RunDir(t, "testdata/docker", opts)
}
Parallel Testing ¶
The package works with Go's parallel testing:
func TestParallel(t *testing.T) {
t.Parallel() // Enable parallel testing
testscript.RunDir(t, "testdata", testscript.DefaultOptions())
}
Package testscript provides a clean connection between Go's testing framework and scripttest. It allows scripttest tests to be run as part of standard Go test suites.
Example (TestscriptWithCommands) ¶
Example_testscriptWithCommands demonstrates how to run tests with custom commands
package main
import (
"fmt"
)
func main() {
// This won't actually run in the example, just showing the pattern
fmt.Println("Running directory with custom commands:")
fmt.Println(`
import (
"testing"
"github.com/tmc/scripttestutil/commands"
"github.com/tmc/scripttestutil/testscript"
"rsc.io/script"
)
func TestWithExpectCommands(t *testing.T) {
opts := testscript.DefaultOptions()
opts.Verbose = testing.Verbose()
// Register expect commands
opts.SetupHook = func(cmds map[string]script.Cmd) {
commands.RegisterExpect(cmds)
}
// Run all tests in the expect directory
testscript.RunDir(t, "testdata/expect", opts)
}
`)
}
Output: Running directory with custom commands: import ( "testing" "github.com/tmc/scripttestutil/commands" "github.com/tmc/scripttestutil/testscript" "rsc.io/script" ) func TestWithExpectCommands(t *testing.T) { opts := testscript.DefaultOptions() opts.Verbose = testing.Verbose() // Register expect commands opts.SetupHook = func(cmds map[string]script.Cmd) { commands.RegisterExpect(cmds) } // Run all tests in the expect directory testscript.RunDir(t, "testdata/expect", opts) }
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Options ¶
type Options struct {
// Pattern is the glob pattern to match test files (default: "testdata/*.txt")
Pattern string
// UseDocker determines whether to run tests in Docker containers
UseDocker bool
// DockerImage specifies which Docker image to use when UseDocker is true (default: golang:latest)
DockerImage string
// UpdateSnapshots controls whether snapshots should be updated
UpdateSnapshots bool
// Verbose enables verbose output
Verbose bool
// EnvVars defines additional environment variables to pass to tests
EnvVars map[string]string
// SnapshotDir specifies the directory for snapshots (default: testdata/__snapshots__)
SnapshotDir string
// SetupHook is a function called to set up additional commands or conditions
// It receives the engine's command map which can be extended with custom commands
SetupHook func(cmds map[string]script.Cmd)
}
Options defines configuration options for running scripttest tests.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns the default test options.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner manages the execution of scripttest tests using Go's testing package.
Source Files
Directories