themis.txt

*themis.txt*	A testing framework for Vim script.

Version: 1.7.0
Author : thinca <thinca+vim@gmail.com>
License: zlib License

==============================================================================
CONTENTS					*themis-contents*

INTRODUCTION			|themis-introduction|
USAGE				|themis-usage|
INTERFACE			|themis-interface|
  EXTERNAL COMMANDS		  |themis-external-commands|
  FUNCTIONS			  |themis-functions|
CUSTOMIZING			|themis-customizing|
  ENVIRONMENT VARIABLE		  |themis-environment-variable|
  THEMISRC			  |themis-themisrc|
WRITE TEST			|themis-write-test|
  QUICKREF			  |themis-quickref|
STYLE				|themis-style|
  BASIC				  |themis-style-basic|
  VIMSPEC			  |themis-style-vimspec|
HELPER				|themis-helper|
  ASSERT			  |themis-helper-assert|
  COMMAND			  |themis-helper-command|
  EXPECT			  |themis-helper-expect|
  SCOPE				  |themis-helper-scope|
REPORTER			|themis-reporter|
TEST RULE			|themis-test-rule|
  EXCEPTION			  |themis-rule-exception|
  VIM BUILTIN ASSERT		  |themis-rule-builtin-assert|
CHANGELOG			|themis-changelog|



==============================================================================
INTRODUCTION					*themis-introduction*

*themis.vim* is a testing framework for Vim script.

- Run tests by command line.
- A result can be outputted in some formats.
- Simply a test fails when an exception is thrown.
- You can write tests in some styles. (in future)



Requirements:
- Vim 7.4 or later

Latest version:
https://github.com/thinca/vim-themis



==============================================================================
USAGE						*themis-usage*

1. Installation
This plugin can install by same way of other general plugins.  You can use
your favorite way.
And, you need install `themis` command.  This command is in `bin/themis`(or
`bin/themis.bat` in MS Windows environment) of the plugin package.  You can
take some methods.
	i.   Through the $PATH to the bin/ directory.
	ii.  Make a symbolic link to `bin/themis` from your bin directory.
	iii. Copy `bin/themis` to your bin directory and set |$THEMIS_HOME|.


2. Write tests
Test is a Vim script like the following.
>
	let s:suite = themis#suite('Test for my plugin')
	let s:assert = themis#helper('assert')

	" The function name(my_test_1) will be a test name.
	function s:suite.my_test_1()
	  call s:assert.equals(3, 1 + 2)
	endfunction

	function s:suite.my_test_2()
	  call s:assert.equals(8, 2 * 4)
	endfunction
	function s:suite.my_fail_test()
	  call s:assert.fail('this will fail')
	endfunction
<
	See |themis-write-test| for detail.

3. Run the test
Run the test by command line.
>
	$ cd /path/to/your-plugin
	$ themis test.vim
<
4. You get the result
>
	ok 1 - my_test_1
	ok 2 - my_test_2
	not ok 3 - my_fail_test
	# this will fail

	# tests 3
	# pass 2
	# fail 1
<


==============================================================================
INTERFACE					*themis-interface*

------------------------------------------------------------------------------
EXTERNAL COMMANDS				*themis-external-commands*

						*bin/themis*
bin/themis [options] [script]...
	Runs tests.  If a directory is passed to [script], uses all "*.vim"
	files in the directory.
	When [script] is omitted, one of the "./test", "./t", or "./spec" is
	automatically used.
	Current directory is appended to 'runtimepath' automatically.
	If test fails or error occurs, exit status becomes non zero.

	--exclude {pattern}			*themis-option-exclude*
		Exclude script files which matched the {pattern}.
		{pattern} is a |regular-expression|.
		Two or more specification is possible.

	--target {pattern}			*themis-option-target*
		Run tests whose full title matches to {pattern}.
		{pattern} is a |regular-expression|.
		Two or more specification is possible.

	-r, --recursive				*themis-option-recursive*
		Include sub directories.

	--reporter {reporter}			*themis-option-reporter*
		Specifies a reporter(|themis-reporter|).

	--reporter-list				*themis-option-reporter-list*
		Show the list of available reporters.

	--runtimepath {runtimepath}		*themis-option-runtimepath*
		Add 'runtimepath'.  Two or more specification is possible.


------------------------------------------------------------------------------
FUNCTIONS					*themis-functions*

Following functions are utilities for test script.

themis#suite([{name}])				*themis#suite()*
	Creates and returns a new test suite.

themis#helper({name})				*themis#helper()*
	Use a helper.
	This creates or enables the {name} helper.  See also |themis-helper|.

themis#option([{name} [, {value}]])		*themis#option()*
	Gets a dictionary that contains default options.
	This is only available in |.themisrc|.
	If {name} is specified, returns the value of specified option.
	If {name} and {value} is specified, updates the value of specified
	option.  When the option is List, {value} is appended to the List.

themis#func_alias({dict})			*themis#func_alias()*
	Supplies function names for |anonymous-function|s.  They are used in
	view of stacktrace info.
	For example:
