go-internal

https://pkg.go.dev/github.com/rogpeppe/go-internal
Admin
go-internal is a Go package that factors out internal packages and functionality from the Go...
Tokens:27,989
Snippets:359
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Testscript example: GOPATH setup and build

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

This snippet demonstrates setting up the GOPATH environment variable and building a Go package ('p1') using 'go install -i'. It also includes checks for stale dependencies.

```bash
# GOPATH with p1 in d2, p2 in d2
env GOPATH=$WORK/d1${:}$WORK/d2

# build & install p1
env
go install -i p1
! stale p1
! stale p2
```

--------------------------------

### Run txtar-goproxy and set GOPROXY

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cmd/txtar-goproxy

This example shows how to start the txtar-goproxy command in the background and configure your environment to use it. Ensure you are in the 'cmd/go' directory before running.

```bash
cd cmd/go
go test -proxy=localhost:1234 &
export GOPROXY=http://localhost:1234/mod
```

--------------------------------

### Example Build Tag

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/imports

Illustrates the format for build tags within Go source file comments. Lines starting with '// +build' are parsed to determine file applicability.

```go
// +build windows linux

```

--------------------------------

### Setup Function for Go Command Testing

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/gotooltest

Use Setup to prepare the test environment for tools using the go command. It adds go tag support and configures the go command path. It also sets up necessary environment variables for running the go command.

```go
func Setup(p *testscript.Params) error
```

--------------------------------

### Script Test Definition Example

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Example of a script test definition showing package structure and expected behavior.

```text
# build & install p1 again
go install -i p11
! stale p1
! stale p2

-- $WORK/d1/src/p1/p1.go --
package p1
import "p2"
func F() { p2.F() }
-- $WORK/d2/src/p2/p2.go --
package p2
func F() {}
-- $WORK/p2x.go --
package p2
func F() {}
func G() {}
```

--------------------------------

### Define a testscript reproduction with .gomodproxy

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cmd/testscript

This example demonstrates a txtar file structure including a module definition and a proxy-served dependency.

```text
go get -m fruit.com
go list fruit.com/...
stdout 'fruit.com/fruit'

-- go.mod --
module mod

-- .gomodproxy/fruit.com_v1.0.0/.mod --
module fruit.com

-- .gomodproxy/fruit.com_v1.0.0/.info --
{"Version":"v1.0.0","Time":"2018-10-22T18:45:39Z"}

-- .gomodproxy/fruit.com_v1.0.0/fruit/fruit.go --
package fruit

const Name = "Apple"
```

--------------------------------

### Define a testscript reproduction for goimports

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cmd/testscript

This example shows how to use testscript to verify command execution and output validation for goimports.

```text
go install golang.org/x/tools/cmd/goimports

# check goimports help information
exec goimports -d main.go
stdout 'import "math"'

-- go.mod --
module mod

require golang.org/x/tools v0.0.0-20181221235234-d00ac6d27372

-- main.go --
package mod

const Pi = math.Pi
```

--------------------------------

### Debugging with -testwork

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Example of running a test with the -testwork flag to inspect the temporary environment.

```text
$ go test -run=Script -testwork
--- FAIL: TestScript (3.75s)
    --- FAIL: TestScript/install_rebuild_gopath (0.16s)
        script_test.go:223:
            WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath
            GOARCH=
            GOCACHE=/Users/rsc/Library/Caches/go-build
            GOOS=
            GOPATH=$WORK/gopath
            GOROOT=/Users/rsc/go
            HOME=/no-home
            TMPDIR=$WORK/tmp
            exe=

            # GOPATH with p1 in d2, p2 in d2 (0.000s)
            # build & install p1 (0.085s)
            # modify p2 - p1 should appear stale (0.030s)
            # build & install p1 again (0.019s)
            > go install -i p11
            [stderr]
            can't load package: package p11: cannot find package "p11" in any of:
            	/Users/rsc/go/src/p11 (from $GOROOT)
            	$WORK/d1/src/p11 (from $GOPATH)
            	$WORK/d2/src/p11
            [exit status 1]
            FAIL: unexpected go command failure

        script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src

FAIL
exit status 1
FAIL	cmd/go	4.875s
$

$ WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath
$ cd $WORK/d1/src/p1
$ cat p1.go
package p1
import "p2"
func F() { p2.F() }
$
```

--------------------------------

### func Setup

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/gotooltest

Sets up the given test environment for tests that use the go command. It adds support for go tags to p.Condition and adds the go command to p.Cmds. It also wraps p.Setup to set up the environment variables for running the go command appropriately. It checks go command can run, but not that it can build or run binaries.

```APIDOC
## func Setup

### Description
Sets up the given test environment for tests that use the go command. It adds support for go tags to p.Condition and adds the go command to p.Cmds. It also wraps p.Setup to set up the environment variables for running the go command appropriately. It checks go command can run, but not that it can build or run binaries.

### Method
N/A (Function signature)

### Endpoint
N/A (Function signature)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A (Function returns error)

#### Response Example
```go
error
```
```

