.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools/gopls@v0.5.2/internal/regtest/doc.go

   1 // Copyright 2020 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 // Package regtest provides a framework for writing gopls regression tests.
   6 //
   7 // User reported regressions are often expressed in terms of editor
   8 // interactions. For example: "When I open my editor in this directory,
   9 // navigate to this file, and change this line, I get a diagnostic that doesn't
  10 // make sense". In these cases reproducing, diagnosing, and writing a test to
  11 // protect against this regression can be difficult.
  12 //
  13 // The regtest package provides an API for developers to express these types of
  14 // user interactions in ordinary Go tests, validate them, and run them in a
  15 // variety of execution modes (see gopls/doc/daemon.md for more information on
  16 // execution modes). This is achieved roughly as follows:
  17 //  + the Runner type starts and connects to a gopls instance for each
  18 //    configured execution mode.
  19 //  + the Env type provides a collection of resources to use in writing tests
  20 //    (for example a temporary working directory and fake text editor)
  21 //  + user interactions with these resources are scripted using test wrappers
  22 //    around the API provided by the golang.org/x/tools/internal/lsp/fake
  23 //    package.
  24 //
  25 // Regressions are expressed in terms of Expectations, which at a high level
  26 // are conditions that we expect to be met (or not to be met) at some point
  27 // after performing the interactions in the test. This is necessary because the
  28 // LSP is by construction asynchronous: both client and server can send
  29 // eachother notifications without formal acknowledgement that they have been
  30 // fully processed.
  31 //
  32 // Simple Expectations may be combined to match specific conditions reported by
  33 // the user. In the example above, a regtest validating that the user-reported
  34 // bug had been fixed would "expect" that the editor never displays the
  35 // confusing diagnostic.
  36 package regtest