{"id":20838876,"url":"https://github.com/andrewradev/vimrunner","last_synced_at":"2025-05-15T05:07:26.965Z","repository":{"id":56897477,"uuid":"2608832","full_name":"AndrewRadev/vimrunner","owner":"AndrewRadev","description":"Control a vim instance through ruby code","archived":false,"fork":false,"pushed_at":"2024-12-21T11:00:47.000Z","size":198,"stargazers_count":241,"open_issues_count":8,"forks_count":13,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-15T05:07:21.245Z","etag":null,"topics":["testing-tool","vim"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AndrewRadev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2011-10-19T20:26:19.000Z","updated_at":"2025-04-12T19:09:36.000Z","dependencies_parsed_at":"2025-01-08T08:00:38.881Z","dependency_job_id":"d17aae99-a904-4d33-ba16-69a680dd275a","html_url":"https://github.com/AndrewRadev/vimrunner","commit_stats":{"total_commits":175,"total_committers":9,"mean_commits":"19.444444444444443","dds":0.24,"last_synced_commit":"9e8343f6f258154dda03d0fa2b8863412e7dc64f"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewRadev%2Fvimrunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewRadev%2Fvimrunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewRadev%2Fvimrunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewRadev%2Fvimrunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndrewRadev","download_url":"https://codeload.github.com/AndrewRadev/vimrunner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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":["testing-tool","vim"],"created_at":"2024-11-18T01:11:45.910Z","updated_at":"2025-05-15T05:07:21.956Z","avatar_url":"https://github.com/AndrewRadev.png","language":"Ruby","readme":"# Vimrunner [![Build Status](https://secure.travis-ci.org/AndrewRadev/vimrunner.svg?branch=master)](http://travis-ci.org/AndrewRadev/vimrunner)\n\nUsing Vim's\n[client/server](http://vimdoc.sourceforge.net/htmldoc/remote.html#clientserver)\nfunctionality, this library exposes a way to spawn a Vim instance and control\nit programatically. Apart from being a fun party trick, this can be used to do\nintegration testing on Vimscript.\n\n![Demo](http://i.andrewradev.com/cb035fee68a149c09c3a252fed91b177.gif)\n\nThe latest stable documentation can be found\n[on rubydoc.info](http://rubydoc.info/gems/vimrunner/frames).\n\nAny issue reports or contributions are very welcome on the\n[GitHub issue tracker](https://github.com/AndrewRadev/Vimrunner/issues).\n\n## Usage\n\nIf you don't already have a running Vim server, Vimrunner can be used in one\nof two main ways:\n\n```ruby\n# Vim will automatically be started and killed.\nVimrunner.start do |vim|\n  vim.edit \"file.txt\"\n  vim.insert \"Hello\"\n  vim.write\nend\n```\n\n```ruby\n# Vim will automatically be started but you must manually kill it when you are\n# finished.\nvim = Vimrunner.start\nvim.edit \"file.txt\"\nvim.insert \"Hello\"\nvim.write\nvim.kill\n```\n\nVimrunner will attempt to start up the most suitable version of Vim available,\nmeaning one of the following:\n\n* `vim` if it supports headlessly creating servers (see [Requirements](#requirements) below for more information);\n* `mvim` if you are on Mac OS X;\n* `gvim`.\n\nIf you wish to always start a GUI Vim (viz. skip using a headless `vim`) then\nyou can use `start_gvim` like so:\n\n```ruby\nVimrunner.start_gvim do |vim|\n  # ...\nend\n```\n\nIf you require an even more specific version of Vim, you can pass the path to\nit by instantiating your own `Server` instance like so:\n\n```ruby\nVimrunner::Server.new(:executable =\u003e \"/path/to/my/specific/vim\").start do |vim|\n  vim.edit \"file.txt\"\nend\n```\n\n(You can also use the non-block form of `start` in both of the above\nexamples.)\n\nCalling `start` (or `start_gvim`) will return a `Client` instance with which\nyou can control Vim. For a full list of methods you can invoke on the remote\nVim instance, check out the `Client`\n[documentation](http://rubydoc.info/gems/vimrunner/Vimrunner/Client).\n\nIf you already have a remote-capable Vim server running, you can connect\nVimrunner to it directly by using `Vimrunner.connect` or `Vimrunner.connect!`\nlike so:\n\n```ruby\n# Assuming a running Vim server called FOO...\nvim = Vimrunner.connect(\"FOO\")\nif vim\n  vim.insert(\"Hello world!\")\nend\n\n# Or, if you're confident there's a running server...\nvim = Vimrunner.connect!(\"FOO\")\nvim.insert(\"Hello world!\")\n```\n\nIn case of failure to find the server `FOO`, the first form will return `nil`,\nwhile the second form will raise an exception.\n\n## Testing\n\nIf you're using Vimrunner for testing vim plugins, a simple way to get up and\nrunning is by requiring the `vimrunner/rspec` file. With that, your\n`spec_helper.rb` would look like this:\n\n``` ruby\nrequire 'vimrunner'\nrequire 'vimrunner/rspec'\n\nVimrunner::RSpec.configure do |config|\n  # Use a single Vim instance for the test suite. Set to false to use an\n  # instance per test (slower, but can be easier to manage).\n  config.reuse_server = true\n\n  # Decide how to start a Vim instance. In this block, an instance should be\n  # spawned and set up with anything project-specific.\n  config.start_vim do\n    vim = Vimrunner.start\n\n    # Or, start a GUI instance:\n    # vim = Vimrunner.start_gvim\n\n    # Setup your plugin in the Vim instance\n    plugin_path = File.expand_path('../..', __FILE__)\n    vim.add_plugin(plugin_path, 'plugin/my_plugin.vim')\n\n    # The returned value is the Client available in the tests.\n    vim\n  end\nend\n```\n\nThis will result in:\n\n- A `vim` helper in every rspec example, returning the configured\n  `Vimrunner::Client` instance.\n- Every example is executed in a separate temporary directory to make it easier\n  to manipulate files.\n- A few helper methods from the `Vimrunner::Testing` module\n  ([documentation](http://rubydoc.info/gems/vimrunner/Vimrunner/Testing)).\n\nThe specs would then look something like this:\n\n``` ruby\nrequire 'spec_helper'\n\ndescribe \"My Vim plugin\" do\n  specify \"some behaviour\" do\n    write_file('test.rb', \u003c\u003c-EOF)\n      def foo\n        bar\n      end\n    EOF\n\n    vim.edit 'test.rb'\n    do_plugin_related_stuff_with(vim)\n    vim.write\n\n    IO.read('test.rb').should eq normalize_string_indent(\u003c\u003c-EOF)\n      def bar\n        foo\n      end\n    EOF\n  end\nend\n```\n\nIf you need a different setup, please look through the file\n`lib/vimrunner/rspec.rb` for ideas on how to build your own testing scaffold.\n\n## Requirements\n\nVim needs to be compiled with `+clientserver`. This should be available with\nthe `normal`, `big` and `huge` featuresets or by using\n[MacVim](http://code.google.com/p/macvim/) on Mac OS X. In order to start a\nserver without a GUI, you will also need `+xterm-clipboard` [as described in\nthe Vim\nmanual](http://vimdoc.sourceforge.net/htmldoc/remote.html#x11-clientserver).\n\nThe client/server functionality (regrettably) needs a running X server to\nfunction, even without a GUI. This means that if you're using it for\nautomated tests on a remote server, you'll probably need to start it with\nXvfb.\n\nIf you are using MacVim, note that you will need the `mvim` binary in your\n`PATH` in order to start and communicate with Vim servers.\n\n## Experimenting\n\nThe `vimrunner` executable opens up an irb session with `$vim` set to a running\n`gvim` (or `mvim`) client. You can use this for interactive experimentation. A\nfew things you can try:\n\n``` ruby\n$vim.edit 'some_file_name'  # edit a file\n$vim.insert 'Hello, World!' # enter insert mode and write some text\n$vim.normal 'T,'            # go back to the nearest comma\n$vim.type 'a\u003ccr\u003e'           # append a newline after the comma\n$vim.write                  # write file to disk\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewradev%2Fvimrunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewradev%2Fvimrunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewradev%2Fvimrunner/lists"}