Massively reduce the amount of code needed for linter tests

3 files changed, 118 insertions, 5 deletions

diff --git a/doc/ale-development.txt b/doc/ale-development.txt
index f97bdee4..5688c1cc 100644
--- a/doc/ale-development.txt
+++ b/doc/ale-development.txt
@@ -10,6 +10,7 @@ CONTENTS                                             *ale-development-contents*
   2. Design Goals.........................|ale-design-goals|
   3. Coding Standards.....................|ale-coding-standards|
   4. Testing ALE..........................|ale-development-tests|
+    4.1. Writing Linter Tests.............|ale-development-linter-tests|
 
 ===============================================================================
 1. Introduction                                  *ale-development-introduction*
@@ -173,6 +174,9 @@ Look at existing tests in the codebase for examples of how to write tests.
 Refer to the Vader documentation for general information on how to write Vader
 tests: https://github.com/junegunn/vader.vim
 
+See |ale-development-linter-tests| for more information on how to write linter
+tests.
+
 When you add new linters or fixers, make sure to add them into the table in
 the README, and also into the |ale-support| list in the main help file. If you
 forget to keep them both in sync, you should see an error like the following
@@ -223,4 +227,81 @@ Make sure to make the table of contents match the headings, and to keep the
 doc tags on the right margin.
 
 ===============================================================================
+4.1 Writing Linter Tests                         *ale-development-linter-tests*
+
+Tests for ALE linters take two forms.
+
+1. Tests for handling the output of commands.
+2. Tests for checking which commands are run, or connections are made.
+
+Tests of the first form should go in the `test/handler` directory, and should
+be written like so. >
+
+  Before:
+    " Load the file which defines the linter.
+    runtime ale_linters/filetype/linter_name_here.vim
+
+  After:
+    " Unload all linters again.
+    call ale#linter#Reset()
+
+  Execute(The output should be correct):
+
+  " Test that the right loclist items are parsed from the handler.
+  AssertEqual
+  \ [
+  \   {
+  \     'lnum': 1,
+  \     'type': 'E',
+  \     'text': 'Something went wrong',
+  \   },
+  \ ],
+  \ ale_linters#filetype#linter_name#Handle(bufnr(''), [
+  \ '1:Something went wrong',
+  \ ]
+<
+Tests for what ALE runs should go in the `test/command_callback` directory,
+and should be written like so. >
+
+  Before:
+    " Load the linter and set up a series of commands, reset linter variables,
+    " clear caches, etc.
+    "
+    " Vader's 'Save' command will be called here for linter variables.
+    call ale#assert#SetUpLinterTest('filetype', 'linter_name')
+
+  After:
+    " Reset linters, variables, etc.
+    "
+    " Vader's 'Restore' command will be called here.
+    call ale#assert#TearDownLinterTest()
+
+  Execute(The default command should be correct):
+    " AssertLinter checks the executable and command.
+    " Pass expected_executable, expected_command
+    AssertLinter 'some-command', ale#Escape('some-command') . ' --foo'
+
+  Execute(Check chained commands):
+    " WithChainResults can be called with 1 or more list for passing output
+    " to chained commands. The output for each callback defaults to an empty
+    " list.
+    WithChainResults ['v2.1.2']
+    " Given a List of commands, check all of them.
+    " Given a String, only the last command in the chain will be checked.
+    AssertLinter 'some-command', [
+    \ ale#Escape('some-command') . ' --version',
+    \ ale#Escape('some-command') . ' --foo',
+    \]
+<
+The full list of commands that will be temporarily defined for linter tests
+given the above setup are as follows.
+
+`WithChainResults [...]`           - Define output for command chain functions.
+`AssertLinter executable, command` - Check the executable and command.
+`AssertLinterNotExecuted`          - Check that linters will not be executed.
+`AssertLSPLanguage language`       - Check the language given to an LSP server.
+`AssertLSPOptions options_dict`    - Check the options given to an LSP server.
+`AssertLSPProject project_root`    - Check the root given to an LSP server.
+
+===============================================================================
   vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:
diff --git a/doc/ale-scala.txt b/doc/ale-scala.txt
index b5474f3b..b992d428 100644
--- a/doc/ale-scala.txt
+++ b/doc/ale-scala.txt
@@ -41,8 +41,8 @@ To disable `scalastyle` globally, use |g:ale_linters| like so: >
 See |g:ale_linters| for more information on disabling linters.
 
 
-g:ale_scalastyle_config_loc                       *g:ale_scalastyle_config_loc*
-
+g:ale_scala_scalastyle_config                   *g:ale_scala_scalastyle_config*
+                                                *b:ale_scala_scalastyle_config*
   Type: |String|
   Default: `''`
 
@@ -54,7 +54,7 @@ g:ale_scalastyle_config_loc                       *g:ale_scalastyle_config_loc*
 
 
 g:ale_scala_scalastyle_options                 *g:ale_scala_scalastyle_options*
-
+                                               *b:ale_scala_scalastyle_options*
   Type: |String|
   Default: `''`
 
diff --git a/doc/ale.txt b/doc/ale.txt
index e1a209cf..75a37533 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -2074,6 +2074,29 @@ ALEStopAllLSPs                                                 *ALEStopAllLSPs*
 ===============================================================================
 9. API                                                                *ale-api*
 
+ALE offers a number of functions for running linters or fixers, or defining
+them. The following functions are part of the publicly documented part of that
+API, and should be expected to continue to work.
+
+
+ale#Env(variable_name, value)                                       *ale#Env()*
+
+  Given a variable name and a string value, produce a string for including in
+  a command for setting environment variables. This function can be used for
+  building a command like so. >
+
+    :echo string(ale#Env('VAR', 'some value') . 'command')
+    'VAR=''some value'' command'      # On Linux or Mac OSX
+    'set VAR="some value" && command' # On Windows
+
+
+ale#Pad(string)                                                     *ale#Pad()*
+
+  Given a string or any |empty()| value, return either the string prefixed
+  with a single space, or an empty string. This function can be used to build
+  parts of a command from variables.
+
+
 ale#Queue(delay, [linting_flag, buffer_number])                   *ale#Queue()*
 
   Run linters for the current buffer, based on the filetype of the buffer,
@@ -2098,8 +2121,17 @@ ale#Queue(delay, [linting_flag, buffer_number])                   *ale#Queue()*
 ale#engine#CreateDirectory(buffer)               *ale#engine#CreateDirectory()*
 
   Create a new temporary directory with a unique name, and manage that
-  directory with |ale#engine#ManageDirectory()|, so it will be removed as
-  soon as possible.
+  directory with |ale#engine#ManageDirectory()|, so it will be removed as soon
+  as possible.
+
+  It is advised to only call this function from a callback function for
+  returning a linter command to run.
+
+
+ale#engine#CreateFile(buffer)                         *ale#engine#CreateFile()*
+
+  Create a new temporary file with a unique name, and manage that file with
+  |ale#engine#ManageFile()|, so it will be removed as soon as possible.
 
   It is advised to only call this function from a callback function for
   returning a linter command to run.