>
	let s:MyClass = {}
	function s:MyClass.useful_function()
	  throw 'some error!'
	endfunction
	call themis#func_alias({'MyClass': s:MyClass})
<
	You get the following stacktrace without |themis#func_alias()|,
>
	function 78() dict  Line:1  (/tmp/vAonMgS/0)
<
	However, you can get the following stacktrace when you use
	|themis#func_alias()|: >

	function MyClass.useful_function() dict  Line:1  (/tmp/vAonMgS/0)



==============================================================================
CUSTOMIZING					*themis-customizing*

------------------------------------------------------------------------------
ENVIRONMENT VARIABLE				*themis-environment-variable*

$THEMIS_HOME					*$THEMIS_HOME*
	The home directory of themis.  The home directory is a base of
	runtimepath.
	When you copy the `themis` command to another place and use it, you
	have to set this environment variable.

$THEMIS_VIM					*$THEMIS_VIM*
	The path to vim command.  "vim" is used when this is empty.

$THEMIS_ARGS					*$THEMIS_ARGS*
	Extra arguments passed to |$THEMIS_VIM|. "-e -s" is used when this is
	empty. Note that chainging the value may cause invalid test run.
	Change the value of this variable with your own responsibility.


------------------------------------------------------------------------------
THEMISRC					*themis-themisrc*

Themis loads *.themisrc* file before loading of test scripts for user setup.
".themisrc" file is just a Vim script.

Loading Rule
------------
The ".themisrc" file is searched from test target file or directory to upper
layer.

When two or more files exist, it is sequentially loaded from a shallow
hierarchy.

For example, you run: >
	$ themis ~/path/to/project/test/
will look in the following dirs for a config file: >
	/path/to/project/test/.themisrc
	/path/to/project/.themisrc
	/path/to/.themisrc
	/path/.themisrc
	... # up until root of filesystem
These files are sorted by alphabetical sequence and loaded in the order. >
	/path/.themisrc
	/path/to/.themisrc
	/path/to/project/.themisrc
	/path/to/project/test/.themisrc

Another example: >
	$ themis ~/project/test/foo/test.vim ~/project/test/dir
will look in the following dirs for a config file: >
	/project/test/foo/.themisrc
	/project/test/.themisrc
	/project/.themisrc
	/.themisrc
	/project/test/dir/.themisrc
	/project/test/.themisrc
	/project/.themisrc
	/.themisrc
These are sorted, and duplicated items are removed. >
	/.themisrc
	/project/.themisrc
	/project/test/.themisrc
	/project/test/dir/.themisrc
	/project/test/foo/.themisrc

Note: You should not place the ".themisrc" file in the subdirectory of test
directory.  The file is not loaded when the test directory was specified and a
test is run.

Command line Options
--------------------
You can access and change the default value of command-line options.
You can get a dictionary from |themis#option()| that contains the following
elements.

option.exclude
	Value of |themis-option-exclude|.  This is a List.
option.target
	Value of |themis-option-target|.  This is a List.
option.recursive
	Value of |themis-option-recursive|.  This is 1 or 0.
option.reporter
	Value of |themis-option-reporter|.
option.runtimepath
	Value of |themis-option-runtimepath|.  This is a List.

Note that these values may be changed from upper stream of ".themisrc".
You can overwrite these options from command line.

Example of Usage
----------------
You can put helpers in global scope, and use all test scripts.
>
	let g:assert = themis#helper('assert')
<
You can define helper functions or commands used only in this project.
>
	function InitBuffer()
	  tabonly!
	  only!
	  enew!
	  put =['aaa', 'bbb', 'ccc']
	endfunction
	command! InitBuffer call InitBuffer()
<
You can define a new matcher for expect-helper.
See |themis#helper#expect#define_matcher()| for detail.


==============================================================================
WRITE TEST					*themis-write-test*

First, make a "test" directory in your project.
You can put tests in favorite place, but "test" directory is read in default.
>
	$ cd /path/to/your-plugin-project
	$ mkdir test
<
Create a new test script.
>
	$ vim test/your-test.vim
<
You can select a style to write a test.  See |themis-style| for details.
And write a test.  There is a sample with explanation comment.
>
	" In a file, create a suite at first.
	let s:suite = themis#suite('test title')
	" In many cases, helper is convenient.
	let s:assert = themis#helper('assert')

	" Define a function to suite.
	" This function is a test.
	" Function name becomes a title of test.  In this case, "my_test".
	function s:suite.my_test_1()
	  " Check the calculation result
	  let value = 1 + 2
	  call s:assert.equals(value, 3)
	endfunction
<

------------------------------------------------------------------------------
QUICKREF					*themis-quickref*

There is a quick reference for writing test.


Assert Helper >
	let s:assert = themis#helper('assert')

