No release in over 3 years
Low commit activity in last 3 years
Capybara helpers for https://select2.org select box (supports Select2 versions 2/3/4)
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 2.0
~> 3.31
~> 0.12
~> 4.3
~> 13.0
~> 3.9
~> 0.18
~> 2.0
 Project Readme

CapybaraSelect2 for select2 version 2/3/4

!!! CapybaraSelect2 detects select2 version automatically

Build Status Maintainability Test Coverage

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.