CapybaraSelect2 for select2 version 2/3/4

!!! CapybaraSelect2 detects select2 version automatically

Build Status Maintainability Test Coverage


Add this line to your application's Gemfile:

group :test do
  gem 'capybara-select-2'

And then execute:

$ bundle

Or install it with gem install command:

$ gem install capybara-select-2



# application_system_test_case.rb
class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  include CapybaraSelect2
  include CapybaraSelect2::Helpers # if need specific helpers


# spec_helper.rb
RSpec.configure do |config|
  config.include CapybaraSelect2
  config.include CapybaraSelect2::Helpers # if need specific helpers

[Note] In RSpec tests select2 helper is available out of the box


# env.rb
World CapybaraSelect2
World CapybaraSelect2::Helpers # if need specific helpers



select2 'Buy Milk', from: 'Todo'
select2 'Buy Milk', css: '#todo'
select2 'Buy Milk', xpath: '//div[@id="todo"]'

Selecting two or more options

select2 'Buy Milk', 'Go to gym', from: 'Todo'


select2 'Buy Milk', from: 'Todo', search: true

Searching by text different than an option text

select2 'Buy Milk', from: 'Todo', search: 'Buy'


select2 'Go to gym', from: 'Todo', tag: true

Resolving ambiguous match

# Select the first matching option if there are two or more options with text 'Buy'
select2 'Buy', from: 'Todo', match: :first

Selecting an option by exact text

# Select 'Eat' if there are two or more options with text 'Eat' ('Eat', 'Eat salad')
select2 'Eat', from: 'Todo', exact_text: true

[Note] CSS and XPath selectors must identify an HTML node that wraps select2 element or a select2 element itself (an HTML element with the .select2-container class)


Option Purpose
css Identify select2 element by a CSS selector
xpath Identify select2 element by an XPath selector
from Identify select2 element by a label
label Identify select2 element by a label
search Search for an option by the passed string. Search by an option text if true is passed
tag Create an option
match Specifies Capybara's matching strategy when selecting an option
exact_text Whether an option text must match exactly


Specific select2 helpers that allow more refined access to a select2 control

select2_open label: 'Todo'
select2_search 'Milk', css: '#todo'
select2_select 'Buy Milk', from: 'Todo'
select2_clear xpath: "//div[@id='todo']"
Helper Purpose Options
select2_open(options) Open select2 control label, css, xpath
select2_close Close select2 control -
select2_search(term, options) Type into a select2 search field label, from, css, xpath
select2_select(value, options) Select an option from an opened select2 control label, from, css, xpath, match, exact_text
select2_clear(options) Remove selected options (for multi select only) label, from, css, xpath

See description for each option in the Options section

[Note] Helpers above are not available in tests by default. To use them include CapybaraSelect2::Helpers in your test invironment (see Configuration section)

RSpec matchers

# Check that a select2 option with specified text is present on the page
expect(page).to have_select2_option 'Buy Milk'


See test examples

To see test examples for a specific select2 version, start Sinatra app first:

$ rackup spec/support/select2_examples/

Visit http://localhost:9292/select2/v4.0.5/examples in your browser to see examples for select2 version 4.0.5

Running tests

# run spec cases for all select2 versions
$ bundle exec rspec

# run spec cases for a specific select2 version
$ SELECT2_VERSION=4.0.5 bundle exec rspec spec/shared


  1. Add a test case which covers the bug
  2. Add code which makes the test green
  3. Open pull request


The gem is available as open source under the terms of the MIT License.