Merge remote-tracking branch 'upstream/master' into colorcolcharcolorcolchar

1 files changed, 35 insertions, 7 deletions

diff --git a/test/README.md b/test/README.md
index a67040e68c..3aafe1273e 100644
--- a/test/README.md
+++ b/test/README.md
@@ -3,7 +3,7 @@ Tests
 
 Tests are broadly divided into *unit tests* ([test/unit](https://github.com/neovim/neovim/tree/master/test/unit/)),
 *functional tests* ([test/functional](https://github.com/neovim/neovim/tree/master/test/functional/)),
-and *old tests* ([src/nvim/testdir/](https://github.com/neovim/neovim/tree/master/src/nvim/testdir/)).
+and *old tests* ([test/old/testdir/](https://github.com/neovim/neovim/tree/master/test/old/testdir/)).
 
 - _Unit_ testing is achieved by compiling the tests as a shared library which is
   loaded and called by [LuaJit FFI](http://luajit.org/ext_ffi.html).
@@ -48,7 +48,7 @@ Layout
 - `/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.
-- `/src/nvim/testdir` : old tests (from Vim)
+- `/test/old/testdir` : old tests (from Vim)
 
 
 Running tests
@@ -83,7 +83,7 @@ To run a *single* legacy test file you can use either:
 
 or:
 
-    make src/nvim/testdir/test_syntax.vim
+    make test/old/testdir/test_syntax.vim
 
 - Specify only the test file name, not the full path.
 
@@ -102,9 +102,25 @@ Debugging tests
     DBG 2022-06-15T18:37:45.229 T57.58016.0   read_cb:118: closing Stream (0x7fd5d700ea18): EOF (end of file)
     INF 2022-06-15T18:37:45.229 T57.58016.0   on_process_exit:400: exited: pid=58017 status=0 stoptime=0
   ```
-- You can set `$GDB` to [run tests under gdbserver](https://github.com/neovim/neovim/pull/1527).
-  And if `$VALGRIND` is set it will pass `--vgdb=yes` to valgrind instead of
+- You can set `$GDB` to [run functional tests under gdbserver](https://github.com/neovim/neovim/pull/1527):
+
+  ```sh
+  GDB=1 TEST_FILE=test/functional/api/buffer_spec.lua TEST_FILTER='nvim_buf_set_text works$' make functionaltest
+  ```
+
+  Read more about [filtering tests](#filtering-tests).
+
+  Then, in another terminal:
+
+  ```sh
+  gdb -ex 'target remote localhost:7777' build/bin/nvim
+  ```
+
+  If `$VALGRIND` is also set it will pass `--vgdb=yes` to valgrind instead of
   starting gdbserver directly.
+
+  See [test/functional/helpers.lua](https://github.com/neovim/neovim/blob/9cadbf1d36b63f53f0de48c8c5ff6c752ff05d70/test/functional/helpers.lua#L52-L69) for details.
+
 - Hanging tests can happen due to unexpected "press-enter" prompts. The
   default screen width is 50 columns. Commands that try to print lines longer
   than 50 columns in the command-line, e.g. `:edit very...long...path`, will
@@ -124,7 +140,7 @@ Filtering Tests
 
 ### Filter by name
 
-Another filter method is by setting a pattern of test name to `TEST_FILTER` or `TEST_FILTER_OUT`.
+Tests can be filtered by setting a pattern of test name to `TEST_FILTER` or `TEST_FILTER_OUT`.
 
 ``` lua
 it('foo api',function()
@@ -149,14 +165,26 @@ To run a *specific* unit test:
 
     TEST_FILE=test/unit/foo.lua make unittest
 
+or
+
+    cmake -E env "TEST_FILE=test/unit/foo.lua" cmake --build build --target unittest
+
 To run a *specific* functional test:
 
     TEST_FILE=test/functional/foo.lua make functionaltest
 
+or
+
+    cmake -E env "TEST_FILE=test/functional/foo.lua" cmake --build build --target functionaltest
+
 To *repeat* a test:
 
     BUSTED_ARGS="--repeat=100 --no-keep-going" TEST_FILE=test/functional/foo_spec.lua make functionaltest
 
+or
+
+    cmake -E env "TEST_FILE=test/functional/foo_spec.lua" cmake -E env BUSTED_ARGS="--repeat=100 --no-keep-going" cmake --build build --target functionaltest
+
 ### Filter by tag
 
 Tests can be "tagged" by adding `#` before a token in the test description.
@@ -273,7 +301,7 @@ Number; !must be defined to function properly):
 
 - `VALGRIND_LOG` (F) (S): overrides valgrind log file name used for `VALGRIND`.
 
-- `TEST_COLORS` (F) (U) (D): enable pretty colors in test runner.
+- `TEST_COLORS` (F) (U) (D): enable pretty colors in test runner. Set to true by default.
 
 - `TEST_SKIP_FRAGILE` (F) (D): makes test suite skip some fragile tests.