BSD-3-Clause licensed by Luke Lau
Maintained by [email protected]
This version can be pinned in stack with:lsp-test-,4414

Module documentation for


lsp-test is a functional testing framework for Language Server Protocol servers.

It is part of the lsp family of packages, along with lsp and lsp-types

import Language.LSP.Test
main = runSession "hie" fullCaps "proj/dir" $ do
  doc <- openDoc "Foo.hs" "haskell"
  skipMany anyNotification
  symbols <- getDocumentSymbols doc


Unit tests with HSpec

describe "diagnostics" $
  it "report errors" $ runSession "hie" fullCaps "test/data" $ do
    openDoc "Error.hs" "haskell"
    [diag] <- waitForDiagnosticsSource "ghcmod"
    liftIO $ do
      diag ^. severity `shouldBe` Just DsError
      diag ^. source `shouldBe` Just "ghcmod"

Replaying captured session

replaySession "hie" "test/data/renamePass"

Parsing with combinators

skipManyTill loggingNotification publishDiagnosticsNotification
count 4 (message :: Session ApplyWorkspaceEditRequest)
anyRequest <|> anyResponse

Try out the example tests in the example directory with cabal test. For more examples see this introductory blog post.

Whilst writing your tests you may want to debug them to see what’s going wrong. You can set the logMessages and logStdErr options in SessionConfig to see what the server is up to. There are also corresponding environment variables so you can turn them on from the command line:



The tests for lsp-test use a dummy server found in test/dummy-server/. Run the tests with cabal test or stack test. Tip: If you want to filter the tests, use cabal run test:tests -- -m "foo"


Seeing funny stuff when running lsp-test via stack? If your server is built upon Haskell tooling, keep in mind that stack sets some environment variables related to GHC, and you may want to unset them.


Revision history for lsp-test

  • ignoreRegistrationRequests option to ignore client/registerCapability requests, on by default.
  • New functions setIgnoringRegistrationRequests to change whether such messages are ignored during a Session without having to change the SessionConfig.
  • lsp-test will no longer send workspace/didChangConfiguration notifications unless the server dynamically registers for them.

  • Support newer versions of dependencies.

  • The client configuration is now mandatory and is an Object rather than a Value.
  • lsp-test now responds to workspace/configuration requests.
  • lsp-test does not send a workspace/didChangeConfiguration request on startup.
  • New functions for modifying the client configuration and notifying the server.
  • ignoreLogNotifications is now on by default. Experience shows the norm is to ignore these and it is simpler to turn this on only when they are required.
  • ignoreConfigurationRequests option to ignore workspace/configuration requests, also on by default.
  • New functions setIgnoringLogNotifications and setIgnoringConfigurationRequests to change whether such messages are ignored during a Session without having to change the SessionConfig.

  • Adds helper functions to resolve code lens, code actions, and completion items.

  • Support lsp-types- and lsp-

  • Compatibility with new lsp-types major version.
  • Export runSessionWithConfigCustomProcess to allow modifying the CreateProcess used to start a server
  • Add MonadThrow instance for Session

  • Compatibility with new lsp-types major version.

  • Compatibility with new lsp-types major version. – 2021-07-30

  • Catch IO exception when sending messages to server (#317) (@berberman)
  • Improve error messages on JSON decode failures (#320) (@strager)
  • Add tests for satisfyMaybe (#325) (@strager)
  • Add call hierarchy support (@July541)
  • pass the lspConfig at initialization time as well (@pepeiborra)
  • Semantic tokens support (@michaelpj) – 2021-03-26

  • Update for lsp-types-1.2 (@wz1000)
  • Limit diagnostics by range in getCodeActions (@aufarg)
  • Kill timeout thread to avoid building up thousands of old TimeoutMessages (@wz1000) – 2021-02-14

  • Add support for lsp-types-1.1 (@wz1000)
  • Automatically respond to workspace/applyEdit and window/workDoneProgress/create messages (@wz1000) – 2021-01-25

  • Add getIncompleteProgressSessions to track ongoing progress sessions (@wz1000) – 2020-05-14

  • Replace openDoc' with createDoc which now sends workspace/didChangeWatchedFiles notifications if the server has registered for it
  • Add getRegisteredCapabilities – 2020-05-04

  • Build with new haskell-lsp-0.22 – 2020-03-21

  • Bump constraints for new haskell-lsp – 2020-02-04

  • Bump constraints for new haskell-lsp – 2019-12-29

  • Account for messages received between the initialize request and response. (Though it will throw an exception if the message received is an illegal one) – 2019-12-1

  • Add ignoreLogNotifications config option
  • Add ability to override logStdErr and logMessages config options with the LSP_TEST_LOG_STDERR and LOG_TEST_LOG_MESSAGES environment variables
  • Update for haskell-lsp- (@mpickering) – 2019-11-17

  • Expose satisfyMaybe (@cocreature) – 2019-11-17

  • Update to haskell-lsp- (@mpickering, @alanz)
  • Tests now require hie-bios based hie – 2019-10-18

  • Make Session a newtype
  • Update for haskell-lsp- (@cocreature) – 2019-09-08

  • Update for haskell-lsp- – 2019-08-24

  • Add satisfyMaybe (@cocreature) – 2019-07-04

  • Update to haskell-lsp- (@lorenzo) – 2019-06-13

  • Fix getDefinitions for SingleLoc (@cocreature)
  • Add getCodeLenses (@cocreature) – 2019-06-13

  • Update to haskell-lsp- (@cocreature)
  • Support TextDocumentDidChange (@cocreature)
  • Add non-file based openDoc (@cocreature) – 2019-04-28

  • Add satisfy parser combinator – 2019-04-22

  • Fix unhandled window/progress server notifications – 2019-04-07

  • Add getTypeDefinitions (@fendor) – 2018-12-05

  • Fix loose threads when exceptions are thrown – 2018-11-13

  • Add lspConfig option in config
  • GHC 8.6.2 support – 2018-09-08

  • Update to haskell-lsp- – 2018-09-0t

  • Update to haskell-lsp- – 2018-08-14

  • Add getCodeActions
  • Add getCurrentDiagnostics – 2018-08-06

  • Update to haskell-lsp