expect

Documentation

Overview

Package expect provides support for interpreting structured comments in Go source code (including go.mod and go.work files) as test expectations.

This is primarily intended for writing tests of things that process Go source files, although it does not directly depend on the testing package.

Collect notes with the Extract or Parse functions, and use the MatchBefore function to find matches within the lines the comments were on.

The interpretation of the notes depends on the application. For example, the test suite for a static checking tool might use a @diag note to indicate an expected diagnostic:

fmt.Printf("%s", 1) //@ diag("%s wants a string, got int")

By contrast, the test suite for a source code navigation tool might use notes to indicate the positions of features of interest, the actions to be performed by the test, and their expected outcomes:

var x = 1 //@ x_decl
...
print(x) //@ definition("x", x_decl)
print(x) //@ typeof("x", "int")

Note comment syntax

Note comments always start with the special marker @, which must be the very first character after the comment opening pair, so //@ or /*@ with no spaces.

This is followed by a comma separated list of notes.

A note always starts with an identifier, which is optionally followed by an argument list. The argument list is surrounded with parentheses and contains a comma-separated list of arguments. The empty parameter list and the missing parameter list are distinguishable if needed; they result in a nil or an empty list in the Args parameter respectively.

Arguments may be positional, such as f(value), or named, such as f(name=value). Positional arguments must appear before named arguments. Names may not be repeated.

Argument values may be either identifiers or literals. The literals supported are the basic value literals, of string, float, integer true, false or nil. All the literals match the standard go conventions, with all bases of integers, and both quote and backtick strings. There is one extra literal type, which is a string literal preceded by the identifier "re" which is compiled to a regular expression.

Index

• func MatchBefore(fset *token.FileSet, readFile ReadFile, end token.Pos, pattern interface{}) (token.Pos, token.Pos, error)
• type Identifier
• type Note
  • func ExtractGo(fset *token.FileSet, file *ast.File) ([]*Note, error)
  • func Parse(fset *token.FileSet, filename string, content []byte) ([]*Note, error)
• type ReadFile

Functions

func MatchBefore

func MatchBefore(fset *token.FileSet, readFile ReadFile, end token.Pos, pattern interface{}) (token.Pos, token.Pos, error)

MatchBefore attempts to match a pattern in the line before the supplied pos. It uses the FileSet and the ReadFile to work out the contents of the line that end is part of, and then matches the pattern against the content of the start of that line up to the supplied position. The pattern may be either a simple string, []byte or a *regexp.Regexp. MatchBefore returns the range of the line that matched the pattern, and invalid positions if there was no match, or an error if the line could not be found.

Types

type Identifier

type Identifier string

Identifier is the type for an identifier in an Note argument list.

type Note

type Note struct {
	Pos       token.Pos      // The position at which the note identifier appears
	Name      string         // the name associated with the note
	Args      []any          // positional arguments (non-nil if parens were present)
	NamedArgs map[string]any // named arguments (or nil if none)
}

Note is a parsed note from an expect comment. It knows the position of the start of the comment, and the name and arguments that make up the note.

func ExtractGo

func ExtractGo(fset *token.FileSet, file *ast.File) ([]*Note, error)

ExtractGo collects all the notes present in an AST. Each comment whose text starts with @ is parsed as a comma-separated sequence of notes. See the package documentation for details about the syntax of those notes.

func Parse

func Parse(fset *token.FileSet, filename string, content []byte) ([]*Note, error)

Parse collects all the notes present in a file. If content is nil, the filename specified is read and parsed, otherwise the content is used and the filename is used for positions and error messages. Each comment whose text starts with @ is parsed as a comma-separated sequence of notes. See the package documentation for details about the syntax of those notes.

type ReadFile

type ReadFile func(filename string) ([]byte, error)

ReadFile is the type of a function that can provide file contents for a given filename. This is used in MatchBefore to look up the content of the file in order to find the line to match the pattern against.