Force fail and skip
|themis-helper-assert-fail()| / |themis-helper-assert-todo()|
|themis-helper-assert-skip()|
Check values
|themis-helper-assert-true()| / |themis-helper-assert-false()|
|themis-helper-assert-truthy()| / |themis-helper-assert-falsy()|
|themis-helper-assert-compare()|
|themis-helper-assert-equals()| / |themis-helper-assert-not_equals()|
|themis-helper-assert-same()| / |themis-helper-assert-not_same()|
|themis-helper-assert-match()| / |themis-helper-assert-not_match()|
Check types
|themis-helper-assert-is_number()| / |themis-helper-assert-is_not_number()|
|themis-helper-assert-is_string()| / |themis-helper-assert-is_not_string()|
|themis-helper-assert-is_func()| / |themis-helper-assert-is_not_func()|
|themis-helper-assert-is_list()| / |themis-helper-assert-is_not_list()|
|themis-helper-assert-is_dict()| / |themis-helper-assert-is_not_dict()|
|themis-helper-assert-is_float()| / |themis-helper-assert-is_not_float()|
|themis-helper-assert-is_bool()| / |themis-helper-assert-is_not_bool()|
|themis-helper-assert-is_none()| / |themis-helper-assert-is_not_none()|
|themis-helper-assert-is_job()| / |themis-helper-assert-is_not_job()|
|themis-helper-assert-is_channel()| / |themis-helper-assert-is_not_channel()|
|themis-helper-assert-is_blob()| / |themis-helper-assert-is_not_blob()|
|themis-helper-assert-type_of()|
Others
|themis-helper-assert-length_of()|
|themis-helper-assert-includes()| / |themis-helper-assert-not_includes()|
|themis-helper-assert-key_exists()| / |themis-helper-assert-key_not_exists()|
|themis-helper-assert-has_key()|
|themis-helper-assert-exists()| / |themis-helper-assert-not_exists()|
|themis-helper-assert-cmd_exists()| / |themis-helper-assert-cmd_not_exists()|
|themis-helper-assert-empty()|
|themis-helper-assert-not_empty()|


Command Helper >
	call themis#helper('command')
	call themis#helper('command').with(s:assert)

Available commands
|themis-helper-command-:Assert|	Checks a value.
|themis-helper-command-:Throws|	Checks an exception thrown.
|themis-helper-command-:Fail|	Fail.
|themis-helper-command-:TODO|	Fail as TODO.
|themis-helper-command-:Skip|	Skip.


Expect Helper >
	let s:expect = themis#helper('expect')

Check values
|themis-helper-expect-to_be_true()| / |themis-helper-expect-to_be_false()|
|themis-helper-expect-to_be_truthy()| / |themis-helper-expect-to_be_falsy()|
|themis-helper-expect-to_be_greater_than()|
|themis-helper-expect-to_be_greater_than_or_equal()|
|themis-helper-expect-to_be_less_than()|
|themis-helper-expect-to_be_less_than_or_equal()|
|themis-helper-expect-to_equal()| / |themis-helper-expect-to_be_same()|
|themis-helper-expect-to_match()|
Check types
|themis-helper-expect-to_be_number()| / |themis-helper-expect-to_be_string()|
|themis-helper-expect-to_be_func()| / |themis-helper-expect-to_be_list()|
|themis-helper-expect-to_be_dict()| / |themis-helper-expect-to_be_float()|
Others
|themis-helper-expect-to_exist()|
|themis-helper-expect-to_be_empty()|
|themis-helper-expect-to_have_length()|
|themis-helper-expect-to_have_key()|
Invert results
|themis-helper-expect-not|
Define custom matcher
|themis#helper#expect#define_matcher()|


Scope Helper >
	let s:scope = themis#helper('scope')

Access to script-local functions.
|themis-helper-scope-funcs()|



==============================================================================
STYLE						*themis-style*

You can write tests by some styles.
Style is a file format.  You can select your favorite style.
Style is decided from extension of test file.

------------------------------------------------------------------------------
BASIC						*themis-style-basic*

Basic-style is most basic style.  This style is just a Vim script.
"*.vim" file is treated as basic style.

You can make a suite by |themis#suite()|.

TEST NAME					*themis-style-basic-test-name*
The key name of a suite is test name.
Some test names have a special meaning.  They are called in special situation.

- before()
  - This is called before a first test of this suite.
- before_each()
  - This is called before each test of this suite.
  - You can make test fail/pending from this function.
- after_each()
  - This is called after each test of this suite.
  - You can make test fail/pending from this function.
- after()
  - This is called after a last test of this suite.
- __XXX__()
  - XXX is any string.
  - This is called before the all test.
  - You can make nested suite in this function.  >
	let s:parent = themis#suite('parent')
	function s:parent.__child__()
	  let child = themis#suite('child')
	  function child.test()
	    " Test code here...
	  endfunction
	endfunction

------------------------------------------------------------------------------
VIMSPEC						*themis-style-vimspec*

Vimspec-style provides spec style test.
"*.vimspec" file is treated as vimspec style.

Vimspec-style provides some special commands.
>
	Describe DateTime
	  Context .from_unix_time()
	    It makes a DateTime object from unix time
	      Assert Equals(DateTime.from_unix_time(1410590959).year(), 2014)
	    End
	  End
	End
<
A .vimspec file is converted to a Vim script before :source.
The converted file may be placed to other place from original file.
Note that when you use `expand("<sfile>")`.

All special commands can start with lowercase. >
	describe DateTime.now()
	  it makes a DateTime object with now time
	    " ...
	  end
	end

:Describe {description}			*themis-style-vimspec-:Describe*
:End
	Defines a suite block.
	This can be nested.
	This makes a new scope like a function.  You can use a |l:| variable.
	And, the variable is available at the nested scope.
	Example: >
	Describe Root scope
	  Before all
	    let foo = 3  " Define "foo" variable
	  End

	  It is a test
	    Assert Equals(foo, 3)  " You can access to "foo"
	  End

	  Context child scope
	    It is a test in child
	      Assert Equals(foo, 3)  " You can access to "foo" also here
	    End
	  End
	End

:Context {description}			*themis-style-vimspec-:Context*
:End
	Defines a suite block.  This is an alias of :Describe.
	This is useful to make nested groups more readable.

:It {example}				*themis-style-vimspec-:It*
:End
	Defines a test.
	This block will be converted to a function.

:Before all				*themis-style-vimspec-:Before*
:End
	Defines a block which is run before each suite.

:Before [each]
:End
	Defines a block which is run before each test.
	You can make test fail/pending from this block.

:After all				*themis-style-vimspec-:After*
:End
	Defines a block which is run after each suite.

:After [each]
:End
	Defines a block which is run after each test.
	You can make test fail/pending from this block.



==============================================================================
HELPER						*themis-helper*

Helper supports writing your test.
To use a helper, writes as follows. >
	let s:helper = themis#helper(helper_name)

- |themis-helper-assert|
- |themis-helper-command|
- |themis-helper-expect|
- |themis-helper-scope|

------------------------------------------------------------------------------
ASSERT						*themis-helper-assert*

Assert-helper provides some useful functions for checking value.
These functions will throw an appropriate exception if check fails.
Check |themis-rule-exception| if you want to know the detail of exception.

assert.fail({message})			*themis-helper-assert-fail()*
	Fails a test with {message}.

assert.todo([{message}])		*themis-helper-assert-todo()*
	Fails a test as todo with {message}.

assert.skip({message})			*themis-helper-assert-skip()*
	Pass a test as SKIP with {message}.

assert.true({value} [, {message}])	*themis-helper-assert-true()*
	Checks {value} is 1 or |v:true|.

assert.false({value} [, {message}])	*themis-helper-assert-false()*
	Checks {value} is 0 or |v:false|.

assert.truthy({value} [, {message}])	*themis-helper-assert-truthy()*
	Checks {value} is truthy value.

assert.falsy({value} [, {message}])	*themis-helper-assert-falsy()*
	Checks {value} is falsy value.

					*themis-helper-assert-compare()*
assert.compare({left}, {op}, {right} [, {message}])
	Compares {left} value and {right} value by {op}. >
	assert.compare(10, '<', 20)
<
					*themis-helper-assert-equals()*
					*themis-helper-assert-equal()*