--------------------------------

### Create New Server - goproxytest

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/goproxytest

Starts a Go module proxy server on a given network address, serving modules from a specified directory. If the address is empty, it defaults to an arbitrary localhost port. If the directory is empty, 'testmod' is used. The returned Server must be closed after use.

```go
func NewServer(dir, addr string) (*Server, error)
```

--------------------------------

### Retrieve Background Commands

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Returns commands started in the background since the last wait command.

```go
func (ts *TestScript) BackgroundCmds() []*exec.Cmd
```

--------------------------------

### Testscript example: Modifying and checking staleness

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

This snippet shows modifying a Go source file ('p2.go') and then checking for staleness in related packages ('p1' and 'p2').

```bash
# modify p2 - p1 should appear stale
cp $WORK/p2x.go $WORK/d2/src/p2/p2.go
stale p1 p2
```

--------------------------------

### Value: Retrieve Value from Env.Values

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Returns a value from Env.Values, or nil if no value was set by Setup. Use this to access custom data associated with the test environment.

```go
func (ts *TestScript) Value(key any) any
```

--------------------------------

### Initialize Testscript Main Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Use Main within a TestMain function to enable subcommands to run in the testscript context. Main always calls os.Exit. The commands map defines runnable commands that are installed in the shell path.

```go
func Main(m TestingM, commands map[string]func())
```

--------------------------------

### Environment Variable Methods

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Methods for getting and setting environment variables within the test script context.

```APIDOC
## Getenv

### Description
Gets the value of the environment variable named by the key.

### Parameters
- **key** (string) - Required - The name of the environment variable.

### Response
- **string** - The value of the environment variable.

## Setenv

### Description
Sets the value of the environment variable named by the key.

### Parameters
- **key** (string) - Required - The name of the environment variable.
- **value** (string) - Required - The value to set.
```

--------------------------------

### Env Type

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Represents the environment for starting a test script invocation, including working directory, environment variables, and custom values.

```APIDOC
### Env Type

Env holds the environment to use at the start of a test script invocation.

#### Fields
- **WorkDir** (string) - Holds the path to the root directory of the extracted files.
- **Vars** ([]string) - Holds the initial set environment variables that will be passed to the testscript commands.
- **Cd** (string) - Holds the initial current working directory.
- **Values** (map[any]any) - Holds a map of arbitrary values for use by custom testscript commands. This enables Setup to pass arbitrary values (not just strings) through to custom commands.
```

--------------------------------

### Get fuzzing directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Returns the subdirectory used for storing fuzzing data.

```go
func (c *Cache) FuzzDir() string
```

--------------------------------

### Get Test Context

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

T returns the testing context passed to the current test. If tests were started with Run, this will implement testing.TB. Note that the underlying value may not be *testing.T.

```go
func (e *Env) T() T
```

--------------------------------

### Get default cache instance

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Returns the default cache instance; guaranteed to be non-nil.

```go
func Default() *Cache
```

--------------------------------

### Name: Get Short Name of Test Script

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Returns the short name or basename of the test script. Useful for identifying the script in logs or reports.

```go
func (ts *TestScript) Name() string
```

--------------------------------

### ReadFile: Get File Contents Relative to Test Script Directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Returns the contents of a file, interpreted relative to the test script's current directory. Special handling for 'stdout' and 'stderr' to capture output from commands. Fails the script if the file cannot be read.

```go
func (ts *TestScript) ReadFile(file string) string
```

--------------------------------

### Define Testscript Environment

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

The Env type holds the environment configuration for starting a test script invocation, including working directory, environment variables, and custom values.

```go
type Env struct {
	// WorkDir holds the path to the root directory of the
	// extracted files.
	WorkDir string
	// Vars holds the initial set environment variables that will be passed to the
	// testscript commands.
	Vars []string
	// Cd holds the initial current working directory.
	Cd string
	// Values holds a map of arbitrary values for use by custom
	// testscript commands. This enables Setup to pass arbitrary
	// values (not just strings) through to custom commands.
	Values map[any]any
	// contains filtered or unexported fields
}
```

--------------------------------

### Getenv: Get Environment Variable Value

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Retrieves the value of an environment variable. Use this to access environment-specific configurations within your tests.

```go
func (ts *TestScript) Getenv(key string) string
```

--------------------------------

### Stdout: Get io.Writer for Standard Output

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Returns an io.Writer for stdout, intended for user-supplied builtin commands. Panics if called outside the execution of a user-supplied builtin command.

```go
func (ts *TestScript) Stdout() io.Writer
```

--------------------------------

### Get length of SortedMap

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/fmtsort

Returns the number of elements in the SortedMap.

```go
func (o *SortedMap) Len() int
```

--------------------------------

