From bdde1628ed1d83ecff963c6bf69b117122e31791 Mon Sep 17 00:00:00 2001
From: Jean de Klerk <deklerk@google.com>
Date: Tue, 24 Nov 2020 16:08:12 -0700
Subject: [PATCH] internal/lsp: add READMEs that describe tests, how to run
 tests

I've recently started working on gopls. It's been a fantastic
experience, but the testing strategies here have required non-trivial
mental work to understand. (thanks Rebecca for all your help!)

Now that I understand the testing a bit better, I wanted to codify it
into a readme for the next person that comes along.

I've taken a stab at that: please feel free to suggest heavy edits,
it's just a best-effort attempt.

Change-Id: Ib739d40ef71018521cd904844443e8c9634a10a6
Reviewed-on: https://go-review.googlesource.com/c/tools/+/273066
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
Reviewed-by: Robert Findley <rfindley@google.com>
Trust: Jean de Klerk <deklerk@google.com>
---
 gopls/doc/contributing.md    | 19 +++++++++++
 internal/lsp/README.md       |  7 ++++
 internal/lsp/tests/README.md | 66 ++++++++++++++++++++++++++++++++++++
 3 files changed, 92 insertions(+)
 create mode 100644 internal/lsp/README.md
 create mode 100644 internal/lsp/tests/README.md

diff --git a/gopls/doc/contributing.md b/gopls/doc/contributing.md
index 3f40fc7372..89b42257d2 100644
--- a/gopls/doc/contributing.md
+++ b/gopls/doc/contributing.md
@@ -14,6 +14,25 @@ Before you begin working on an issue, please leave a comment that you are claimi
 Provide information to get contributors up and running here
 --->
 
+## Testing
+
+To run tests for just `gopls/`, run,
+
+```
+cd /path/to/tools/gopls
+go test ./...
+```
+
+But, much of the gopls work involves `internal/lsp` too, so you might want to
+run both:
+
+```
+cd /path/to/tools
+cd gopls && go test ./...
+cd ..
+go test ./internal/lsp/...
+```
+
 ## Debugging
 
 <!--- TODO: debugging
diff --git a/internal/lsp/README.md b/internal/lsp/README.md
new file mode 100644
index 0000000000..34a142cbbe
--- /dev/null
+++ b/internal/lsp/README.md
@@ -0,0 +1,7 @@
+# lsp
+
+internal/lsp provides much of the Language Server Protocol (lsp) implementation
+for gopls.
+
+Documentation for users and contributors can be found in the
+[`gopls/doc`](../../gopls/doc) directory.
diff --git a/internal/lsp/tests/README.md b/internal/lsp/tests/README.md
new file mode 100644
index 0000000000..31268a962f
--- /dev/null
+++ b/internal/lsp/tests/README.md
@@ -0,0 +1,66 @@
+## 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: https://pkg.go.dev/golang.org/x/tools/internal/lsp/tests#Data.Golden.
+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](https://github.com/golang/tools/blob/299f270db45902e93469b1152fafed034bb3f033/internal/lsp/tests/tests.go#L418-L447).
+
+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
+```
\ No newline at end of file