zsh-syntax-highlighting/tests/README.md

zsh-syntax-highlighting / tests
===============================

Utility scripts for testing zsh-syntax-highlighting highlighters.

The tests expect the highlighter directory to contain a `test-data` directory with test data files. See the [main highlighter](../highlighters/main/test-data) for examples.

Each test should define the array parameter `$expected_region_highlight`.
The value of that parameter is a list of `"$i $j $style [$todo]"` strings.
Each string specifies the highlighting that `$BUFFER[$i,$j]` should have;
that is, `$i` and `$j` specify a range, 1-indexed, inclusive of both endpoints.
If `$todo` exists, the test point is marked as TODO (the failure of that test point will not fail the test), and `$todo` is used as the explanation.

_Note_: `$region_highlight` uses the same `"$i $j $style"` syntax but interprets the indexes differently.


highlighting test
-----------------
[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of the highlighting. Usage:

    zsh test-highlighting.zsh <HIGHLIGHTER NAME>

All tests may be run with

    make test

which will run all highlighting tests and report results in [TAP](http://testanything.org/) format.


performance test
----------------
[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the highlighting. Usage:

    zsh test-perfs.zsh <HIGHLIGHTER NAME>
Big refactoring. * Don't override user defined styles * Better modularisation of highlighters * Allow to define which highlighters are activated * Allow to define the order in which they are defined * Minor performance optimizations * Fixed some variables leak * Improve documentation * Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array 2011-06-13 04:57:14 +08:00			`zsh-syntax-highlighting / tests`
			`===============================`

			`Utility scripts for testing zsh-syntax-highlighting highlighters.`

			The tests expect the highlighter directory to contain a `test-data` directory with test data files. See the [main highlighter](../highlighters/main/test-data) for examples.

test harness: Fix off-by-one discrepancy between observed and expected. Fixes issue #195. 2015-09-13 04:29:04 +08:00			Each test should define the array parameter `$expected_region_highlight`.
test harness: Run each test as a single subshell. That allows tests to be completely independent of each other, so tests that change global state — such as modify environment variables, define functions or aliases, or hash commands — will not affect other tests, without needing an explicit cleanup step. This enables testing path-tilde-home with and without $HOME set, which is part of issue #216. While at it, convert the test harness to TAP. This fixes issue #180 by adding support for "not ok 42 # TODO" output. This commit assumes that 'grep' supports POSIX-compliant -q and -v flags. Patch-by: Matthew Martin <phy1729@gmail.com> 2015-10-23 11:27:05 +08:00			The value of that parameter is a list of `"$i $j $style [$todo]"` strings.
test harness: Fix off-by-one discrepancy between observed and expected. Fixes issue #195. 2015-09-13 04:29:04 +08:00			Each string specifies the highlighting that `$BUFFER[$i,$j]` should have;
			that is, `$i` and `$j` specify a range, 1-indexed, inclusive of both endpoints.
test harness: Run each test as a single subshell. That allows tests to be completely independent of each other, so tests that change global state — such as modify environment variables, define functions or aliases, or hash commands — will not affect other tests, without needing an explicit cleanup step. This enables testing path-tilde-home with and without $HOME set, which is part of issue #216. While at it, convert the test harness to TAP. This fixes issue #180 by adding support for "not ok 42 # TODO" output. This commit assumes that 'grep' supports POSIX-compliant -q and -v flags. Patch-by: Matthew Martin <phy1729@gmail.com> 2015-10-23 11:27:05 +08:00			If `$todo` exists, the test point is marked as TODO (the failure of that test point will not fail the test), and `$todo` is used as the explanation.
test harness: Fix off-by-one discrepancy between observed and expected. Fixes issue #195. 2015-09-13 04:29:04 +08:00
			_Note_: `$region_highlight` uses the same `"$i $j $style"` syntax but interprets the indexes differently.

Big refactoring. * Don't override user defined styles * Better modularisation of highlighters * Allow to define which highlighters are activated * Allow to define the order in which they are defined * Minor performance optimizations * Fixed some variables leak * Improve documentation * Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array 2011-06-13 04:57:14 +08:00
			`highlighting test`
			`-----------------`
Fix READMEs 2011-06-13 05:16:41 +08:00			[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of the highlighting. Usage:
Big refactoring. * Don't override user defined styles * Better modularisation of highlighters * Allow to define which highlighters are activated * Allow to define the order in which they are defined * Minor performance optimizations * Fixed some variables leak * Improve documentation * Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array 2011-06-13 04:57:14 +08:00
			`zsh test-highlighting.zsh <HIGHLIGHTER NAME>`

test harness: Run each test as a single subshell. That allows tests to be completely independent of each other, so tests that change global state — such as modify environment variables, define functions or aliases, or hash commands — will not affect other tests, without needing an explicit cleanup step. This enables testing path-tilde-home with and without $HOME set, which is part of issue #216. While at it, convert the test harness to TAP. This fixes issue #180 by adding support for "not ok 42 # TODO" output. This commit assumes that 'grep' supports POSIX-compliant -q and -v flags. Patch-by: Matthew Martin <phy1729@gmail.com> 2015-10-23 11:27:05 +08:00			`All tests may be run with`

			`make test`

			`which will run all highlighting tests and report results in [TAP](http://testanything.org/) format.`

Big refactoring. * Don't override user defined styles * Better modularisation of highlighters * Allow to define which highlighters are activated * Allow to define the order in which they are defined * Minor performance optimizations * Fixed some variables leak * Improve documentation * Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array 2011-06-13 04:57:14 +08:00
			`performance test`
			`----------------`
Fix READMEs 2011-06-13 05:16:41 +08:00			[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the highlighting. Usage:
Big refactoring. * Don't override user defined styles * Better modularisation of highlighters * Allow to define which highlighters are activated * Allow to define the order in which they are defined * Minor performance optimizations * Fixed some variables leak * Improve documentation * Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array 2011-06-13 04:57:14 +08:00
			`zsh test-perfs.zsh <HIGHLIGHTER NAME>`