diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ale-development.txt | 81 | ||||
| -rw-r--r-- | doc/ale-scala.txt | 6 | ||||
| -rw-r--r-- | doc/ale.txt | 36 |
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. |