History

Rebecca Stambler d78b04bdf9 gopls/doc: clean up and slightly reorganize documentation This is a first CL to clean up the gopls documentation. The main changes are cosmetic (to correct warnings found by the MD Lint VS Code extension), though some parts are reworded or moved around. Ultimately, more work needs to be done, particularly on the user guide and features overview. My current thinking is that we should rename settings.md to configuration and move the configuration piece out of the user guide, and also reorganize the user guide to be more "getting started" oriented. I'm still not sure where miscellaneous items should go (e.g., working on the Go distribution itself)--I deleted the FAQ because it seemed useless and is probably not the most discoverable, but it's the only place that comes to mind so far. Change-Id: I3689362067672f7ad8d5e8fd97ca9c7c45cfc8c4 Reviewed-on: https://go-review.googlesource.com/c/tools/+/280595 Trust: Rebecca Stambler <rstambler@golang.org> Run-TryBot: Rebecca Stambler <rstambler@golang.org> Reviewed-by: Robert Findley <rfindley@google.com>		2021-01-14 06:55:38 +00:00
..
README.md	gopls/doc: clean up and slightly reorganize documentation	2021-01-14 06:55:38 +00:00
normalizer.go	internal/lsp: rewrite the workspace symbol marker tests	2020-11-24 17:38:01 +00:00
tests.go	internal/lsp/source: do not panic in "var func" outgoing callhierarchy	2020-12-26 21:56:59 +00:00
util.go	internal/lsp, gopls: recover from go-diff panics	2020-12-17 16:56:54 +00:00

README.md

Testing

LSP has "marker tests" defined in internal/lsp/testdata, as well as traditional tests.

Marker tests

Marker tests have a standard input file, like internal/lsp/testdata/foo/bar.go, and some may have a corresponding golden file, like internal/lsp/testdata/foo/bar.go.golden. The former is the "input" and the latter is the expected output.

Each input file contains annotations like //@suggestedfix("}", "refactor.rewrite"). These annotations are interpreted by test runners to perform certain actions. The expected output after those actions is encoded in the golden file.

When tests are run, each annotation results in a new subtest, which is encoded in the golden file with a heading like,

-- suggestedfix_bar_11_21 --
// expected contents go here
-- suggestedfix_bar_13_20 --
// expected contents go here

The format of these headings vary: they are defined by the Golden function for each annotation. In the case above, the format is: annotation name, file name, annotation line location, annotation character location.

So, if internal/lsp/testdata/foo/bar.go has three suggestedfix annotations, the golden file should have three headers with suggestedfix_bar_xx_yy headings.

To see a list of all available annotations, see the exported "expectations" in tests.go.

To run marker tests,

cd /path/to/tools

# The marker tests are located in "internal/lsp", "internal/lsp/cmd, and
# "internal/lsp/source".
go test ./internal/lsp/...

There are quite a lot of marker tests, so to run one individually, pass the test path and heading into a -run argument:

cd /path/to/tools
go test ./internal/lsp -v -run TestLSP/Modules/SuggestedFix/bar_11_21

Resetting marker tests

Sometimes, a change is made to lsp that requires a change to multiple golden files. When this happens, you can run,

cd /path/to/tools
./internal/lsp/reset_golden.sh