Update documentation for running tests

[xsebek]

Is your enhancement request related to a problem? Please describe.

The contributing guide mentions this alternative:

cabal run haskell-language-server:func-test -- -p "hlint enables"

This is supposed to work around Cabal flushing caches when using --test-options:

• --enable-tests / --test-option(s) causes recalculation cabal#6114

But that does not work, because Cabal does not set executables to PATH for run:

• cabal test sees the executable, but cabal run does not. cabal#8391

And thus runSession produces this slightly confusing message:

haskell-language-server
  window/workDoneProgress
    sends indefinite progress notifications: FAIL
      Exception: haskell-language-server: createProcess: posix_spawnp: does not exist (No such file or directory)

Describe the solution you'd like

The contributing guide should probably be updated to mention this error and link to the Cabal bug.

As a temporary workaround, the tests could check that the executable exists and print more helpful error.

Describe alternatives you've considered

The users can set HLS_TEST_EXE and HLS_WRAPPER_TEST_EXE like CI does, but that seems brittle.

haskell-language-server/test/utils/Test/Hls/Command.hs

Lines 10 to 19 in c0f7d4c

	-- | The command to execute the version of hls for the current compiler.
	--
	-- Both @stack test@ and @cabal new-test@ setup the environment so @hls@ is
	-- on PATH. Cabal seems to respond to @build-tool-depends@ specifically while
	-- stack just puts all project executables on PATH.
	hlsCommand :: String
	{-# NOINLINE hlsCommand #-}
	hlsCommand = unsafePerformIO $ do
	testExe <- fromMaybe "haskell-language-server" <$> lookupEnv "HLS_TEST_EXE"
	pure $ testExe ++ " --lsp -d -j4"

Additional context

I hit this long ago and @pepeiborra helpfully pointed out that this does not work in #2837, but I have since forgotten about it. 😅

[fendor]

Another great way to filter tests is to use the TASTY_PATTERN environment variable.

For example:

TASTY_PATTERN="hlint enables" cabal test haskell-language-server:func-test

[xsebek]

As another alternative, I attempted to fix the bug in Cabal so this will one day not be an Issue. 😄

This documentation definitely needs an update though, as the "hlint enables" test does not exist after the refactor. 🙂