CapybaraSelect2 for select2 version 2/3/4

!!! CapybaraSelect2 detects select2 version automatically

Installation

Add this line to your application's Gemfile:

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

And then execute:

$ bundle

Or install it with gem install command:

$ gem install capybara-select-2

Configuration

Minitest

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

Rspec

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

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

Cucumber

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

Usage

Examples

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'

Searching

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

Searching by text different than an option text

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

Tagging

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)

Options

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

Helpers

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

select2_open label: 'Todo'
select2_close
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'

Testing

See test examples

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

$ rackup spec/support/select2_examples/config.ru

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

Contributing

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

License

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