{"id":13898845,"url":"https://github.com/LucHermitte/vim-UT","last_synced_at":"2025-07-17T16:31:04.532Z","repository":{"id":28738751,"uuid":"32260155","full_name":"LucHermitte/vim-UT","owner":"LucHermitte","description":"Unit Testing plugin for Vim","archived":false,"fork":false,"pushed_at":"2024-08-26T00:51:20.000Z","size":1924,"stargazers_count":22,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-25T05:30:34.860Z","etag":null,"topics":["assertions","quickfix-window","unit-testing","vim","vim-plugins"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LucHermitte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-15T12:44:25.000Z","updated_at":"2024-10-01T22:54:35.000Z","dependencies_parsed_at":"2024-08-17T22:30:02.969Z","dependency_job_id":"8e4229f4-d02f-41c2-8935-c110cddaa225","html_url":"https://github.com/LucHermitte/vim-UT","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/LucHermitte/vim-UT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Fvim-UT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Fvim-UT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Fvim-UT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Fvim-UT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LucHermitte","download_url":"https://codeload.github.com/LucHermitte/vim-UT/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucHermitte%2Fvim-UT/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265629895,"owners_count":23801488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assertions","quickfix-window","unit-testing","vim","vim-plugins"],"created_at":"2024-08-06T18:04:29.218Z","updated_at":"2025-07-17T16:31:04.124Z","avatar_url":"https://github.com/LucHermitte.png","language":"Vim Script","readme":"# vim-UT [![Last release](https://img.shields.io/github/tag/LucHermitte/vim-UT.svg)](https://github.com/LucHermitte/vim-UT/releases) [![Project Stats](https://www.openhub.net/p/21020/widgets/project_thin_badge.gif)](https://www.openhub.net/p/21020)\n\n## Introduction\n\n_UT_ is another Unit Testing Framework for Vim, which main particularity is to fill the [`quickfix`](http://vimhelp.appspot.com/quickfix.txt.html#quickfix) window with the assertion failures.\n\n## Features\n\n#### Main features\n\n  * Assertion failures are reported in the [`quickfix`](http://vimhelp.appspot.com/quickfix.txt.html#quickfix) window\n  * Meant to be simple to use\n      * Simple assertion syntax (`:Assert expression`, `:AssertEquals(ref, expr)`...)\n      * Supports `:Comments`\n      * Automatic registration of test functions\n          * 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\n      * A suite == a file\n      * Several `s:TestXxx()` per suite\n  * Callstack is decoded and expanded in the quickfix window on uncaught\n    exceptions.\n\n#### Other features\n  * Lightweight and simple to use: there is only one command defined, all the other definitions are kept in an autoload plugin.\n  * Fixtures:\n    * optional `s:Setup()`, `s:Teardown()` executed before and after each test\n    * optional `s:BeforeAll()`, `s:AfterAll()` executed once before and after all tests from a suite\n  * Supports banged `:Assert!` to stop processing a given test on failed assertions\n  * `s:LocalFunctions()`, `s:variables`, and `l:variables` are supported\n  * Buffer content can be set -- with `:SetBufferContent`\n  * Buffer content can be tested -- with `:AssertBufferMatches`\n  * Count successful tests and failed assertions\n  * Command to exclude, or specify the tests to play =\u003e `:UTPlay`, `UTIgnore`\n  * Add [`:debug`](http://vimhelp.appspot.com/repeat.txt.html#%3adebug) before an assertion to debug its evaluation\n  * Short-cuts to run the Unit Tests associated to a given vim script; Relies on: [Let-Modeline](http://github.com/LucHermitte/lh-misc/blob/master/plugin/let-modeline.vim)/[local\\_vimrc](http://github.com/LucHermitte/local_vimrc)/[Project](http://www.vim.org/scripts/script.php?script_id=69) to set `g:UTfiles` (space separated list of glob-able paths), and on [`lh-vim-lib#path`](http://github.com/LucHermitte/lh-vim-lib)\n  * [Helper scripts](doc/rspec-integration.md) are provided to help integration\n    with vimrunner+rspec. See examples of use in\n    [lh-vim-lib](http://github.com/LucHermitte/lh-vim-lib) and\n    [lh-brackets](http://github.com/LucHermitte/lh-brackets).\n  * Takes advantage of [BuildToolsWrapper](http://github.com/LucHermitte/vim-build-tools-wrapper)'s `:COpen` command if installed\n\n## Demo\n\nHere is a little screencast to see how things are displayed when errors are\ndetected.\n\nNotes:\n- the diff-mode is entered with `D` -- sorry, I wasn't able to display the keys\n  typed in this screencast.\n- the signs and balloons are automatically added by\n  [vim-compil-hints](https://github.com/LucHermitte/vim-compil-hints)\n\n![vim-UT demo](doc/screencast-vim-UT.gif \"vim-UT demo\")\n\n## Usage\n\n#### Start-up\n\n  * Create a new vim script, it will be a Unit Testing Suite.\n  * One of the first lines must contain\n\n    ```vim\n    UTSuite Some intelligible name for the suite\n    ```\n\n  * Then you are free to directly assert anything you wish as long as it is a valid vim [`expression`](http://vimhelp.appspot.com/eval.txt.html#expression), e.g.\n\n    ```vim\n    Assert 1 \u003e 2\n    Assert 1 \u003e 0\n    Assert s:foo \u003e s:Bar(g:var + 28) / strlen(\"foobar\")\n\n    debug AssertTxt (s:foo \u003e s:Bar(g:var+28)\n          \\, s:foo.\" isn't bigger than s:Bar(\".g:var.\"+28)\")\n    AssertEquals!('a', 'a')\n    AssertDiffers('a', 'a')\n    let dict = {}\n    AssertIs(dict, dict)\n    AssertIsNot(dict, dict)\n    AssertMatch('abc', 'a')\n    AssertRelation(1, '\u003c', 2)\n    AssertThrows 0 + [0]\n    ```\n\n    ```\n    tests/lh/README.vim|| SUITE \u003c[lh#UT] Demonstrate assertions in README\u003e\n    tests/lh/README.vim|27 error| assertion failed: 1 \u003e 2\n    tests/lh/README.vim|31 error| assertion failed: s:foo \u003e s:Bar(g:var + 28) / strlen(\"foobar\")\n    tests/lh/README.vim|33 error| assertion failed: -1 isn't bigger than s:Bar(5+28)\n    tests/lh/README.vim|37 error| assertion failed: 'a' is not different from 'a'\n    tests/lh/README.vim|40 error| assertion failed: {} is not identical to {}\n    ...\n    ```\n\n  * or to define as many independent tests as you wish. 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.\n\n    ```vim\n    function s:Test1()\n      let var = SomeFunction()\n      Assert! type(var) == type(0)\n      Assert var \u003c 42\n      Assert! var \u003e 0\n\n      \" Some other code that won't be executed if the previous assertion failed\n      \" /*the wiki does not recognizes vim comments*/\n      let i = var / 42.0\n      Comment \"This comment may never be displayed if {var} is negative or not a number\"\n    endfunction\n\n    function s:Test2()\n      Assert s:what != Ever()\n    endfunction\n    ```\n\n  * Now run `:UTRun` on your test script (filename), and ... debug your failed assertions.\n\n#### Fixtures\n\nCode can be executed before and after each test function with the optional\nspecial functions:\n\n  * `s:Setup()`: set-up function executed __before each__ test\n  * `s:Teardown()`: clean-up function executed __after each__ test\n  * `s:BeforeAll()`: set-up function execute once __before all__ tests from a suite\n  * `s:AfterAll()`: clean-up function execute once __after all__ tests from a suite\n\n#### Test on buffers\n\nMost `:AssertXxx` commands are dedicated to unit testing vim functions. A\nfunction returns a result and we test whether its value _equals_, _differs_,\n_matches_, _is_...\n\nSince V2, it's now possible set the content of a buffer before transforming it,\nand to test whether the new buffer state is as expected.\n\nWithin the quickfix-window, we can hit `D` on the message associated to a\nbuffer matching failure in order to display, in a new\n[`tabpage`](http://vimhelp.appspot.com/tabpage.txt.html#tabpage), the expected\ncontent alongside the expected content in\n[`diff-mode`](http://vimhelp.appspot.com/diff.txt.html#diff%2dmode).\n\nThe diff-mode can be exited by hitting `q` from any scratch buffer involded.\n\n```vim\nsilent! call lh#window#create_window_with('new') \" work around possible E36\ntry\n    SetBufferContent a/file/name.txt\n    %s/.*/\\U\u0026/\n    AssertBufferMatch a/file/NAME.txt\nfinally\n    bw\nendtry\n```\n\nOr, with [`:let=\u003c\u003c`](http://vimhelp.appspot.com/eval.txt.html#%3alet%3d%3c%3c)\nsyntax\n\n```vim\nsilent! call lh#window#create_window_with('new') \" work around possible E36\ntry\n    SetBufferContent \u003c\u003c trim EOF\n    1\n    3\n    2\n    EOF\n\n    %sort\n\n    AssertBufferMatch \u003c\u003c trim EOF\n    1\n    4\n    3\n    EOF\nfinally\n    silent bw!\nendtry\n```\n\nwhich results into\n\n```\ntests/lh/README.vim|78 error| assertion failed: Observed buffer does not match Expected reference:\n|| ---\n|| +++\n|| @@ -1,3 +1,3 @@\n||  1\n|| -4\n|| +2\n||  3\n```\n\n__Note__: `:SetBufferContent` and `:AssertBufferMatch` with `\u003c\u003c [trim] EOF`\nsyntax can only be used within `s:TestXxx` functions.\n\n#### Examples\nSee:\n  * [tests/lh/UT.vim](tests/lh/UT.vim) for a classical test,\n  * [tests/lh/UT-fixtures.vim](tests/lh/UT-fixtures.vim) for a test with fixtures.\n  * [tests/lh/UT-buf.vim](tests/lh/UT-buf.vim) for tests on buffer content.\n\n\n## To Do\n  * Check UT works fine under windows (where paths have spaces, etc.), and on UTF-8 files\n  * Simplify `s:errors` functions\n  * Support Embedded comments like for instance:\n\n    ```vim\n    Assert 1 == 1 \" 1 must value 1\n    ```\n\n  * Ways to test buffers produced\n  * Find a way to prevent the potential script scope pollution\n  * Add a summary at the end of the execution\n\n\n## Design Choices\n  * 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 my [DbC framework](http://github.com/LucHermitte/lh-vim-lib/tree/master/doc/DbC.md) in lh-vim-lib, or even Thomas Link's plugin, it is much more suited for that kind of assertions.\n\n  * 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. Incidentally, this permits to reduce plugin footprint: none of `:AssertXXX` commands are actual commands.\n\n## Installation\n  * Requirements: Vim 7.+, [lh-vim-lib](http://github.com/LucHermitte/lh-vim-lib) v5.1.0\n  * With [vim-addon-manager](https://github.com/MarcWeber/vim-addon-manager), install vim-UT (this is the preferred method because of the dependencies)\n\n    ```vim\n    ActivateAddons UT\n    ```\n\n  * or with [vim-flavor](http://github.com/kana/vim-flavor), which also handles\n    dependencies\n\n    ```\n    flavor 'LucHermitte/vim-UT'\n    ```\n  * or you can clone the git repositories\n\n    ```bash\n    git clone git@github.com:LucHermitte/lh-vim-lib.git\n    git clone git@github.com:LucHermitte/vim-UT.git\n    ```\n\n  * or with Vundle/NeoBundle:\n\n    ```vim\n    Bundle 'LucHermitte/lh-vim-lib'\n    Bundle 'LucHermitte/vim-UT'\n    ```\n\n## Other Tests related plugins for Vim\n  * Tom Link's [tAssert plugin](http://www.vim.org/scripts/script.php?script_id=1730), and [spec\\_vim plugin](https://github.com/tomtom/spec_vim),\n  * Staale Flock's [vimUnit plugin](http://www.vim.org/scripts/script.php?script_id=1125),\n  * Meikel Brandmeyer's [vimTAP plugin](http://www.vim.org/scripts/script.php?script_id=2213),\n  * Ben Fritz's [vim-2html-test](http://code.google.com/p/vim-2html-test/) plugin,\n  * Ingo Karkat's [runVimTests plugin](http://www.vim.org/scripts/script.php?script_id=2565),\n  * See also Paul Mucur article's: [Testing Vim Plugins on Travis CI with RSpec and Vimrunner](http://mudge.github.com/2012/04/18/testing-vim-plugins-on-travis-ci-with-rspec-and-vimrunner.html),\n  * Andrew Radev's [vimrunner](http://github.com/AndrewRadev/vimrunner),\n  * Kana's [vim-spec](http://github.com/kana/vim-spec)\n  * Dhruva Sagar's [vim-testify](https://github.com/dhruvasagar/vim-testify)\n\n","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLucHermitte%2Fvim-UT","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLucHermitte%2Fvim-UT","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLucHermitte%2Fvim-UT/lists"}