github.com/v2fly/tools@v0.100.0/internal/lsp/regtest/doc.go (about)

     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 github.com/v2fly/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