### Create Test Server - goproxytest

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/goproxytest

A wrapper for NewServer designed for Go tests. It integrates with testing.TB for fatal errors, logging, and automatic server cleanup.

```go
func NewTestServer(tb testing.TB, dir, addr string) *Server
```

--------------------------------

### Build Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/semver

Returns the build metadata of a semantic version string.

```go
func Build(v string) string
```

--------------------------------

### Test Script Commands: cd, chmod, cmp, cp, env, exec

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Provides an overview of fundamental test script commands including changing directories, modifying file permissions, comparing files, copying files, managing environment variables, and executing programs.

```go
cd dir Change to the given directory for future commands.
```

```go
chmod perm path... Change the permissions of the files or directories named by the path arguments to the given octal mode (000 to 777).
```

```go
[!] cmp file1 file2 Check that the named files have (or do not have) the same content. By convention, file1 is the actual data and file2 the expected data. File1 can be "stdout" or "stderr" to use the standard output or standard error from the most recent exec or wait command. (If the files have differing content and the command is not negated, the failure prints a diff.)
```

```go
[!] cmpenv file1 file2 Like cmp, but environment variables in file2 are substituted before the comparison. For example, $GOOS is replaced by the target GOOS.
```

```go
cp src... dst Copy the listed files to the target file or existing directory. src can include "stdout" or "stderr" to use the standard output or standard error from the most recent exec or go command.
```

```go
env [key=value...] With no arguments, print the environment (useful for debugging). Otherwise add the listed key=value pairs to the environment.
```

```go
[!] exec program [args...] [&] Run the given executable program with the arguments. It must (or must not) succeed. Note that 'exec' does not terminate the script (unlike in Unix shells).
If the last token is '&', the program executes in the background. The standard output and standard error of the previous command is cleared, but the output of the background process is buffered — and checking of its exit status is delayed — until the next call to 'wait', 'skip', or 'stop' or the end of the test. At the end of the test, any remaining background processes are terminated using os.Interrupt (if supported) or os.Kill.
```

--------------------------------

### SortedMap Methods

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/fmtsort

Provides methods to interact with the SortedMap, including getting its length and comparing/swapping elements.

```APIDOC
## Methods for SortedMap

### Len

```go
func (o *SortedMap) Len() int
```

### Less

```go
func (o *SortedMap) Less(i, j int) bool
```

### Swap

```go
func (o *SortedMap) Swap(i, j int)
```
```

--------------------------------

### Execute Command

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Runs a command and captures its output for later inspection.

```go
func (ts *TestScript) Exec(command string, args ...string) error
```

--------------------------------

### Conditional Execution in Test Scripts

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Illustrates how to use conditions like '[short]', '[net]', '[link]', '[symlink]', '[exec:prog]', '[gc]', '[gccgo]', '[go1.x]', and OS/architecture identifiers to control command execution.

```go
[short] for testing.Short()
net for whether the external network can be used
[link] for whether the OS has hard link support
[symlink] for whether the OS has symbolic link support
[exec:prog] for whether prog is available for execution (found by exec.LookPath)
[gc] for whether Go was built with gc
[gccgo] for whether Go was built with gccgo
[go1.x] for whether the Go version is 1.x or later
[unix] for whether the OS is Unix-like (that is, would match the 'unix' build constraint)
```

```go
[darwin] is true if GOOS=darwin, and [amd64] is true if GOARCH=amd64.
```

```go
[!short] means to run the rest of the line when testing.Short() is false.
```

--------------------------------

### Get Environment Variable

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Getenv retrieves the value of an environment variable. It returns an empty string if the variable is not set.

```go
func (e *Env) Getenv(key string) string
```

--------------------------------

### Prerelease Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/semver

Returns the prerelease information of a semantic version string.

```go
func Prerelease(v string) string
```

--------------------------------

### Execute Command and Check Output

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Executes a command and verifies its standard output matches the expected content. Use single quotes to preserve spaces and disable environment variable expansion.

```go
exec cat hello.text
stdout 'hello world\n'
```

--------------------------------

### Open Pseudo-terminal

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript/internal/pty

Opens a new pseudo-terminal pair, returning the pty and tty file descriptors.

```go
func Open() (pty, tty *os.File, err error)
```

--------------------------------

### Version Type

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Alias for the module.Version type.

```go
type Version = module.Version
```

--------------------------------

### Get temporary file pattern

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/renameio

Returns a glob pattern matching temporary files created during the atomic write process for a given filename.

```go
func Pattern(filename string) string
```

--------------------------------

### Define Test Parameters

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

The Params struct defines configuration for running test scripts, including directory settings, custom commands, and execution behavior.

