doc

1 files changed, 35 insertions, 18 deletions

diff --git a/test/README.md b/test/README.md
index 01db5960cd..44558f0981 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,31 +1,48 @@
-# Tests
+Tests
+=====
 
 Tests are run by `/cmake/RunTests.cmake` file, using busted.
 
 For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight.
 
-## Directory structure
+Lint
+----
 
-Directories with tests: `/test/benchmark` for benchmarks, `/test/functional` for 
-functional tests, `/test/unit` for unit tests. `/test/config` contains `*.in` 
-files (currently a single one) which are transformed into `*.lua` files using 
-`configure_file` CMake command: this is for acessing CMake variables in lua 
-tests. `/test/includes` contains include files for use by luajit `ffi.cdef` 
-C definitions parser: normally used to make macros not accessible via this 
-mechanism accessible the other way.
+`make lint` (and `make testlint`) runs [luacheck](https://github.com/mpeterv/luacheck)
+on the test code.
 
-Files `/test/*/preload.lua` contain modules which will be preloaded by busted, 
-via `--helper` option. `/test/**/helpers.lua` contain various “library” 
-functions, (intended to be) used by a number of tests and not just a single one.
+If a luacheck warning must be ignored, specify the warning code. Example:
 
-`/test/*/**/*_spec.lua` are files containing actual tests. Files that do not end 
-with a `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they 
-have some common topic.
+    -- luacheck: ignore 621
 
-Tests inside `/test/unit` and `/test/functional` are normally divided into 
-groups by the semantic component they are testing.
+http://luacheck.readthedocs.io/en/stable/warnings.html
 
-## Environment variables
+Ignore the smallest applicable scope (e.g. inside a function, not at the top of
+the file).
+
+Layout
+------
+
+- `/test/benchmark` : benchmarks
+- `/test/functional` : functional tests
+- `/test/unit` : unit tests
+- `/test/config` : contains `*.in` files which are transformed into `*.lua`
+  files using `configure_file` CMake command: this is for acessing CMake
+  variables in lua tests.
+- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions
+  parser: normally used to make macros not accessible via this mechanism
+  accessible the other way.
+- `/test/*/preload.lua` : modules preloaded by busted `--helper` option
+- `/test/**/helpers.lua` : common utility functions for test code
+- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with
+  `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have
+  some common topic.
+
+Tests in `/test/unit` and `/test/functional` are normally divided into groups
+by the semantic component they are testing.
+
+Environment variables
+---------------------
 
 Test behaviour is affected by environment variables. Currently supported 
 (Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined,