gopls/internal/test/marker: minor clean up of marker test doc
Change-Id: Id5fd8592a207e8ade8aeb1521730e4f35514824e
Reviewed-on: https://go-review.googlesource.com/c/tools/+/549120
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Robert Findley <rfindley@google.com>
diff --git a/gopls/internal/test/marker/doc.go b/gopls/internal/test/marker/doc.go
index 755812f..bf8b363 100644
--- a/gopls/internal/test/marker/doc.go
+++ b/gopls/internal/test/marker/doc.go
@@ -33,35 +33,14 @@
file is used as the subtest name. The preliminary section of the file
(before the first archive entry) is a free-form comment.
-These tests were inspired by (and in many places copied from) a previous
-iteration of the marker tests built on top of the packagestest framework.
-Key design decisions motivating this reimplementation are as follows:
- - The old tests had a single global session, causing interaction at a
- distance and several awkward workarounds.
- - The old tests could not be safely parallelized, because certain tests
- manipulated the server options
- - Relatedly, the old tests did not have a logic grouping of assertions into
- a single unit, resulting in clusters of files serving clusters of
- entangled assertions.
- - The old tests used locations in the source as test names and as the
- identity of golden content, meaning that a single edit could change the
- name of an arbitrary number of subtests, and making it difficult to
- manually edit golden content.
- - The old tests did not hew closely to LSP concepts, resulting in, for
- example, each marker implementation doing its own position
- transformations, and inventing its own mechanism for configuration.
- - The old tests had an ad-hoc session initialization process. The integration
- test environment has had more time devoted to its initialization, and has a
- more convenient API.
- - The old tests lacked documentation, and often had failures that were hard
- to understand. By starting from scratch, we can revisit these aspects.
-
# Special files
There are several types of file within the test archive that are given special
treatment by the test runner:
+
- "skip": the presence of this file causes the test to be skipped, with
the file content used as the skip message.
+
- "flags": this file is treated as a whitespace-separated list of flags
that configure the MarkerTest instance. Supported flags:
-min_go=go1.20 sets the minimum Go version for the test;
@@ -78,21 +57,28 @@
-filter_keywords=false disables the filtering of keywords from
completion results.
TODO(rfindley): support flag values containing whitespace.
+
- "settings.json": this file is parsed as JSON, and used as the
session configuration (see gopls/doc/settings.md)
+
- "capabilities.json": this file is parsed as JSON client capabilities,
and applied as an overlay over the default editor client capabilities.
see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#clientCapabilities
for more details.
+
- "env": this file is parsed as a list of VAR=VALUE fields specifying the
editor environment.
+
- Golden files: Within the archive, file names starting with '@' are
treated as "golden" content, and are not written to disk, but instead are
made available to test methods expecting an argument of type *Golden,
using the identifier following '@'. For example, if the first parameter of
Foo were of type *Golden, the test runner would convert the identifier a
in the call @foo(a, "b", 3) into a *Golden by collecting golden file
- data starting with "@a/".
+ data starting with "@a/". As a special case, for tests that only need one
+ golden file, the data contained in the file "@a" is indexed in the *Golden
+ value by the empty string "".
+
- proxy files: any file starting with proxy/ is treated as a Go proxy
file. If present, these files are written to a separate temporary
directory and GOPROXY is set to file://<proxy directory>.
@@ -309,11 +295,14 @@
Here is a complete example:
+ This test checks hovering over constants.
+
-- a.go --
package a
const abc = 0x2a //@hover("b", "abc", abc),hover(" =", "abc", abc)
- -- @abc/hover.md --
+
+ -- @abc --
```go
const abc untyped int = 42
```
@@ -329,13 +318,13 @@
files, and sandboxed directory.
Argument converters translate the "b" and "abc" arguments into locations by
-interpreting each one as a regular expression and finding the location of
-its first match on the preceding portion of the line, and the abc identifier
-into a dictionary of golden content containing "hover.md". Then the
-hoverMarker method executes a textDocument/hover LSP request at the src
-position, and ensures the result spans "abc", with the markdown content from
-hover.md. (Note that the markdown content includes the expect annotation as
-the doc comment.)
+interpreting each one as a substring (or as a regular expression, if of the
+form re"a|b") and finding the location of its first occurrence on the preceding
+portion of the line, and the abc identifier into a the golden content contained
+in the file @abc. Then the hoverMarker method executes a textDocument/hover LSP
+request at the src position, and ensures the result spans "abc", with the
+markdown content from @abc. (Note that the markdown content includes the expect
+annotation as the doc comment.)
The next hover on the same line asserts the same result, but initiates the
hover immediately after "abc" in the source. This tests that we find the
diff --git a/gopls/internal/test/marker/marker_test.go b/gopls/internal/test/marker/marker_test.go
index 2fa4197..ce79507 100644
--- a/gopls/internal/test/marker/marker_test.go
+++ b/gopls/internal/test/marker/marker_test.go
@@ -59,6 +59,29 @@
// Test runs the marker tests from the testdata directory.
//
// See package documentation for details on how marker tests work.
+//
+// These tests were inspired by (and in many places copied from) a previous
+// iteration of the marker tests built on top of the packagestest framework.
+// Key design decisions motivating this reimplementation are as follows:
+// - The old tests had a single global session, causing interaction at a
+// distance and several awkward workarounds.
+// - The old tests could not be safely parallelized, because certain tests
+// manipulated the server options
+// - Relatedly, the old tests did not have a logic grouping of assertions into
+// a single unit, resulting in clusters of files serving clusters of
+// entangled assertions.
+// - The old tests used locations in the source as test names and as the
+// identity of golden content, meaning that a single edit could change the
+// name of an arbitrary number of subtests, and making it difficult to
+// manually edit golden content.
+// - The old tests did not hew closely to LSP concepts, resulting in, for
+// example, each marker implementation doing its own position
+// transformations, and inventing its own mechanism for configuration.
+// - The old tests had an ad-hoc session initialization process. The integration
+// test environment has had more time devoted to its initialization, and has a
+// more convenient API.
+// - The old tests lacked documentation, and often had failures that were hard
+// to understand. By starting from scratch, we can revisit these aspects.
func Test(t *testing.T) {
// The marker tests must be able to run go/packages.Load.
testenv.NeedsGoPackages(t)
