From 2acb2e697b49f179be93652febb89d384f0f09c9 Mon Sep 17 00:00:00 2001 From: Rob Findley Date: Tue, 12 Dec 2023 12:24:30 -0500 Subject: [PATCH] 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 LUCI-TryBot-Result: Go LUCI Auto-Submit: Robert Findley --- gopls/internal/test/marker/doc.go | 53 +++++++++-------------- gopls/internal/test/marker/marker_test.go | 23 ++++++++++ 2 files changed, 44 insertions(+), 32 deletions(-) diff --git a/gopls/internal/test/marker/doc.go b/gopls/internal/test/marker/doc.go index 755812fd592..bf8b3634809 100644 --- a/gopls/internal/test/marker/doc.go +++ b/gopls/internal/test/marker/doc.go @@ -33,35 +33,14 @@ which is extracted to a temporary directory. The relative path to the .txt 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 @@ treatment by the test runner: -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://. @@ -309,11 +295,14 @@ parameter type pairs: 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 @@ The first argument holds the test context, including fake editor with open 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 2fa4197550e..ce7950703c3 100644 --- a/gopls/internal/test/marker/marker_test.go +++ b/gopls/internal/test/marker/marker_test.go @@ -59,6 +59,29 @@ func TestMain(m *testing.M) { // 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)