166 lines
7.4 KiB
Plaintext
166 lines
7.4 KiB
Plaintext
*UT.txt* Unit Testing Framework for Vim (v0.0.3)
|
||
For Vim version 7+. Last change: $Date: 2010-05-17 19:10:03 -0400 (Mon, 17 May 2010) $
|
||
|
||
By Luc Hermitte
|
||
hermitte {at} free {dot} fr
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
CONTENTS *UT-contents* {{{1
|
||
|UT-presentation| Presentation
|
||
|UT-usage| Usage
|
||
|UT-API| UT API
|
||
|UT-examples| Examples
|
||
|UT-todo| Bugs to fix and futur enhancements to come
|
||
|UT-design| Design choices
|
||
|UT-others| Other tests related plugins for vim
|
||
|add-local-help| Instructions on installing this file
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
PRESENTATION *UT-presentation* {{{1
|
||
UT is another Test Unit Framework for Vim, which main particularity is to fill
|
||
the |quickfix| window with the assertion failures.
|
||
|
||
Features~
|
||
- Assertion failures are reported in the |quickfix| window
|
||
- Assertion syntax is simple, check Tom Link's suite, it's the same
|
||
- Supports banged ":Assert!" to stop processing a given test on failed
|
||
assertions
|
||
- All the |s:Test()| functions of a suite are executed (almost)
|
||
independently (i.e., a critical ":Assert!" failure will stop the Test of
|
||
the function, and |lh#UT| will proceed to the next |s:Test()| function
|
||
- Lightweight and simple to use: there is only one command defined, all the
|
||
other definitions are kept in an autoload plugin.
|
||
- A suite == a file
|
||
- Several |s:Test()| functions per suite
|
||
- +optional |s:Setup()|, |s:Teardown()|
|
||
- Supports |:Comments|
|
||
- |local-function|s, |script-variable|s, and |local-variable|s are supported
|
||
- Takes advantage of |BuildToolsWrapper|'s |:Copen| command if installed
|
||
- Counts successful tests and not successful assertions
|
||
- Short-cuts to run the Unit Tests associated to a given vim script; Relies
|
||
on: |Let-Modeline|, |local_vimrc|/|project.vim| to set |g:UTfiles| (space
|
||
separated list of glob-able paths), and on |lhvl#path|.
|
||
- Command to exclude, or specify the tests to play => |:UTPlay|, |UTIgnore|
|
||
|
||
Requirements~
|
||
This suite requires Vim 7.1 and |lh-vim-lib| v2.2.0+.
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
USAGE *UT-usage* {{{1
|
||
First, create a new vim script, it will be a Unit Testing Suite.
|
||
|
||
*:UTSuite*
|
||
One of the first lines must contain >
|
||
UTSuite Some intelligible name for the suite
|
||
<
|
||
*:Assert*
|
||
Then you are free to directly assert anything you wish as long as it is a
|
||
valid vim |expression|, e.g. >
|
||
Assert 1 > 2
|
||
Assert 1 > 0
|
||
Assert s:foo > s:Bar(g:var + 28) / strlen("foobar")
|
||
or to define as many independent tests as you wish.
|
||
|
||
*:Comment*
|
||
Comments may be added to the |quickfix| report thanks to the |:Comment|
|
||
fake command.
|
||
*s:Test()*
|
||
A test is a function with a name starting with |s:Test|. Even if a test
|
||
critically fails, the next test will be executed, e.g. >
|
||
function s:Test1()
|
||
let var = SomeFucntion()
|
||
Assert! type(var) == type(0)
|
||
Assert var < 42
|
||
Assert! var > 0
|
||
|
||
" Some other code that won't be executed if the previous assertion failed
|
||
let i = var / 42.0
|
||
Comment This comment may never be displayed if {var} is negative or not a number
|
||
endfunction
|
||
|
||
function s:Test2()
|
||
Assert s:what != Ever()
|
||
endfunction
|
||
<
|
||
*s:Setup()* *s:Teardown()*
|
||
If you wish to see a set-up function executed before each test, define the
|
||
|s:Setup()| function.
|
||
|
||
If you wish to see a clean-up function executed after each test, define the
|
||
|s:Teardown()| function.
|
||
|
||
*:UTRun*
|
||
Finally run |:UTRun| on your test script (filename), and ... debug your failed
|
||
assertions from the |quickfix| window.
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
UT API *UT-API* {{{1
|
||
|
||
*should#be#dict()* returns whether the parameter is a |Dictionary|
|
||
*should#be#float()* returns whether the parameter is a |float|
|
||
*should#be#funcref()* returns whether the parameter is a |Funcref|
|
||
*should#be#list()* returns whether the parameter is a |List|
|
||
*should#be#number()* returns whether the parameter is a |expr-number|
|
||
*should#be#string()* returns whether the parameter is a |expr-string|
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
EXAMPLES *UT-examples* {{{1
|
||
See:
|
||
- {rtp}/tests/lh/UT.vim tests/lh/UT.vim for a classical test,
|
||
- {rtp}/tests/lh/UT-fixtures.vim tests/lh/UT-fixtures.vim for a test with
|
||
fixtures.
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
TO DO *UT-todo* {{{1
|
||
- Add |'efm'| for VimL errors like the one produced by >
|
||
:Assert 0 + [0]
|
||
- Check UT works fine under windows (where paths have spaces, etc), and on
|
||
UTF-8 files
|
||
- Simplify "s:errors" functions
|
||
- Merge with Tom Link's tAssert plugin? (the UI is quite different)
|
||
- |:AssertEquals| that shows the name of both expressions and their values as
|
||
well -- a correct distinction of both parameters will be tricky with regexes
|
||
; using functions will loose either the name, or the value in case of
|
||
local/script variables use ; we need macros /<2F> la C/...
|
||
- Support Embedded comments like for instance: >
|
||
Assert 1 == 1 " 1 must value 1
|
||
- Ways to test buffers produced
|
||
- Always execute |s:Teardown()| -- move its call to a |:finally| bloc
|
||
- Find a way to prevent the potential script scope pollution
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
DESIGN CHOICES *UT-design* {{{1
|
||
The assertions supported by this plugin are expected to be made in a Unit
|
||
Testing file, they are not to be used in regular VimL scripts as a /Design by
|
||
Contract/ tool. Check Thomas Link's plugin, it is much more suited for that
|
||
kind of assertions.
|
||
|
||
In order to be able to produce the |quickfix| entries, the plugin first parses
|
||
the Unit Test file to complete all |:Assert| occurrences with extra
|
||
information about the line number where the assertion is made.
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
OTHER TESTS RELATED PLUGINS FOR VIM *UT-others* {{{1
|
||
You may also want to have a look at:
|
||
- Tom Link's |tAssert| plugin
|
||
http://www.vim.org/scripts/script.php?script_id=1730
|
||
- Staale Flock's |vimUnit| plugin
|
||
http://www.vim.org/scripts/script.php?script_id=1125
|
||
- Meikel Brandmeyer's |vimTAP| plugin
|
||
http://www.vim.org/scripts/script.php?script_id=2213
|
||
|
||
|
||
------------------------------------------------------------------------------
|
||
<20> Luc Hermitte, 2010, http://code.google.com/p/lh-vim/
|
||
$Id: UT.txt 193 2010-05-17 23:10:03Z luc.hermitte $
|
||
VIM: let b:VS_language = 'american'
|
||
vim:ts=8:sw=4:tw=80:fo=tcq2:isk=!-~,^*,^\|,^\":ft=help:fdm=marker:
|