evaltest

Documentation

Overview

Package evaltest supports testing the Elvish interpreter and libraries.

Index

• func TestTranscriptsInFS(t *testing.T, fsys fs.FS, setupPairs ...any)

Functions

func TestTranscriptsInFS

func TestTranscriptsInFS(t *testing.T, fsys fs.FS, setupPairs ...any)

TestTranscriptsInFS extracts all Elvish transcript sessions from .elv and .elvts files in fsys, and runs each of them as a test. See src.elv.sh/pkg/transcript for how transcript sessions are discovered.

Typical use of this function looks like this:

import (
	"embed"
	"src.elv.sh/pkg/eval/evaltest"
)

//go:embed *.elv *.elvts
var transcripts embed.FS

func TestTranscripts(t *testing.T) {
	evaltest.TestTranscriptsInFS(t, transcripts)
}

The function accepts variadic arguments in (name, f) pairs, where name must not contain any spaces. Each pair defines a setup function that may be referred to in the transcripts with the directive "//name".

The setup function f may take a *testing.T, *eval.Evaler and a string argument. All of them are optional but must appear in that order. If it takes a string argument, the directive can be followed by an argument after a space ("//name argument"), and that argument is passed to f. The argument itself may contain spaces.

The following setup functions are predefined:

• in-temp-dir: Run inside a temporary directory.

• set-env $name $value: Run with the environment variable $name set to $value.

• unset-env $name: Run with the environment variable $name unset.

• eval $code: Evaluate the argument as Elvish code.

• only-on $cond: Evaluate $cond like a //go:build constraint and only run the test if the constraint is satisfied.

  The full build constraint syntax is supported, but only literal GOARCH and GOOS values and "unix" are recognized as tags; other tags are always false.

• deprecation-level $x: Run with deprecation level set to $x.

Since directives in a higher level propagated to all its descendants, this mechanism can be used to specify setup functions that apply to an entire .elvts file (or an entire elvish-transcript code block in a .elv file) or an entire section:

//global-setup

# h1 #
//h1-setup

## h2 ##
//h2-setup

// All of top-setup, h1-setup and h2-setup are run for this session, in that
// order.

~> echo foo
foo