```go
type Params struct {
	// Dir holds the name of the directory holding the scripts.
	// All files in the directory with a .txtar or .txt suffix will be
	// considered as test scripts. By default the current directory is used.
	// Dir is interpreted relative to the current test directory.
	Dir string

	// Files holds a set of script filenames. If Dir is empty and this
	// is non-nil, these files will be used instead of reading
	// a directory.
	Files []string

	// Setup is called, if not nil, to complete any setup required
	// for a test. The WorkDir and Vars fields will have already
	// been initialized and all the files extracted into WorkDir,
	// and Cd will be the same as WorkDir.
	// The Setup function may modify Vars and Cd as it wishes.
	Setup func(*Env) error

	// Condition is called, if not nil, to determine whether a particular
	// condition is true. It's called only for conditions not in the
	// standard set, and may be nil.
	Condition func(cond string) (bool, error)

	// Cmds holds a map of commands available to the script.
	// It will only be consulted for commands not part of the standard set.
	Cmds map[string]func(ts *TestScript, neg bool, args []string)

	// TestWork specifies that working directories should be
	// left intact for later inspection.
	TestWork bool

	// WorkdirRoot specifies the directory within which scripts' work
	// directories will be created. Setting WorkdirRoot implies TestWork=true.
	// If empty, the work directories will be created inside
	// $GOTMPDIR/go-test-script*, where $GOTMPDIR defaults to os.TempDir().
	WorkdirRoot string

	// Deprecated: this option is no longer used.
	IgnoreMissedCoverage bool

	// UpdateScripts specifies that if a `cmp` command fails and its second
	// argument refers to a file inside the testscript file, the command will
	// succeed and the testscript file will be updated to reflect the actual
	// content (which could be stdout, stderr or a real file).
	//
	// The content will be quoted with txtar.Quote if needed;
	// a manual change will be needed if it is not unquoted in the
	// script.
	UpdateScripts bool

	// RequireExplicitExec requires that commands passed to [Main] must be used
	// in test scripts via `exec cmd` and not simply `cmd`. This can help keep
	// consistency across test scripts as well as keep separate process
	// executions explicit.
	RequireExplicitExec bool

	// RequireUniqueNames requires that names in the txtar archive are unique.
	// By default, later entries silently overwrite earlier ones.
	RequireUniqueNames bool

	// ContinueOnError causes a testscript to try to continue in
	// the face of errors. Once an error has occurred, the script
	// will continue as if in verbose mode.
	ContinueOnError bool

	// Deadline, if not zero, specifies the time at which the test run will have
	// exceeded the timeout. It is equivalent to testing.T's Deadline method,
	// and Run will set it to the method's return value if this field is zero.
	Deadline time.Time
}
```

--------------------------------

### Check Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Validates a module path and version.

```go
func Check(path, version string) error
```

--------------------------------

### Cache Get method

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/par

Retrieves the cached result for a given key. Returns nil if no result is found. This method does not wait for ongoing computations to finish.

```go
func (c *Cache) Get(key any) any
```

--------------------------------

### Define Executable Commands for Scripts

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Integrate custom executable commands into scripts by calling `testscript.Main` with a map of command names to their functions. These functions run in a separate process.

```go
func TestMain(m *testing.M) {
	testscript.Main(m, map[string] func() {
		"testscript": testscriptMain,
	})
}
```

--------------------------------

### Check for Symlink Support

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testenv

Use this to skip tests on systems that do not support os.Symlink.

```go
func MustHaveSymlink(t testing.TB)
```

--------------------------------

### Format function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/modfile

Formats the provided FileSyntax into a byte slice.

```go
func Format(f *FileSyntax) []byte
```

--------------------------------

### Create a Locked File

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/lockedfile

Creates a new file and returns a write-locked *os.File. Ensure to close the file to release the lock.

```go
func Create(name string) (*File, error)
```

--------------------------------

### Stderr: Get io.Writer for Standard Error

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Returns an io.Writer for stderr, intended for user-supplied builtin commands. Panics if called outside the execution of a user-supplied builtin command.

```go
func (ts *TestScript) Stderr() io.Writer
```

--------------------------------

### Params Struct

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Defines the configuration parameters for running a test script.

```APIDOC
## Params Struct

Params holds parameters for a call to Run.

### Fields

- **Dir** (string) - Holds the name of the directory holding the scripts. All files in the directory with a .txtar or .txt suffix will be considered as test scripts. By default the current directory is used. Dir is interpreted relative to the current test directory.
- **Files** ([]string) - Holds a set of script filenames. If Dir is empty and this is non-nil, these files will be used instead of reading a directory.
- **Setup** (func(*Env) error) - Is called, if not nil, to complete any setup required for a test. The WorkDir and Vars fields will have already been initialized and all the files extracted into WorkDir, and Cd will be the same as WorkDir. The Setup function may modify Vars and Cd as it wishes.
- **Condition** (func(string) (bool, error)) - Is called, if not nil, to determine whether a particular condition is true. It's called only for conditions not in the standard set, and may be nil.
- **Cmds** (map[string]func(*TestScript, bool, []string)) - Holds a map of commands available to the script. It will only be consulted for commands not part of the standard set.
- **TestWork** (bool) - Specifies that working directories should be left intact for later inspection.
- **WorkdirRoot** (string) - Specifies the directory within which scripts' work directories will be created. Setting WorkdirRoot implies TestWork=true. If empty, the work directories will be created inside $GOTMPDIR/go-test-script*, where $GOTMPDIR defaults to os.TempDir().
- **IgnoreMissedCoverage** (bool) - Deprecated: this option is no longer used.
- **UpdateScripts** (bool) - Specifies that if a `cmp` command fails and its second argument refers to a file inside the testscript file, the command will succeed and the testscript file will be updated to reflect the actual content (which could be stdout, stderr or a real file). The content will be quoted with txtar.Quote if needed; a manual change will be needed if it is not unquoted in the script.
- **RequireExplicitExec** (bool) - Requires that commands passed to [Main] must be used in test scripts via `exec cmd` and not simply `cmd`. This can help keep consistency across test scripts as well as keep separate process executions explicit.
- **RequireUniqueNames** (bool) - Requires that names in the txtar archive are unique. By default, later entries silently overwrite earlier ones.
- **ContinueOnError** (bool) - Causes a testscript to try to continue in the face of errors. Once an error has occurred, the script will continue as if in verbose mode.
- **Deadline** (time.Time) - If not zero, specifies the time at which the test run will have exceeded the timeout. It is equivalent to testing.T's Deadline method, and Run will set it to the method's return value if this field is zero.
```

--------------------------------

### Server Type and Constructor Functions

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/goproxytest

This section details the Server type and its associated constructor functions, NewServer and NewTestServer, used to initiate the Go module proxy.

```APIDOC
## Type: Server

```go
type Server struct {
	URL string
	// contains filtered or unexported fields
}
```

### Function: NewServer

```go
func NewServer(dir, addr string) (*Server, error)
```

**Description:** Starts the Go module proxy listening on the given network address. It serves modules taken from the given directory name. If addr is empty, it will listen on an arbitrary localhost port. If dir is empty, "testmod" will be used. The returned Server should be closed after use.

### Function: NewTestServer

```go
func NewTestServer(tb testing.TB, dir, addr string) *Server
```

**Description:** A wrapper around NewServer for use in Go tests. Failure to start the server stops the test via testing.TB.Fatalf, all server logs go through testing.TB.Logf, and the server is closed when the test finishes via testing.TB.Cleanup. Added in v1.13.0.
```

--------------------------------

### Define Supported Constant

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript/internal/pty

Indicates whether the current platform supports pseudo-terminals.

```go
const Supported = true
```

--------------------------------

### File System and Path Methods

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Methods for resolving paths and reading file contents relative to the test script directory.

```APIDOC
## MkAbs

### Description
Interprets a file path relative to the test script's current directory and returns the absolute path.

### Parameters
- **file** (string) - Required - The relative file path.

### Response
- **string** - The absolute path.

## ReadFile

### Description
Returns the contents of the file with the given name. Interprets 'stdout' and 'stderr' as standard output/error from the most recent command.

### Parameters
- **file** (string) - Required - The name of the file to read.

### Response
- **string** - The contents of the file.
```

--------------------------------

### Compare Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/semver

Compares two semantic version strings and returns an integer result.

```go
func Compare(v, w string) int
```

--------------------------------

### Run Specific Test Script

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

To run a specific script (e.g., `foo.txtar` or `foo.txt`), use `go test` with the `-run` flag, matching the test name and script name.

```bash
go test cmd/go -run=TestName/^foo$
```

--------------------------------

### Lookup action ID

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Retrieves the output ID and file size for a given action ID.

```go
func (c *Cache) Get(id ActionID) (Entry, error)
```

--------------------------------

### NewHash Constructor

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Creates a new hash instance for a given name.

```go
func NewHash(name string) *Hash
```

--------------------------------

### EncodeVersion Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Encodes a version string.

```go
func EncodeVersion(v string) (encoding string, err error)
```

--------------------------------

### Environment Variables in Test Scripts

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Lists common environment variables available to test scripts, including WORK, PATH, HOME, TMPDIR, and devnull. These variables provide context and temporary storage for test execution.

```go
PATH=<actual PATH>
HOME=/no-home (USERPROFILE on windows, home on plan9)
TMPDIR=$WORK/.tmp (TMP on windows)
devnull=<value of os.DevNull>
/=<value of os.PathSeparator>
:=<value of os.PathListSeparator>
$
```

--------------------------------

### Sort Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Sorts a list of versions.

```go
func Sort(list []Version)
```

--------------------------------

### Sysdll Package Overview

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/internal/syscall/windows/sysdll

Provides an overview of the sysdll package's purpose and functionality.

```APIDOC
## Package sysdll

### Overview

Package sysdll is an internal leaf package that records and reports which Windows DLL names are used by Go itself. These DLLs are then only loaded from the System32 directory. See Issue 14959.

### Variables

```go
var IsSystemDLL = map[string]bool{}
```

IsSystemDLL reports whether the named dll key (a base name, like "foo.dll") is a system DLL which should only be loaded from the Windows SYSTEM32 directory. Filenames are case sensitive, but that doesn't matter because the case registered with Add is also the same case used with LoadDLL later. It has no associated mutex and should only be mutated serially (currently: during init), and not concurrent with DLL loading.
```

--------------------------------

### Look function for finding executables

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/internal/os/execpath

Searches for an executable named file, using getenv to look up environment variables. If getenv is nil, os.Getenv will be used. If file contains a slash, it is tried directly and getenv will not be called. The result may be an absolute path or a path relative to the current directory.

```go
func Look(file string, getenv func(string) string) (string, error)
```

--------------------------------

### Open cache directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Opens a cache in the specified directory. Safe for concurrent local process access but not for network file systems.

```go
func Open(dir string) (*Cache, error)
```

--------------------------------

### Retrieve default cache directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Returns the effective GOCACHE setting or "off" if disabled.

```go
func DefaultDir() string
```

--------------------------------

### CheckPath Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Validates a module path.

```go
func CheckPath(path string) error
```

--------------------------------

### Run Tests with Interface

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

RunT is similar to Run but utilizes an interface type instead of *testing.T, allowing testscript functionality to be used outside of the standard 'go test' command.

```go
func RunT(t T, p Params)
```

--------------------------------

### CanonicalVersion Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Returns the canonical form of a version string.

```go
func CanonicalVersion(v string) string
```

--------------------------------

### Run Filesystem-Based Tests

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Invoke filesystem-based tests by calling `testscript.Run` with test parameters. Ensure the `Dir` parameter points to the test data directory.

```go
func TestFoo(t *testing.T) {
	testscript.Run(t, testscript.Params{
		Dir: "testdata",
	})
}
```

--------------------------------

### Create a Mutex for a Path

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/lockedfile

Returns a new Mutex instance configured for the specified file path. The path must be non-empty and is used for the well-known lock file.

```go
func MutexAt(path string) *Mutex
```

--------------------------------

### func Run

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Executes a script-based test using the provided parameters.

```APIDOC
## func Run

### Description
Runs a script-based test within the context of a *testing.T object using the specified Params.

### Signature
func Run(t *testing.T, p Params)
```

--------------------------------

### Change Script Directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Updates the current working directory for the script.

```go
func (ts *TestScript) Chdir(dir string) error
```

--------------------------------

### RunMain Function (Deprecated)

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Deprecated function for running tests and returning exit codes. Use Main instead.

```APIDOC
## RunMain Function (Deprecated)

### Description
Deprecated: use Main, as the only reason for returning exit codes was to collect full code coverage, which Go does automatically now: https://go.dev/blog/integration-test-coverage

### Method
GET

### Endpoint
/runmain

### Parameters
#### Path Parameters
- **m** (TestingM) - The testing interface.
- **commands** (map[string]func() int) - A map of command names to functions returning exit codes.

### Returns
- **exitCode** (int) - The exit code of the test run.
```

--------------------------------

### Register System DLL

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/internal/syscall/windows/sysdll

Registers a DLL name as a system32 DLL. It returns the input string to facilitate use in generated code.

```go
func Add(dll string) string
```

--------------------------------

### func Look

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/internal/os/execpath

Searches for an executable file using a provided environment lookup function.

```APIDOC
## func Look(file string, getenv func(string) string) (string, error)

### Description
Look searches for an executable named file, using getenv to look up environment variables. If getenv is nil, os.Getenv will be used. If file contains a slash, it is tried directly and getenv will not be called. The result may be an absolute path or a path relative to the current directory.

### Parameters
- **file** (string) - Required - The name of the executable to search for.
- **getenv** (func(string) string) - Optional - A function to look up environment variables. If nil, os.Getenv is used.

### Response
- **string** - The absolute or relative path to the executable.
- **error** - Returns ErrNotFound if the executable is not found.
```

--------------------------------

### Deprecated RunMain Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Deprecated: Use Main instead. RunMain was used for collecting full code coverage, which Go now handles automatically.

```go
func RunMain(m TestingM, commands map[string]func() int) (exitCode int)
```

--------------------------------

### Functions

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/dirhash

Core functions for hashing directories and files.

```APIDOC
## Functions

### DirFiles

```go
func DirFiles(dir, prefix string) ([]string, error)
```

**Description**: Lists files in a directory, optionally with a prefix. Returns a slice of file paths and an error if any occurs.
```

```APIDOC
### Hash1

```go
func Hash1(files []string, open func(string) (io.ReadCloser, error)) (string, error)
```

**Description**: Computes a hash for a given list of files using a provided open function. Returns the hash string and an error.
```

```APIDOC
### HashDir

```go
func HashDir(dir, prefix string, hash Hash) (string, error)
```

**Description**: Computes a hash for a directory's contents using a specified hash algorithm. Returns the hash string and an error.
```

```APIDOC
### HashZip

```go
func HashZip(zipfile string, hash Hash) (string, error)
```

**Description**: Computes a hash for a zip file's contents using a specified hash algorithm. Returns the hash string and an error.
```

--------------------------------

### Archive a directory with txtar-c

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cmd/txtar-c

Use this command to archive a directory tree and redirect the output to a file.

```bash
txtar-c /path/to/dir >saved.txtar
```

--------------------------------

### OpenFile with Locking

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/lockedfile

Opens a file with specified flags and permissions, returning a locked file. The lock type (read or write) depends on the flags provided.

```go
func OpenFile(name string, flag int, perm fs.FileMode) (*File, error)
```

--------------------------------

### Run Tests in Directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

RunDir executes tests within a specified directory. It considers all files with .txt or .txtar extensions as test files.

```go
func Run(t *testing.T, p Params)
```

--------------------------------

### MatchPathMajor Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Checks if a version matches a major path version.

```go
func MatchPathMajor(v, pathMajor string) bool
```

--------------------------------

### Run Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Runs tests in a specified directory. All .txt and .txtar files are considered test files.

```APIDOC
## Run Function

### Description
RunDir runs the tests in the given directory. All files in dir with a ".txt" or ".txtar" extension are considered to be test files.

### Method
GET

### Endpoint
/run

### Parameters
#### Query Parameters
- **t** (*testing.T) - The testing object.
- **p** (Params) - Parameters for running the tests.
```

--------------------------------

### Run command in background with name

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Commands can be run in the background using the '&word&` token. This allows for specific waiting or killing of the process using the provided 'word'.

--------------------------------

### Open a Read-Locked File

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/lockedfile

Opens an existing file with a read-lock. Ensure to close the file to release the lock.

```go
func Open(name string) (*File, error)
```

--------------------------------

### Environment Variable Quoting for Regex

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Shows how to use the '@R' suffix to quote environment variable values, which is useful for safely including regexp metacharacters.

```go
${VAR@R}
```

--------------------------------

### ShouldBuild Function Signature

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/imports

Provides the function signature for ShouldBuild. This function determines if a file should be built based on its build tags found in comments.

```go
func ShouldBuild(content []byte, tags map[string]bool) bool
```

--------------------------------

### Add Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/internal/syscall/windows/sysdll

Documentation for the Add function, which registers a DLL as a system DLL.

```APIDOC
## func Add

```go
func Add(dll string) string
```

Add notes that dll is a system32 DLL which should only be loaded from the Windows SYSTEM32 directory. It returns its argument back, for ease of use in generated code.
```

--------------------------------

### Process and I/O Management

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Commands for executing external processes, managing standard input/output, and interacting with pseudo-terminals.

```APIDOC
## EXEC

### Description
Executes a command. If the last token is '&word&` (where "word" is alphanumeric), the command runs in the background and can be waited for or terminated.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **command** (string) - Required - The command to execute.
- **&word&** (string) - Optional - If present, runs the command in the background.

### Request Example
```
exec echo "hello"
exec sleep 5 &background_job
```

## STDIN

### Description
Sets the standard input for the next exec command to the contents of the given file.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file** (string) - Required - The file to use as standard input. Can be "stdout" or "stderr" to use the standard output or standard error from the most recent exec or wait command.

### Request Example
```
stdin input.txt
exec my_command
```

## TTYIN

### Description
Attaches the next exec command to a controlling pseudo-terminal and uses the contents of the given file as the raw terminal input.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file** (string) - Required - The file containing raw terminal input.
- **-stdin** (flag) - Optional - If specified, also attach the terminal to standard input.

### Request Example
```
ttyin -stdin input.txt
exec interactive_command
```

## TTYOUT

### Description
Applies the grep command to the raw controlling terminal output from the most recent exec command.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **pattern** (string) - Required - The pattern to grep for.
- **-count=N** (integer) - Optional - Specifies an exact number of matches to require.

### Request Example
```
ttyout "error" -count=1
```
```

--------------------------------

### Format Archive

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/txtar

Serializes an Archive structure into its byte representation.

```go
func Format(a *Archive) []byte
```

--------------------------------

### Generate subkey

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Creates an action ID by mixing a parent ID with a string description.

```go
func Subkey(parent ActionID, desc string) ActionID
```

--------------------------------

### Declare KnownOS, UnixOS, and KnownArch Variables

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/imports

Declares global maps for tracking operating systems and architectures. These are typically initialized and used throughout the package for system-specific logic.

```go
var (
	KnownOS   = make(map[string]bool)
	UnixOS    = make(map[string]bool)
	KnownArch = make(map[string]bool)
)
```

--------------------------------

### Write Hash Data

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Writes data to the running hash instance.

```go
func (h *Hash) Write(b []byte) (int, error)
```

--------------------------------

### Variables

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/dirhash

Provides access to the default hash implementation.

```APIDOC
## Variables

### DefaultHash

```go
var DefaultHash = dirhash.Hash1
```

**Description**: The default hash implementation used by the package.
```

--------------------------------

### Major Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/semver

Returns the major version component of a semantic version string.

```go
func Major(v string) string
```

--------------------------------

### EncodePath Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Encodes a module path.

```go
func EncodePath(path string) (encoding string, err error)
```

--------------------------------

### SplitPathVersion Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Splits a path into its prefix and major version components.

```go
func SplitPathVersion(path string) (prefix, pathMajor string, ok bool)
```

--------------------------------

### Set file hash

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Manually sets the hash value for a specific file.

```go
func SetFileHash(file string, sum [HashSize]byte)
```

--------------------------------

### CheckFilePath Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/module

Validates a file path.

```go
func CheckFilePath(path string) error
```

--------------------------------

### MatchFile Function Signature

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/imports

Provides the function signature for MatchFile. This function determines if a filename matches the current operating system and architecture, considering GOOS and GOARCH environment variables and specific naming conventions.

```go
func MatchFile(name string, tags map[string]bool) bool
```

--------------------------------

### File and Directory Operations

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript

Commands for checking file existence, manipulating file content, and managing directories.

```APIDOC
## EXISTS

### Description
Checks if files or directories exist.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file...** (string) - Required - The files or directories to check.
- **-readonly** (flag) - Optional - If given, the files or directories must be unwritable.

### Request Example
```
exists file1.txt
exists -readonly protected_file.txt
```

## RM

### Description
Removes the listed files or directories.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file...** (string) - Required - The files or directories to remove.

### Request Example
```
rm file1.txt dir1/
```

## MV

### Description
Renames a file or directory.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **path1** (string) - Required - The source path.
- **path2** (string) - Required - The destination path.

### Request Example
```
mv old_name.txt new_name.txt
```

## MKDIR

### Description
Creates the listed directories if they do not already exist.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **path...** (string) - Required - The directories to create.

### Request Example
```
mkdir new_dir/
```

## SYMLINK

### Description
Creates a symbolic link.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file** (string) - Required - The name of the symlink to create.
- **->** (literal) - Required - Separator.
- **target** (string) - Required - The target of the symlink.

### Request Example
```
symlink link_name -> target_file
```

## UNQUOTE

### Description
Rewrites each file by replacing any leading ">" characters from each line.

### Method
N/A (Command)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **file...** (string) - Required - The files to rewrite.

### Request Example
```
unquote file.txt
```
```

--------------------------------

### Define Server Struct - goproxytest

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/goproxytest

Represents the Go module proxy server. It contains the URL of the running proxy.

```go
type Server struct {
	URL string
	// contains filtered or unexported fields
}
```

--------------------------------

### OutputFile Path Retrieval

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/cache

Returns the file path for a specific output ID.

```go
func (c *Cache) OutputFile(out OutputID) string
```

--------------------------------

### AutoQuote function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/modfile

Returns a quoted string if necessary.

```go
func AutoQuote(s string) string
```

--------------------------------

### File interface definition

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/lockedfile/internal/filelock

Defines the minimal set of methods required for an object to be used with the filelock package.

```go
type File interface {
	// Name returns the name of the file.
	Name() string

	// Fd returns a valid file descriptor.
	// (If the File is an *os.File, it must not be closed.)
	Fd() uintptr

	// Stat returns the FileInfo structure describing file.
	Stat() (fs.FileInfo, error)
}
```

--------------------------------

### IsDirectoryPath function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/modfile

Checks if the provided string represents a directory path.

```go
func IsDirectoryPath(ns string) bool
```

--------------------------------

### Write data to file atomically

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/renameio

Writes a byte slice to a temporary file before renaming it to the target filename, ensuring atomic updates.

```go
func WriteFile(filename string, data []byte) (err error)
```

--------------------------------

### ParseGopkgIn function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/modfile

Splits gopkg.in import paths into their constituent parts.

```go
func ParseGopkgIn(path string) (root, repo, major, subdir string, ok bool)
```

--------------------------------

### Write Archive to Directory

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/txtar

Writes all files within an Archive to a specified directory.

```go
func Write(a *Archive, dir string) error
```

--------------------------------

### Hash1 Function Signature

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/dirhash

This function signature shows Hash1 takes a slice of file paths and an open function, returning a hash string and an error. It's used for hashing files.

```go
func Hash1(files []string, open func(string) (io.ReadCloser, error)) (string, error)
```

--------------------------------

### Canonical Function

Source: https://pkg.go.dev/github.com/rogpeppe/go-internal/semver

Returns the canonical form of a semantic version string.

```go
func Canonical(v string) string
```
Tokens:
Raw