regtest

Documentation

Overview

Package regtest provides an environment for writing regression tests.

Index

• type DiagnosticExpectation
  • func DiagnosticAt(name string, line, col int) DiagnosticExpectation
  • func EmptyDiagnostics(name string) DiagnosticExpectation
• type Env
  • func NewEnv(ctx context.Context, t *testing.T, ws *fake.Workspace, ts servertest.Connector) *Env
  • func (e *Env) AnyDiagnosticAtCurrentVersion(name string) DiagnosticExpectation
  • func (e *Env) Await(expectations ...DiagnosticExpectation)
  • func (e *Env) CloseBuffer(name string)
  • func (e *Env) CloseEditor()
  • func (e *Env) CreateBuffer(name string, content string)
  • func (e *Env) DiagnosticAtRegexp(name, re string) DiagnosticExpectation
  • func (e *Env) EditBuffer(name string, edits ...fake.Edit)
  • func (e *Env) ExpectDiagnostics(expectations ...DiagnosticExpectation)
  • func (e *Env) FormatBuffer(name string)
  • func (e *Env) GoToDefinition(name string, pos fake.Pos) (string, fake.Pos)
  • func (e *Env) OpenFile(name string)
  • func (e *Env) OrganizeImports(name string)
  • func (e *Env) ReadWorkspaceFile(name string) string
  • func (e *Env) RegexpReplace(name, regexpStr, replace string)
  • func (e *Env) RegexpSearch(name, re string) fake.Pos
  • func (e *Env) RemoveFileFromWorkspace(name string)
  • func (e *Env) SaveBuffer(name string)
• type EnvMode
• type Runner
  • func NewTestRunner(modes EnvMode, testTimeout time.Duration, goplsPath string) *Runner
  • func (r *Runner) Close() error
  • func (r *Runner) Modes() EnvMode
  • func (r *Runner) Run(t *testing.T, filedata string, test func(e *Env))
  • func (r *Runner) RunInMode(modes EnvMode, t *testing.T, filedata string, test func(e *Env))

Types

type DiagnosticExpectation

type DiagnosticExpectation struct {
	// IsMet determines whether the diagnostics for this file version satisfy our
	// expectation.
	IsMet func(*protocol.PublishDiagnosticsParams) bool
	// Description is a human-readable description of the diagnostic expectation.
	Description string
	// Path is the workspace-relative path to the file being asserted on.
	Path string
}

A DiagnosticExpectation is a condition that must be met by the current set of diagnostics.

func DiagnosticAt

func DiagnosticAt(name string, line, col int) DiagnosticExpectation

DiagnosticAt asserts that there is a diagnostic entry at the position specified by line and col, for the workspace-relative path name.

func EmptyDiagnostics

func EmptyDiagnostics(name string) DiagnosticExpectation

EmptyDiagnostics asserts that diagnostics are empty for the workspace-relative path name.

type Env

type Env struct {
	T   *testing.T
	Ctx context.Context

	// Most tests should not need to access the workspace, editor, server, or
	// connection, but they are available if needed.
	W      *fake.Workspace
	E      *fake.Editor
	Server servertest.Connector
	Conn   *jsonrpc2.Conn
	// contains filtered or unexported fields
}

Env holds an initialized fake Editor, Workspace, and Server, which may be used for writing tests. It also provides adapter methods that call t.Fatal on any error, so that tests for the happy path may be written without checking errors.

func NewEnv

func NewEnv(ctx context.Context, t *testing.T, ws *fake.Workspace, ts servertest.Connector) *Env

NewEnv creates a new test environment using the given workspace and gopls server.

func (*Env) AnyDiagnosticAtCurrentVersion

func (e *Env) AnyDiagnosticAtCurrentVersion(name string) DiagnosticExpectation

AnyDiagnosticAtCurrentVersion asserts that there is a diagnostic report for the current edited version of the buffer corresponding to the given workspace-relative pathname.

func (*Env) Await

func (e *Env) Await(expectations ...DiagnosticExpectation)

Await waits for all diagnostic expectations to simultaneously be met. It should only be called from the main test goroutine.

func (*Env) CloseBuffer

func (e *Env) CloseBuffer(name string)

CloseBuffer closes an editor buffer without saving, calling t.Fatal on any error.

func (*Env) CloseEditor

func (e *Env) CloseEditor()

CloseEditor shuts down the editor, calling t.Fatal on any error.

func (*Env) CreateBuffer

func (e *Env) CreateBuffer(name string, content string)

CreateBuffer creates a buffer in the editor, calling t.Fatal on any error.

func (*Env) DiagnosticAtRegexp

func (e *Env) DiagnosticAtRegexp(name, re string) DiagnosticExpectation

DiagnosticAtRegexp expects that there is a diagnostic entry at the start position matching the regexp search string re in the buffer specified by name. Note that this currently ignores the end position.

func (*Env) EditBuffer

func (e *Env) EditBuffer(name string, edits ...fake.Edit)

EditBuffer applies edits to an editor buffer, calling t.Fatal on any error.

func (*Env) ExpectDiagnostics

func (e *Env) ExpectDiagnostics(expectations ...DiagnosticExpectation)

ExpectDiagnostics asserts that the current diagnostics in the editor match the given expectations. It is intended to be used together with Env.Await to allow waiting on simpler diagnostic expectations (for example, AnyDiagnosticsACurrenttVersion), followed by more detailed expectations tested by ExpectDiagnostics.

For example:

env.RegexpReplace("foo.go", "a", "x")
env.Await(env.AnyDiagnosticAtCurrentVersion("foo.go"))
env.ExpectDiagnostics(env.DiagnosticAtRegexp("foo.go", "x"))

This has the advantage of not timing out if the diagnostic received for "foo.go" does not match the expectation: instead it fails early.

func (*Env) FormatBuffer

func (e *Env) FormatBuffer(name string)

FormatBuffer formats the editor buffer, calling t.Fatal on any error.

func (*Env) GoToDefinition

func (e *Env) GoToDefinition(name string, pos fake.Pos) (string, fake.Pos)

GoToDefinition goes to definition in the editor, calling t.Fatal on any error.

func (*Env) OpenFile

func (e *Env) OpenFile(name string)

OpenFile opens a file in the editor, calling t.Fatal on any error.

func (*Env) OrganizeImports

func (e *Env) OrganizeImports(name string)

OrganizeImports processes the source.organizeImports codeAction, calling t.Fatal on any error.

func (*Env) ReadWorkspaceFile

func (e *Env) ReadWorkspaceFile(name string) string

ReadWorkspaceFile reads a file from the workspace, calling t.Fatal on any error.

func (*Env) RegexpReplace

func (e *Env) RegexpReplace(name, regexpStr, replace string)

RegexpReplace replaces the first group in the first match of regexpStr with the replace text, calling t.Fatal on any error.

func (*Env) RegexpSearch

func (e *Env) RegexpSearch(name, re string) fake.Pos

RegexpSearch returns the starting position of the first match for re in the buffer specified by name, calling t.Fatal on any error. It first searches for the position in open buffers, then in workspace files.

func (*Env) RemoveFileFromWorkspace

func (e *Env) RemoveFileFromWorkspace(name string)

RemoveFileFromWorkspace deletes a file on disk but does nothing in the editor. It calls t.Fatal on any error.

func (*Env) SaveBuffer

func (e *Env) SaveBuffer(name string)

SaveBuffer saves an editor buffer, calling t.Fatal on any error.

type EnvMode

type EnvMode int

EnvMode is a bitmask that defines in which execution environments a test should run.

const (
	// Singleton mode uses a separate cache for each test.
	Singleton EnvMode = 1 << iota

	// Forwarded forwards connections to an in-process gopls instance.
	Forwarded
	// SeparateProcess runs a separate gopls process, and forwards connections to
	// it.
	SeparateProcess
	// NormalModes runs tests in all modes.
	NormalModes = Singleton | Forwarded
)

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

A Runner runs tests in gopls execution environments, as specified by its modes. For modes that share state (for example, a shared cache or common remote), any tests that execute on the same Runner will share the same state.

func NewTestRunner

func NewTestRunner(modes EnvMode, testTimeout time.Duration, goplsPath string) *Runner

NewTestRunner creates a Runner with its shared state initialized, ready to run tests.

func (*Runner) Close

func (r *Runner) Close() error

Close cleans up resource that have been allocated to this workspace.

func (*Runner) Modes

func (r *Runner) Modes() EnvMode

Modes returns the bitmask of environment modes this runner is configured to test.

func (*Runner) Run

func (r *Runner) Run(t *testing.T, filedata string, test func(e *Env))

Run executes the test function in the default configured gopls execution modes. For each a test run, a new workspace is created containing the un-txtared files specified by filedata.

func (*Runner) RunInMode

func (r *Runner) RunInMode(modes EnvMode, t *testing.T, filedata string, test func(e *Env))

RunInMode runs the test in the execution modes specified by the modes bitmask.