assert.equals({actual}, {expect} [, {message}])
	alias: equal()
	Checks an {actual} equals to an {expect}.  (|expr-==#|)
	When this checks string and number, this also checks the string seems
	to a number.
	This means the following check fails: >
	assert.equals('', 0)
<
					*themis-helper-assert-not_equals()*
					*themis-helper-assert-not_equal()*
assert.not_equals({actual}, {expect} [, {message}])
	alias: not_equal()
	Checks an {actual} not equals to an {expect}.  (|expr-!=#|)
	When this checks string and number, this also checks the string seems
	to a number.

					*themis-helper-assert-same()*
assert.same({actual}, {expect} [, {message}])
	Checks an {actual} and an {expect} are same.  (|expr-is#|)

					*themis-helper-assert-not_same()*
assert.not_same({actual}, {expect} [, {message}])
	Checks an {actual} and an {expect} are not same.  (|expr-isnot#|)

					*themis-helper-assert-match()*
assert.match({value}, {pattern} [, {message}])
	Checks {value} matches to {pattern}.  (|expr-=~#|)

					*themis-helper-assert-not_match()*
assert.not_match({value}, {pattern} [, {message}])
	Checks {value} doesn't match to {pattern}.  (|expr-!~#|)

assert.is_number({value} [, {message}])	*themis-helper-assert-is_number()*
	Checks type of {value} is |Number|.

					*themis-helper-assert-is_not_number()*
assert.is_not_number({value} [, {message}])
	Checks type of {value} is not |Number|.

assert.is_string({value} [, {message}])	*themis-helper-assert-is_string()*
	Checks type of {value} is String.

					*themis-helper-assert-is_not_string()*
assert.is_not_string({value} [, {message}])
	Checks type of {value} is not String.

					*themis-helper-assert-is_function()*
					*themis-helper-assert-is_func()*
assert.is_function({value} [, {message}])
	alias: is_func(), is_funcref()
	Checks type of {value} is |Funcref|.

				*themis-helper-assert-is_not_function()*
				*themis-helper-assert-is_not_func()*
assert.is_not_function({value} [, {message}])
	alias: is_not_func(), is_not_funcref()
	Checks type of {value} is not |Funcref|.

assert.is_list({value} [, {message}])	*themis-helper-assert-is_list()*
	Checks type of {value} is |List|.

					*themis-helper-assert-is_not_list()*
assert.is_not_list({value} [, {message}])
	Checks type of {value} is not |List|.

					*themis-helper-assert-is_dictionary()*
					*themis-helper-assert-is_dict()*
assert.is_dictionary({value} [, {message}])
	alias: is_dict()
	Checks type of {value} is |Dictionary|.

				*themis-helper-assert-is_not_dictionary()*
				*themis-helper-assert-is_not_dict()*
assert.is_not_dictionary({value} [, {message}])
	alias: is_not_dict
	Checks type of {value} is not |Dictionary|.

assert.is_float({value} [, {message}])	*themis-helper-assert-is_float()*
	Checks type of {value} is |Float|.

					*themis-helper-assert-is_not_float()*
assert.is_not_float({value} [, {message}])
	Checks type of {value} is not |Float|.

assert.is_bool({value} [, {message}])	*themis-helper-assert-is_bool()*
	Checks type of {value} is |v:true| or |v:false|.

					*themis-helper-assert-is_not_bool()*
assert.is_not_bool({value} [, {message}])
	Checks type of {value} is not |v:true| and |v:false|.

assert.is_none({value} [, {message}])	*themis-helper-assert-is_none()*
	Checks type of {value} is |v:none| or |v:null|.

					*themis-helper-assert-is_not_none()*
assert.is_not_none({value} [, {message}])
	Checks type of {value} is not |v:none| and |v:null|.

assert.is_job({value} [, {message}])	*themis-helper-assert-is_job()*
	Checks type of {value} is |job|.

					*themis-helper-assert-is_not_job()*
assert.is_not_job({value} [, {message}])
	Checks type of {value} is not |job|.

					*themis-helper-assert-is_channel()*
assert.is_channel({value} [, {message}])
	Checks type of {value} is |channel|.

					*themis-helper-assert-is_not_channel()*
assert.is_not_channel({value} [, {message}])
	Checks type of {value} is not |channel|.

assert.is_blob({value} [, {message}])	*themis-helper-assert-is_blob()*
	Checks type of {value} is |blob|.

					*themis-helper-assert-is_not_blob()*
assert.is_not_blob({value} [, {message}])
	Checks type of {value} is not |blob|.

					*themis-helper-assert-type_of()*
assert.type_of({value}, {names} [, {message}])
	Checks the type of {value} is one of {names}.
	{names} is a List of type names or a String of type name.
	Type name is one of the following:
	"number", "string", "funcref", "func", "function", "list", "dict",
	"dictionary", "float", "bool", "none", "job", "channel", "blob"
	Type name is case-insensitive.

					*themis-helper-assert-length_of()*
assert.length_of({value}, {length} [, {message}])
	Checks length of {value} is {length}.
	{value} is a String, a List, Dictionary, or a Blob.
	|len()| is used for length of {value}.

					*themis-helper-assert-includes()*
assert.includes({value}, {target} [, {message}])
	Checks {value} includes {target}.
	When {value} is a String, {target} must be a String and checks
	{target} is part of {value}.
	When {value} is a List, checks {value} includes {target} as an
	element.  Using |expr-is#| to compare elements.
	When {value} is a Dictionary:
		When {target} is a List, checks {value} has {target}s as key.
		When {target} is a Dictionary, checks {value} includes key and
		value pairs from {target}.  Values of dicts are compared by
		|expr-is#|.

					*themis-helper-assert-not_includes()*
assert.not_includes({value}, {target} [, {message}])
	Checks {value} does not include {target}.
	This is inversed version of |themis-helper-assert-includes()|.

					*themis-helper-assert-key_exists()*
assert.key_exists({dict}, {key} [, {message}])
	Checks {key} exists in {dict}.

					*themis-helper-assert-key_not_exists()*
assert.key_not_exists({dict}, {key} [, {message}])
	Checks {key} does not exist in {dict}.

					*themis-helper-assert-has_key()*
assert.has_key({dict}, {key} [, {message}])
assert.has_key({list}, {index} [, {message}])
	If the first argument is a dictionary, check {key} exists in {dict}.
	If the first argument is an array, check {index} exists in {list}.

assert.exists({expr} [, {message}])	*themis-helper-assert-exists()*
	Checks by |exists()| that {expr} exist.
	Note that this can not use for |local-variable| and |script-variable|.

assert.not_exists({expr} [, {message}])	*themis-helper-assert-not_exists()*
	Checks by |exists()| that {expr} does not exist.
	Note that this can not use for |local-variable| and |script-variable|.

assert.cmd_exists({cmd} [, {message}])	*themis-helper-assert-cmd_exists()*
	Checks by |exists()| strictly(full match with a command) that {cmd}
	exist.

					*themis-helper-assert-cmd_not_exists()*
assert.cmd_not_exists({cmd} [, {message}])
	Checks by |exists()| strictly(full match with a command) that {cmd}
	does not exist.

assert.empty({expr} [, {message}])	*themis-helper-assert-empty()*
	Checks {expr} by |empty()|.

assert.not_empty({expr} [, {message}])	*themis-helper-assert-not_empty()*
	Checks {expr} is not empty.

------------------------------------------------------------------------------
COMMAND						*themis-helper-command*

Command-helper provides some useful commands for checking value or exception.
An advantage of command is to show the test line directly in result.

command.prefix({prefix})		*themis-helper-command-prefix()*
	Use prefix to commands.
	The prefix must start with an uppercase letter.
>
	call themis#helper('command').prefix('Themis')

	function s:suite.test()
	  ThemisAssert 1 + 1 == 2
	endfunction
<
command.with({scope})			*themis-helper-command-with()*
	Add scope to command area.  {scope} is a Dictionary.
	In the command, you can access to function local variables, but can
	not access to script local variables.
	You can access the member of a {scope} Dictionary like a function
	local variable.
>
	let s:assert = themis#helper('assert')
	call themis#helper('command').with(s:)

	function s:suite.test()
	  Assert assert.equals(1 + 1, 2)
	endfunction
<
	If a value of {scope} is a |Funcref|, the key name becomes CamelCase.
>
	let s:assert = themis#helper('assert')
	call themis#helper('command').with(s:assert)

	function s:suite.test()
	  Assert Equals(1 + 1, 2)
	  Assert HasKey({'foo': 0}, 'foo')
	endfunction
<

:Assert {value}				*themis-helper-command-:Assert*
	Checks {value} is truthy value.

:Throws [/{pattern}/] {expr}		*themis-helper-command-:Throws*
:Throws [/{pattern}/] :{command}
	Checks {expr} or {command} throws an exception.
	If {pattern} is given, checks the exception matches the {pattern}.

:Fail {message}				*themis-helper-command-:Fail*
	Fails a test with {message}.

:TODO [{message}]			*themis-helper-command-:TODO*
	Fails a test as TODO with {message}.

:Skip {message}				*themis-helper-command-:Skip*
	Passes a test as SKIP with {message}.

------------------------------------------------------------------------------
EXPECT						*themis-helper-expect*

Expect-helper provides a natural-language-flavored testing style.
First, you should create an expect object by following.
>
	let s:expect = themis#helper('expect')
<
Then, we can use expect-helper like below.
>
	call s:expect(40 + 2).to_equal(42)
<
						*themis-helper-expect-not*
Expect-helper also provides not object.
It is useful to invert the result of the test.
>
	call s:expect(2 + 3).not.to_equal(42)
<
					*themis-helper-expect-with_message()*
If you want to override failure message, you can use with_message().
>
	call s:expect(1).with_message("not equal!").to_be_equal(1)
<
Of course you can easily make a custom matcher.
See |themis#helper#expect#define_matcher()|

expect({value}).to_be_true()		*themis-helper-expect-to_be_true()*
	Checks {value} is 1.

expect({value}).to_be_false()		*themis-helper-expect-to_be_false()*
	Checks {value} is 0.

expect({value}).to_be_truthy()		*themis-helper-expect-to_be_truthy()*
	Checks {value} is truthy value.

expect({value}).to_be_falsy()		*themis-helper-expect-to_be_falsy()*
	Checks {value} is falsy value.

				*themis-helper-expect-to_be_greater_than()*
expect({left}).to_be_greater_than({right})
	Compares by |expr->#|

			*themis-helper-expect-to_be_greater_than_or_equal()*
expect({left}).to_be_greater_than({right})
	Compares by |expr->=#|

				*themis-helper-expect-to_be_less_than()*
expect({left}).to_be_less_than({right})
	Compares by |expr-<#|

			*themis-helper-expect-to_be_less_than_or_equal()*
expect({left}).to_be_less_than_or_equal({right})
	Compares by |expr-<=#|

expect({actual}).to_equal({expect})	*themis-helper-expect-to_equal()*
	Checks an {actual} equals to an {expect}.  (|expr-==#|)

expect({actual}).to_be_same({expect})	*themis-helper-expect-to_be_same()*
	Checks an {actual} sames to an {expect}.  (|expr-is#|)

expect({value}).to_match({pattern})	*themis-helper-expect-to_match()*
	Checks {value} matches to {pattern}.  (|expr-=~#|)

expect({value}).to_be_number()		*themis-helper-expect-to_be_number()*
	Checks type of {value} is |Number|.

expect({value}).to_be_string()		*themis-helper-expect-to_be_string()*
	Checks type of {value} is String.

expect({value}).to_be_func()		*themis-helper-expect-to_be_func()*
	Checks type of {value} is |Funcref|.

expect({value}).to_be_list()		*themis-helper-expect-to_be_list()*
	Checks type of {value} is |List|.

expect({value}).to_be_dict()		*themis-helper-expect-to_be_dict()*
	Checks type of {value} is |Dictionary|.

expect({value}).to_be_float()		*themis-helper-expect-to_be_float()*
	Checks type of {value} is |Float|.

expect({expr}).to_exist()		*themis-helper-expect-to_exist()*
	Checks {expr} by |exists()|.
	Note that this can not use for |local-variable| and |script-variable|.

expect({expr}).to_be_empty()		*themis-helper-expect-to_be_empty()*
	Checks {value} is empty by |empty()|.

					*themis-helper-expect-to_have_length()*
expect({expr}).to_have_length({length})
	Checks length of {value} is {length}.
	{value} is a String, a List, or a Dictionary.
	|len()| is used for length of {value}.

expect({dict}).to_have_key({key})	*themis-helper-expect-to_have_key()*
expect({list}).to_have_key({index})
	When argument of expect() is dictionary, check {key} exists in
	{dict}.
	When argument of expect() is list, check {key} exists in {list}.


					*themis#helper#expect#define_matcher()*
themis#helper#expect#define_matcher({name}, {predicate} [, {meesageexpr}])
	Defines a matcher which name is {name}.
	{predicate} decides how a test result to be success.
	When {predicate} is |Funcref|, it should take one argument at least
	and should return 1 or 0 as a test result. The first argument will be
	consumed by expect function and extra arguments will be used for
	matcher arguments.
	For example,
>
	function CloseTo(actual, value)
	  return a:value - 0.1 < a:actual && a:actual < a:value + 0.1
	endfunction
	call themis#helper#expect#define_matcher('to_be_close_to',
	\ function('CloseTo'))

	call s:expect(1 / 100.0).to_be_close_to(0.0)
	" => Success
<
	When {predicate} is String, it will be evaluated as a Funcref body.
	Inside this string, |a:1|, a:2, ... can be used as arguments.
>
	call themis#helper#expect#define_matcher('to_be_similar_to, 'a:1 ==? a:2')
<
	You can also customize the message which is shown when a test fails
	by specifying {messageexpr}.
	If {messageexpr} is |Funcref|, it should have the following signature.
>
	function MyMessage(not, name, x, y)
	  let name = (a:not ? 'not ' : '') . a:name
	  return printf("You tested '%s' with %s and %s but failed",
	  \ name, a:x, a:y)
	endfunction
<
	In case of the tests using |themis-helper-expect-not|, argument a:not
	becomes 1, otherwise 0. a:name has the name of the current matcher.
	Other arguments are used by an expect function argument and matcher
	arguments. (similar to {predicate})
	For example,
>
	call themis#helper#expect#define_matcher('to_equal2', 'a:1 ==# a:2',
	\ function('MyMessage'))

	call s:expect(1).not.to_equal2(1)
	" => You tested 'not.to_equal' with 1 and 1 but failed.
<
	{messageexpr} can also be specified as |String|. a:not and a:name can
	be used in the same manner as the case of |Funcref|. Also a:1, a:2 ...
	are available.
	For example,
>
	call themis#helper#expect#define_matcher('to_equal3', 'a:1 ==# a:2',
	\ 'printf("You tested %s with %s and %s but failed",
	\ (a:not ? "not " : "") . a:name, a:1, a:2)')

------------------------------------------------------------------------------
SCOPE						*themis-helper-scope*

Scope-helper provides a feature that to access to script-local functions.

scope.funcs({path})			*themis-helper-scope-funcs()*
	Returns a dictionary which contains |script-local| functions with
	{path}.
	{path} is a full path or relative path from 'runtimepath'.
>
	let s:scope = themis#helper('scope')
	let s:myfuncs = s:scope.funcs('autoload/myfuncs.vim')
	call s:myfuncs.foo()  " calls s:foo() in myfuncs.vim

scope.vars({path})			*themis-helper-scope-vars()*
	Returns a dictionary which contains |script-local| variables with
	{path}.
	{path} is a full path or relative path from 'runtimepath'.
>
	let s:scope = themis#helper('scope')
	let s:myvars = s:scope.vars('autoload/myvars.vim')
	echo s:myvars.foo  " echo s:foo in myvars.vim
<
	CAUTION: vars() will temporarily overwrite the target file and
	restore the file, so please be careful if you want to use it.

------------------------------------------------------------------------------
DEPS						*themis-helper-deps*

Deps-helper provides a feature to get and store the plugin dependencies.
This assumes such as library plugin or base plugin that has plugin system.
This helper gets the specified deps to local, and adds it to 'runtimepath'.
Currently, this can get only Git repository, and need `git` command.

deps.dir					*themis-helper-deps-dir*
	Base directory to store the dependencies.
	Default value is set to `fnamemodify({themisrc}, ':h') . '/.deps'` .

deps.git({deps-spec})				*themis-helper-deps-git()*
	Gets a Git repository as deps to local, and adds it to 'runtimepath'.

	When {deps-spec} is a String, it is one of the following forms.
	- GitHub repository such as "owner/repos".
	- URL of Git repository.
	A String value can contain "#branch-name" suffix.  It is a branch name
	following "#".

	When {deps-spec} is a Dictionary, it has the following keys.
	"repos":	(Required)
		String value of {deps-spec} that described in above.
	"name":		(Optional)
		The name of dependency.  This is used as directory name in
		base directory.  If omitted, the last part of "repos" except
		branch name is used.
	"branch":	(Optional)
		The name of branch.  If this is specified, "#branch-name" in
		"repos" has no special mean, treated as is.

	When the deps already exists in local, does not fetch it.
	You need delete old deps if you want to update deps.

	Example:
>
	let s:deps = themis#helper('deps')
	call s:deps.git('kana/vim-textobj-user')

deps.git_cmd					*themis-helper-deps-git_cmd*
	Command name of Git.
	Default: "git"



==============================================================================
REPORTER					*themis-reporter*

Reporter reports the result of tests by each format.
You can specify a reporter by |themis-option-reporter|.

------------------------------------------------------------------------------

tap						*themis-reporter-tap*
Report by TAP(Test Anything Protocol) format.  (http://testanything.org/)

dot						*themis-reporter-dot*
Report by dot style.

spec						*themis-reporter-spec*
Report by spec style.



==============================================================================
TEST RULE					*themis-test-rule*

A unit of a test is a function with no argument.
A result of a test becomes either of following.

- pass
- fail
- pending

See |themis-rule-exception| for detail of result.
A test suite is a |Dictionary| that has some test functions.


------------------------------------------------------------------------------
EXCEPTION					*themis-rule-exception*

If a test throws an exception, the test fails.
Some specialized patterns are processed by themis.
>
	themis: report: {type}: {message}
<
When all characters of {type} are uppercase, a test treated as "pending".


------------------------------------------------------------------------------
VIM BUILTIN ASSERT				*themis-rule-builtin-assert*

Some assertion functions were added after Vim 7.4.944.

- |assert_equal()|
- |assert_notequal()|
- |assert_equalfile()|
- |assert_match()|
- |assert_notmatch()|
- |assert_inrange()|
- |assert_true()|
- |assert_false()|
- |assert_exception()|
- |assert_fails()|
- |assert_beeps()|
- |assert_report()|

themis.vim handles these functions.  You can use these for test.
Note that these functions do not throw an exception, so a test does not stop
when assertion fails.



==============================================================================
CHANGELOG					*themis-changelog*

1.7.0	2021-12-03
	- Add |Blob| support.
	  - Add |themis-helper-assert-is_blob()|.
	  - Add |themis-helper-assert-is_not_blob()|.
	  - |themis-helper-assert-length_of()| accepts a blob.
	- Add |themis-helper-assert-includes()| and
	  |themis-helper-assert-not_includes()|.
	- Add |themis-helper-expect-with_message()|.

1.6.0	2021-09-30
	- Add |themis-helper-assert-not_exists()|.
	- Add |themis-helper-assert-cmd_not_exists()|.
	- Add |themis-helper-deps|.
	- Fix scope of |themis-helper-command|.
	- Fix a bug that couldn't include some keywords in heredoc of vimspec.

1.5.5	2020-11-19
	- Some fixes.

1.5.4	2017-12-28
	- Add type check functions for new types to assert helper.
	- Add |themis-helper-assert-cmd_exists()|.

1.5.3	2017-06-14
	- Add |$THEMIS_ARGS|.
	- Add |themis-helper-scope-vars()|.
	- Some fixes.

1.5.2.1	2016-04-27
	- Fix and improve the scope's behavior of vimspec.
	- Update vital.

1.5.2	2016-04-09
	- Refactoring.
	- Add more test for themis itself.
	- Support Vim builtin assert functions.

1.5.1	2016-03-23
	- Add workaround for Vim 7.4.1068
	- Add symlink support of themis command on MS Windows(Thanks Milly).
	- Fix a bug by which a swapfile is created.

1.5	2015-10-28
	- Add |themis-helper-scope|.
	- Add some aliases to |themis-helper-assert|.
	- Skip test group.
	- Some bug fixes.

1.4.1	2015-03-14
	- Add setting examples for CI services.
	- Add |themis-helper-assert-key_exists()| and
	  |themis-helper-assert-key_not_exists()|.
	- Some bug fixes.

1.4	2014-12-05
	- Lexical scope support for |themis-style-vimspec|.
	- Add |themis#func_alias()|.

1.3	2014-10-06
	- Add |themis-style| feature.
	  - Add |themis-style-vimspec|.

1.2	2014-09-06
	- Add |.themisrc| file feature.
	- Add --reporter-list option(|themis-option-reporter-list|).
	- Add --target option(|themis-option-target|).
	- Assert-helpers take optional argument {message}.
	- Do not load all plugins.
	  - Use "-u NONE" instead of "-u NORC" and load plugins by themis.

1.1	2014-08-05
	- Add tests to themis.vim itself.
	  - This is incomplete.  I will add more tests in the future.
	- Add |themis-helper-command|.
	- Improve |themis-helper-assert|.
	- Improve the output of error.

1.0	2014-06-30
	- Initial version.



==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl