capybara package¶

Subpackages¶

Submodules¶

capybara.compat module¶

capybara.compat.cmp(a, b)[source]¶

capybara.dsl module¶

capybara.dsl.page = <capybara.dsl.Page object>¶: The singleton current-session proxy object.

capybara.dsl.assert_no_title(self, title, **kwargs)¶

Asserts that the page doesn’t have the given title.

Parameters:	title (str \| RegexObject) – The string that the title should include. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

capybara.dsl.assert_title(self, title, **kwargs)¶

Asserts that the page has the given title.

Parameters:	title (str \| RegexObject) – The string or regex that the title should match. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

capybara.dsl.has_no_title(self, title, **kwargs)¶

Checks if the page doesn’t have the given title.

Parameters:	title (str \| RegexObject) – The string that the title should include. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	Whether it doesn’t match.
Return type:	bool

capybara.dsl.has_title(self, title, **kwargs)¶

Checks if the page has the given title.

Parameters:	title (str \| RegexObject) – The string or regex that the title should match. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	Whether it matches.
Return type:	bool

capybara.dsl.assert_all_of_selectors(self, selector, *locators, **kwargs)¶

Asserts that all of the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_all_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_all_of_selectors("css", "#my_dif", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so all of the locators must be present within wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.assert_no_selector(self, *args, **kwargs)¶

Asserts that a given selector is not on the page or a descendant of the current node. Usage is identical to assert_selector().

Query options such as count, minimum, and between are considered to be an integral part of the selector. This will return True, for example, if a page contains 4 anchors but the query expects 5:

page.assert_no_selector("a", minimum=1)  # Found, raises ExpectationNotMet
page.assert_no_selector("a", count=4)    # Found, raises ExpectationNotMet
page.assert_no_selector("a", count=5)    # Not Found, returns True

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – The given selector matched.

capybara.dsl.assert_none_of_selectors(self, selector, *locators, **kwargs)¶

Asserts that none of the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_none_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_none_of_selectors("css", "#my_div", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so none of the locators must be present with wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.assert_no_text(self, *args, **kwargs)¶

Asserts that the page or current node doesn’t have the given text content, ignoring any HTML tags.

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

capybara.dsl.assert_selector(self, *args, **kwargs)¶

Asserts that a given selector is on the page or a descendant of the current node.

page.assert_selector("p#foo")

By default it will check if the expression occurs at least once, but a different number can be specified.

page.assert_selector("p.foo", count=4)

This will check if the expression occurs exactly 4 times. See find_all() for other available result size options.

If a count of 0 is specified, it will behave like assert_no_selector(); however, use of that method is preferred over this one.

It also accepts all options that find_all() accepts, such as text and visible.

page.assert_selector("li", text="Horse", visible=True)

assert_selector can also accept XPath expressions generated by the xpath-py package:

from xpath import dsl as x

page.assert_selector("xpath", x.descendant("p"))

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – The given selector did not match.

capybara.dsl.assert_style(self, styles, **kwargs)¶

Asserts that an element has the specified CSS styles.

element.assert_style({"color": "rgb(0,0,255)", "font-size": re.compile(r"px")})

Parameters:	styles (Dict[str, str \| RegexObject]) – The expected styles.
Returns:	True
Raises:	`ExpectationNotMet` – The element doesn’t have the specified styles.

capybara.dsl.assert_text(self, *args, **kwargs)¶

Asserts that the page or current node has the given text content, ignoring any HTML tags.

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

capybara.dsl.attach_file(self, locator_or_path, path=None, **kwargs)¶

Find a file field on the page and attach a file given its path. The file field can be found via its name, id, or label text.

page.attach_file(locator, "/path/to/file.png")

Parameters:	locator_or_path (str) – Which field to attach the file to, or the path of the file that will be attached. path (str, optional) – The path of the file that will be attached. Defaults to `locator_or_path`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Raises:	`FileNotFound` – No file exists at the given path.

capybara.dsl.check(self, locator=None, allow_label_click=None, **kwargs)¶

Find a check box and mark it as checked. The check box can be found via name, id, or label text.

page.check("German")

Parameters:	locator (str, optional) – Which check box to check. allow_label_click (bool, optional) – Attempt to click the label to toggle state if element is non-visible. Defaults to `capybara.automatic_label_click`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.choose(self, locator=None, allow_label_click=None, **kwargs)¶

Find a radio button and mark it as checked. The radio button can be found via name, id, or label text.

page.choose("Male")

Parameters:	locator (str, optional) – Which radio button to choose. allow_label_click (bool, optional) – Attempt to click the label to toggle state if element is non-visible. Defaults to `capybara.automatic_label_click`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.click_button(self, locator=None, **kwargs)¶

Finds a button on the page and clicks it. This can be any <input> element of type submit, reset, image, or button, or it can be any <button> element. All buttons can be found by their id, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute.

Parameters:	locator (str, optional) – Which button to find. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.click_link(self, locator=None, **kwargs)¶

Finds a link by id, text, or title and clicks it. Also looks at image alt text inside the link.

Parameters:	locator (str, optional) – Text, id, title, or nested image’s alt attribute. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.click_link_or_button(self, locator=None, **kwargs)¶

Finds a button or link by id, text or value and clicks it. Also looks at image alt text inside the link.

Parameters:	locator (str, optional) – Text, id, or value of link or button. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.click_on(self, locator=None, **kwargs)¶

Finds a button or link by id, text or value and clicks it. Also looks at image alt text inside the link.

Parameters:	locator (str, optional) – Text, id, or value of link or button. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.fill_in(self, locator=None, current_value=None, value=None, fill_options=None, **kwargs)¶

Locate a text field or text area and fill it in with the given text. The field can be found via its name, id, or label text.

page.fill_in("Name", value="Bob")

Parameters:	locator (str, optional) – Which field to fill in. current_value (str, optional) – The current value of the field. value (str, optional) – The value to fill in. Defaults to None. fill_options (Dict, optional) – Driver-specific options regarding how to fill fields. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.find(self, *args, **kwargs)¶

Find an Element based on the given arguments. find will raise an error if the element is not found.

find takes the same options as find_all().

page.find("#foo").find(".bar")
page.find("xpath", "//div[contains(., 'bar')]")
page.find("li", text="Quox").click_link("Delete")

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element
Raises:	`Ambiguous` – If more than one element matching element is found. `ElementNotFound` – If the element can’t be found before time expires.

capybara.dsl.find_all(self, *args, **kwargs)¶

Find all elements on the page matching the given selector and options.

Both XPath and CSS expressions are supported, but Capybara does not try to automatically distinguish between them. The following statements are equivalent:

page.find_all("css", "a#person_123")
page.find_all("xpath", "//a[@id='person_123']")

If the type of selector is left out, Capybara uses capybara.default_selector. It’s set to "css" by default.

page.find_all("a#person_123")

capybara.default_selector = "xpath"
page.find_all("//a[@id='person_123']")

The set of found elements can further be restricted by specifying options. It’s possible to select elements by their text or visibility:

page.find_all("a", text="Home")
page.find_all("#menu li", visible=True)

By default if no elements are found, an empty list is returned; however, expectations can be set on the number of elements to be found which will trigger Capybara’s waiting behavior for the expectations to match. The expectations can be set using:

page.assert_selector("p#foo", count=4)
page.assert_selector("p#foo", maximum=10)
page.assert_selector("p#foo", minimum=1)
page.assert_selector("p#foo", between=range(1, 11))

See capybara.result.Result.matches_count() for additional information about count matching.

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	A collection of found elements.
Return type:	Result
Raises:	`ExpectationNotMet` – The matched results did not meet the expected criteria.

capybara.dsl.find_button(self, locator=None, **kwargs)¶

Find a button on the page. This can be any <input> element of type submit, reset, image, or button, or it can be a <button> element. All buttons can be found by their id, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute.

Parameters:	locator (str, optional) – The id, value, title, text content, alt of image. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

capybara.dsl.find_by_id(self, id, **kwargs)¶

Find an element on the page, given its id.

Parameters:	id (str) – The id of the element. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

capybara.dsl.find_field(self, locator=None, **kwargs)¶

Find a form field on the page. The field can be found by its name, id, or label text.

Parameters:	locator (str, optional) – Name, id, placeholder, or text of associated label element. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

capybara.dsl.find_first(self, *args, **kwargs)¶

Find the first element on the page matching the given selector and options, or None if no element matches.

By default, no waiting behavior occurs. However, if capybara.wait_on_first_by_default is set to true, it will trigger Capybara’s waiting behavior for a minimum of 1 matching element to be found.

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element or None.
Return type:	Element

capybara.dsl.find_link(self, locator=None, **kwargs)¶

Find a link on the page. The link can be found by its id or text.

Parameters:	locator (str, optional) – ID, title, text, or alt of enclosed img element. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

capybara.dsl.has_all_of_selectors(self, selector, *locators, **kwargs)¶

Checks if allof the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_all_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_all_of_selectors("css", "#my_dif", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so all of the locators must be present within wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.has_button(self, locator, **kwargs)¶

Checks if the page or current node has a button with the given text, value, or id.

Parameters:	locator (str) – The text, value, or id of a button to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_checked_field(self, locator, **kwargs)¶

Checks if the page or current node has a radio button or checkbox with the given label, value, or id, that is currently checked.

Parameters:	locator (str) – The label, name, or id of a checked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_content(self, *args, **kwargs)¶

Checks if the page or current node has the given text content, ignoring any HTML tags.

Whitespaces are normalized in both the node’s text and the passed text parameter. Note that whitespace isn’t normalized in a passed regular expression as normalizing whitespace in a regular expression isn’t easy and doesn’t seem to be worth it.

By default it will check if the text occurs at least once, but a different number can be specified.

page.has_text("lorem ipsum", between=range(2, 5))

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_css(self, path, **kwargs)¶

Checks if a given CSS selector is on the page or a descendant of the current node.

page.has_css("p#foo")

By default it will check if the selector occurs at least once, but a different number can be specified.

page.has_css("p#foo", count=4)

This will check if the selector occurs exactly 4 times.

It also accepts all options that find_all() accepts, such as text and visible.

page.has_css("li", text="Horse", visible=True)

Parameters:	path (str) – A CSS selector. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the selector exists.
Return type:	bool

capybara.dsl.has_field(self, locator, **kwargs)¶

Checks if the page or current node has a form field with the given label, name, or id.

For text fields and other textual fields, such as textareas and HTML5 email/url/etc. fields, it’s possible to specify a value argument to specify the text the field should contain:

page.has_field("Name", value="Jonas")

Parameters:	locator (str) – The label, name, or id of a field to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_link(self, locator, **kwargs)¶

Checks if the page or current node has a link with the given text or id.

Parameters:	locator (str) – The text or id of a link to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_no_button(self, locator, **kwargs)¶

Checks if the page or current node has no button with the given text, value, or id.

Parameters:	locator (str) – The text, value, or id of a button to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_checked_field(self, locator, **kwargs)¶

Checks if the page or current node has no radio button or checkbox with the given label, value, or id that is currently checked.

Parameters:	locator (str) – The label, name, or id of a checked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_css(self, path, **kwargs)¶

Checks if a given CSS selector is not on the page or a descendant of the current node. Usage is identical to has_css().

Parameters:	path (str) – A CSS Selector. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the selector does not exist.
Return type:	bool

capybara.dsl.has_no_field(self, locator, **kwargs)¶

Checks if the page or current node has no form field with the given label, name, or id. See has_field().

Parameters:	locator (str) – The label, name, or id of a field to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_link(self, locator, **kwargs)¶

Checks if the page or current node has no link with the given text or id.

Parameters:	locator (str) – The text or id of a link to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_select(self, locator, **kwargs)¶

Checks if the page or current node has no select field with the given label, name, or id. See has_select().

Parameters:	locator (str) – The label, name, or id of a select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_selector(self, *args, **kwargs)¶

Checks if a given selector is not on the page or a descendant of the current node. Usage is identical to has_selector().

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_table(self, locator, **kwargs)¶

Checks if the page or current node has no table with the given id or caption. See has_table().

Parameters:	locator (str) – The id or caption of a table. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_text(self, *args, **kwargs)¶

Checks if the page or current node does not have the given text content, ignoring any HTML tags and normalizing whitespace.

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_unchecked_field(self, locator, **kwargs)¶

Checks if the page or current node has no radio button or checkbox with the given label, value, or id, that is currently unchecked.

Parameters:	locator (str) – The label, name, or id of an unchecked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

capybara.dsl.has_no_xpath(self, path, **kwargs)¶

Checks if a given XPath expression is not on the page or a descendant of the current node. Usage is identical to has_xpath().

Parameters:	path (str) – An XPath expression. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the expression does not exist.
Return type:	bool

capybara.dsl.has_none_of_selectors(self, selector, *locators, **kwargs)¶

Checks if none of the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_none_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_none_of_selectors("css", "#my_div", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so none of the locators must be present with wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.has_select(self, locator, **kwargs)¶

Checks if the page or current node has a select field with the given label, name, or id.

It can be specified which option should currently be selected:

page.has_select("Language", selected="German")

For multiple select boxes, several options may be specified:

page.has_select("Language", selected=["English", "German"])

It’s also possible to check if the exact set of options exists for this select box:

page.has_select("Language", options=["English", "German", "Spanish"])

You can also check for a partial set of options:

page.has_select("Language", with_options=["English", "German"])

Parameters:	locator (str) – The label, name, or id of a select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_selector(self, *args, **kwargs)¶

Checks if a given selector is on the page or a descendant of the current node.

page.has_selector("p#foo")
page.has_selector("xpath", ".//p[@id='foo']")

By default it will check if the expression occurs at least once, but a different number can be specified.

page.has_selector("p.foo", count=4)

This will check if the expression occurs exactly 4 times.

It also accepts all options that find_all() accepts, such as text and visible.

page.has_selector("li", text="Horse", visible=True)

has_selector can also accept XPath expressions generated by the xpath-py package:

from xpath import dsl as x

page.has_selector("xpath", x.descendant("p"))

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the expression exists.
Return type:	bool

capybara.dsl.has_table(self, locator, **kwargs)¶

Checks if the page or current node has a table with the given id or caption:

page.has_table("People")

Parameters:	locator (str) – The id or caption of a table. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_text(self, *args, **kwargs)¶

Checks if the page or current node has the given text content, ignoring any HTML tags.

Whitespaces are normalized in both the node’s text and the passed text parameter. Note that whitespace isn’t normalized in a passed regular expression as normalizing whitespace in a regular expression isn’t easy and doesn’t seem to be worth it.

By default it will check if the text occurs at least once, but a different number can be specified.

page.has_text("lorem ipsum", between=range(2, 5))

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_unchecked_field(self, locator, **kwargs)¶

Checks if the page or current node has a radio button or checkbox with the given label, value, or id, that is currently unchecked.

Parameters:	locator (str) – The label, name, or id of an unchecked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

capybara.dsl.has_xpath(self, query, **kwargs)¶

Checks if a given XPath expression is on the page or a descendant of the current node.

session.has_xpath(".//p[@id='foo']")

has_xpath can also accept XPath expressions generated by the xpath-py package:

from xpath import dsl as x

session.has_xpath(x.descendant("p"))

Parameters:	query (str) – An XPath expression. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the expression exists.
Return type:	bool

capybara.dsl.select(self, value=None, field=None, **kwargs)¶

If the field argument is present, select finds a select box on the page and selects a particular option from it. Otherwise it finds an option inside the current scope and selects it. If the select box is a multiple select, select can be called multiple times to select more than one option. The select box can be found via its name, id, or label text. The option can be found by its text.

page.select("March", field="Month")

Parameters:	value (str, optional) – Which option to select. field (str, optional) – The id, name, or label of the select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.uncheck(self, locator=None, allow_label_click=None, **kwargs)¶

Find a check box and uncheck it. The check box can be found via name, id, or label text.

page.uncheck("German")

Parameters:	locator (str, optional) – Which check box to uncheck. allow_label_click (bool, optional) – Attempt to click the label to toggle state if element is non-visible. Defaults to `capybara.automatic_label_click`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.unselect(self, value=None, field=None, **kwargs)¶

Find a select box on the page and unselect a particular option from it. If the select box is a multiple select, unselect can be called multiple times to unselect more than one option. The select box can be found via its name, id, or label text.

page.unselect("March", field="Month")

Parameters:	value (str, optional) – Which option to unselect. field (str, optional) – The id, name, or label of the select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

capybara.dsl.accept_alert(self, text=None, wait=None)¶

Execute the wrapped code, accepting an alert.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

capybara.dsl.accept_confirm(self, text=None, wait=None)¶

Execute the wrapped code, accepting a confirm.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

capybara.dsl.accept_prompt(self, text=None, response=None, wait=None)¶

Execute the wrapped code, accepting a prompt, optionally responding to the prompt.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. response (str, optional) – Response to provide to the prompt. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

capybara.dsl.assert_current_path(self, path, **kwargs)¶

Asserts that the page has the given path. By default this will compare against the path+query portion of the full URL.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

capybara.dsl.assert_no_current_path(self, path, **kwargs)¶

Asserts that the page doesn’t have the given path.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

capybara.dsl.dismiss_confirm(self, text=None, wait=None)¶

Execute the wrapped code, dismissing a confirm.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

capybara.dsl.dismiss_prompt(self, text=None, wait=None)¶

Execute the wrapped code, dismissing a prompt.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

capybara.dsl.evaluate_async_script(self, script, *args)¶

Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.

Parameters:	script (str) – A string of JavaScript to evaluate. *args – Variable length argument list to pass to the executed JavaScript string.
Returns:	The result of the evaluated JavaScript (may be driver specific).
Return type:	object

capybara.dsl.evaluate_script(self, script, *args)¶

Evaluate the given JavaScript and return the result. Be careful when using this with scripts that return complex objects, such as jQuery statements. execute_script() might be a better alternative.

Parameters:	script (str) – A string of JavaScript to evaluate. *args – Variable length argument list to pass to the executed JavaScript string.
Returns:	The result of the evaluated JavaScript (may be driver specific).
Return type:	object

capybara.dsl.execute_script(self, script, *args)¶

Execute the given script, not returning a result. This is useful for scripts that return complex objects, such as jQuery statements. execute_script should be used over evaluate_script() whenever possible.

Parameters:	script (str) – A string of JavaScript to execute. *args – Variable length argument list to pass to the executed JavaScript string.

capybara.dsl.fieldset(self, locator)¶

Execute the wrapped code within a specific fieldset given the id or legend of that fieldset.

Parameters:	locator (str) – The id or legend of the fieldset.

capybara.dsl.frame(self, locator=None, *args, **kwargs)¶

Execute the wrapped code within the given iframe using the given frame or frame name/id. May not be supported by all drivers.

Parameters:	locator (str \| Element, optional) – The name/id of the frame or the frame’s element. Defaults to the only frame in the document.

capybara.dsl.go_back(self)¶: Move back a single entry in the browser’s history.

capybara.dsl.go_forward(self)¶: Move forward a single entry in the browser’s history.

capybara.dsl.has_current_path(self, path, **kwargs)¶

Checks if the page has the given path.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	Whether it matches.
Return type:	bool

capybara.dsl.has_no_current_path(self, path, **kwargs)¶

Checks if the page doesn’t have the given path.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	Whether it doesn’t match.
Return type:	bool

capybara.dsl.open_new_window(self)¶

Open new window. The current window doesn’t change as a result of this call. It should be switched explicitly.

Returns:	The window that has been opened.
Return type:	Window

capybara.dsl.refresh(self)¶: Refresh the page.

capybara.dsl.reset(self)¶

Reset the session (i.e., remove cookies and navigate to a blank page).

This method does not: * accept modal dialogs if they are present (the Selenium driver does, but others may not), * clear the browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc., or * modify the state of the driver/underlying browser in any other way

as doing so would result in performance downsides and it’s not needed to do everything from the list above for most apps.

If you want to do anything from the list above on a general basis you can write a test teardown method.

capybara.dsl.save_page(self, path=None)¶

Save a snapshot of the page.

If invoked without arguments, it will save a file to capybara.save_path and the file will be given a randomly generated filename. If invoked with a relative path, the path will be relative to capybara.save_path.

Parameters:	path (str, optional) – The path to where it should be saved.
Returns:	The path to which the file was saved.
Return type:	str

capybara.dsl.save_screenshot(self, path=None, **kwargs)¶

Save a screenshot of the page.

If invoked without arguments, it will save a file to capybara.save_path and the file will be given a randomly generated filename. If invoked with a relative path, the path will be relative to capybara.save_path.

Parameters:	path (str, optional) – The path to where it should be saved. **kwargs – Arbitrary keywords arguments for the driver.
Returns:	The path to which the file was saved.
Return type:	str

capybara.dsl.scope(self, *args, **kwargs)¶

Executes the wrapped code within the context of a node. scope takes the same options as find(). For the duration of the context, any command to Capybara will be handled as though it were scoped to the given element.

with scope("xpath", "//div[@id='delivery-address']"):
    fill_in("Street", value="12 Main Street")

Just as with find(), if multiple elements match the selector given to scope, an error will be raised, and just as with find(), this behavior can be controlled through the match and exact options.

It is possible to omit the first argument, in that case, the selector is assumed to be of the type set in capybara.default_selector.

with scope("div#delivery-address"):
    fill_in("Street", value="12 Main Street")

Note that a lot of uses of scope can be replaced more succinctly with chaining:

find("div#delivery-address").fill_in("Street", value="12 Main Street")

Parameters:	args – Variable length argument list for the call to `find()`. *kwargs – Arbitrary keywords arguments for the call to `find()`.

capybara.dsl.switch_to_frame(self, frame)¶

Switch to the given frame.

If you use this method you are responsible for making sure you switch back to the parent frame when done in the frame changed to. frame() is preferred over this method and should be used when possible. May not be supported by all drivers.

Parameters:	frame (Element \| str) – The iframe/frame element to switch to.

capybara.dsl.switch_to_window(self, window, wait=None)¶

If window is a lambda, it switches to the first window for which window returns a value other than False or None. If a window that matches can’t be found, the window will be switched back and WindowError will be raised.

Parameters:	window (Window \| lambda) – The window that should be switched to, or a filtering lambda. wait (int \| float, optional) – The number of seconds to wait to find the window.
Returns:	The new current window.
Return type:	Window
Raises:	`ScopeError` – If this method is invoked inside scope, :meth:`frame(), or `window()`. `WindowError` – If no window matches the given lambda.

capybara.dsl.table(self, locator)¶

Execute the wrapped code within a specific table given the id or caption of that table.

Parameters:	locator (str) – The id or caption of the table.

capybara.dsl.visit(self, visit_uri)¶

Navigate to the given URL. The URL can either be a relative URL or an absolute URL. The behavior of either depends on the driver.

session.visit("/foo")
session.visit("http://google.com")

For drivers which can run against an external application, such as the Selenium driver, giving an absolute URL will navigate to that page. This allows testing applications running on remote servers. For these drivers, setting capybara.app_host will make the remote server the default. For example:

capybara.app_host = "http://google.com"
session.visit("/")  # visits the Google homepage

Parameters:	visit_uri (str) – The URL to navigate to.

capybara.dsl.window(self, window)¶

This method does the following:

Switches to the given window (it can be located by window instance/lambda/string).
Executes the given block (within window located at previous step).
Switches back (this step will be invoked even if exception happens at second step).

Parameters:	window (Window \| lambda) – The desired `Window`, or a lambda that will be run in the context of each open window and returns `True` for the desired window.

capybara.dsl.window_opened_by(self, trigger_func, wait=None)¶

Get the window that has been opened by the passed lambda. It will wait for it to be opened (in the same way as other Capybara methods wait). It’s better to use this method than windows[-1] as order of windows isn’t defined in some drivers.

Parameters:	trigger_func (func) – The function that should trigger the opening of a new window. wait (int \| float, optional) – Maximum wait time. Defaults to `capybara.default_max_wait_time`.
Returns:	The window that has been opened within the lambda.
Return type:	Window
Raises:	`WindowError` – If lambda passed to window hasn’t opened window or opened more than one window.

capybara.dsl.using_session(name)[source]¶

Execute the wrapped code using a specific session name.

Parameters:	name (str) – The name of the session to use.

capybara.dsl.using_wait_time(seconds)[source]¶

Execute a context using a specific wait time.

Parameters:	seconds (int \| float) – The new wait time.

capybara.exceptions module¶

exception capybara.exceptions.Ambiguous[source]¶: Bases: capybara.exceptions.ElementNotFound

exception capybara.exceptions.CapybaraError[source]¶: Bases: Exception

exception capybara.exceptions.ElementNotFound[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.ExpectationNotMet[source]¶: Bases: capybara.exceptions.ElementNotFound

exception capybara.exceptions.FileNotFound[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.FrozenInTime[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.ModalNotFound[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.ReadOnlyElementError[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.ScopeError[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.UnselectNotAllowed[source]¶: Bases: capybara.exceptions.CapybaraError

exception capybara.exceptions.WindowError[source]¶: Bases: capybara.exceptions.CapybaraError

capybara.helpers module¶

class capybara.helpers.Timer(expire_in)[source]¶

Bases: object

Parameters:	expire_in (int) – The number of seconds from now in which this timer should expire.

expired¶: bool – Whether this timer has expired.

stalled¶: bool – Whether this timer appears to have stalled.

capybara.helpers.declension(singular, plural, count)[source]¶

Returns the appropriate word variation for the given quantity.

Parameters:	singular (str) – The singular variation. plural (str) – The plural variation. count (int) – The count.
Returns:	The appropriate variation for the quantity.
Return type:	str

capybara.helpers.desc(value)[source]¶: str: A normalized representation for a user-provided value.

capybara.helpers.expects_none(options)[source]¶

Returns whether the given query options expect a possible count of zero.

Parameters:	options (Dict[str, int \| Iterable[int]]) – A dictionary of query options.
Returns:	Whether a possible count of zero is expected.
Return type:	bool

capybara.helpers.failure_message(description, options)[source]¶

Returns a expectation failure message for the given query description.

Parameters:	description (str) – A description of the failed query. options (Dict[str, Any]) – The query options.
Returns:	A message describing the failure.
Return type:	str

capybara.helpers.matches_count(count, options)[source]¶

Returns whether the given count matches the given query options.

If no quantity options are specified, any count is considered acceptable.

Parameters:	count (int) – The count to be validated. options (Dict[str, int \| Iterable[int]]) – A dictionary of query options.
Returns:	Whether the count matches the options.
Return type:	bool

capybara.helpers.monotonic()[source]¶: float: Returns the current time, using a monotonic clock where available.

capybara.helpers.normalize_text(value)[source]¶

Normalizes the given value to a string of text with extra whitespace removed.

Byte sequences are decoded. None is converted to an empty string. Everything else is simply cast to a string.

Parameters:	value (Any) – The data to normalize.
Returns:	The normalized text.
Return type:	str

capybara.helpers.normalize_whitespace(text)[source]¶

Returns the given text with outer whitespace removed and inner whitespace collapsed.

Parameters:	text (str) – The text to normalize.
Returns:	The normalized text.
Return type:	str

capybara.helpers.toregex(text, exact=False)[source]¶

Returns a compiled regular expression for the given text.

Parameters:	text (str \| RegexObject) – The text to match. exact (bool, optional) – Whether the generated regular expression should match exact strings. Defaults to False.
Returns:	A compiled regular expression that will match the text.
Return type:	RegexObject

capybara.html module¶

class capybara.html.HTML(source)[source]¶

Bases: object

css(css)[source]¶

xpath(xpath)[source]¶

capybara.pytest_plugin module¶

capybara.pytest_plugin.page()[source]¶

capybara.pytest_plugin.pytest_runtest_setup(item)[source]¶

capybara.pytest_plugin.pytest_runtest_teardown()[source]¶

capybara.result module¶

class capybara.result.Result(elements, query)[source]¶

Bases: object

A Result represents a collection of Element objects on the page. It is possible to interact with this collection similar to a List because it implements __getitem__ and offers the following container methods through delegation:

__len__
__nonzero__ (Python 2)

Parameters:	elements (List[Element]) – The initial list of elements found by the query. query (SelectorQuery) – The query used to find elements.

compare_count¶

Returns how the result count compares to the query options.

The return value is negative if too few results were found, zero if enough were found, and positive if too many were found.

Returns:	-1, 0, or 1.
Return type:	int

failure_message¶: str – A message describing the query failure.

matches_count¶: bool – Whether the result count matches the query options.

negative_failure_message¶

capybara.server module¶

class capybara.server.Middleware(app)[source]¶

Bases: object

has_pending_requests¶

identify(environ, start_response)[source]¶

class capybara.server.Server(app, port=None, host=None)[source]¶

Bases: object

Serves a WSGI-compliant app for Capybara to test.

Parameters:	app (object) – The WSGI-compliant app to serve. port (int, optional) – The port on which the server should be available. Defaults to `capybara.server_port`, or the last port used by the given app, or a random available port. host (str, optional) – The host on which the server should be available. Defaults to `capybara.server_host`.

boot()[source]¶

Boots a server for the app, if it isn’t already booted.

Returns:	This server.
Return type:	Server

error¶

has_pending_requests¶

middleware[source]¶

port_key¶

reset_error()[source]¶

responsive¶: bool – Whether the server for this app is up and responsive.

wait_for_pending_requests()[source]¶

capybara.session module¶

class capybara.session.Session(mode, app)[source]¶

Bases: capybara.session_matchers.SessionMatchersMixin, object

The Session class represents a single user’s interaction with the system. The Session can use any of the underlying drivers. A session can be initialized manually like this:

session = Session("selenium", MyWSGIApp)

The application given as the second argument is optional. When running Capybara against an external page, you might want to leave it out:

session = Session("selenium")
session.visit("http://www.google.com")

Session provides a number of methods and properties for controlling the navigation of the page, such as visit(), current_path, and so on. It also delegates a number of methods to a Document, representing the current HTML document. This allows interaction:

session.fill_in("q", value="Capybara")
session.click_button("Search")
assert session.has_text("Capybara")

When using capybara.dsl, the Session is initialized automatically for you.

Parameters:	mode (str) – The name of the driver to use. app (object) – The WSGI-compliant app with which to interact.

accept_alert(text=None, wait=None)[source]¶

Execute the wrapped code, accepting an alert.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

accept_confirm(text=None, wait=None)[source]¶

Execute the wrapped code, accepting a confirm.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

accept_prompt(text=None, response=None, wait=None)[source]¶

Execute the wrapped code, accepting a prompt, optionally responding to the prompt.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. response (str, optional) – Response to provide to the prompt. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

assert_all_of_selectors(selector, *locators, **kwargs)¶

Asserts that all of the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_all_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_all_of_selectors("css", "#my_dif", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so all of the locators must be present within wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

assert_no_selector(*args, **kwargs)¶

Asserts that a given selector is not on the page or a descendant of the current node. Usage is identical to assert_selector().

Query options such as count, minimum, and between are considered to be an integral part of the selector. This will return True, for example, if a page contains 4 anchors but the query expects 5:

page.assert_no_selector("a", minimum=1)  # Found, raises ExpectationNotMet
page.assert_no_selector("a", count=4)    # Found, raises ExpectationNotMet
page.assert_no_selector("a", count=5)    # Not Found, returns True

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – The given selector matched.

assert_no_text(*args, **kwargs)¶

Asserts that the page or current node doesn’t have the given text content, ignoring any HTML tags.

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

assert_no_title(title, **kwargs)¶

Asserts that the page doesn’t have the given title.

Parameters:	title (str \| RegexObject) – The string that the title should include. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

assert_none_of_selectors(selector, *locators, **kwargs)¶

Asserts that none of the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_none_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_none_of_selectors("css", "#my_div", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so none of the locators must be present with wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

assert_selector(*args, **kwargs)¶

Asserts that a given selector is on the page or a descendant of the current node.

page.assert_selector("p#foo")

By default it will check if the expression occurs at least once, but a different number can be specified.

page.assert_selector("p.foo", count=4)

This will check if the expression occurs exactly 4 times. See find_all() for other available result size options.

If a count of 0 is specified, it will behave like assert_no_selector(); however, use of that method is preferred over this one.

It also accepts all options that find_all() accepts, such as text and visible.

page.assert_selector("li", text="Horse", visible=True)

assert_selector can also accept XPath expressions generated by the xpath-py package:

from xpath import dsl as x

page.assert_selector("xpath", x.descendant("p"))

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – The given selector did not match.

assert_style(styles, **kwargs)¶

Asserts that an element has the specified CSS styles.

element.assert_style({"color": "rgb(0,0,255)", "font-size": re.compile(r"px")})

Parameters:	styles (Dict[str, str \| RegexObject]) – The expected styles.
Returns:	True
Raises:	`ExpectationNotMet` – The element doesn’t have the specified styles.

assert_text(*args, **kwargs)¶

Asserts that the page or current node has the given text content, ignoring any HTML tags.

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

assert_title(title, **kwargs)¶

Asserts that the page has the given title.

Parameters:	title (str \| RegexObject) – The string or regex that the title should match. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

attach_file(locator_or_path, path=None, **kwargs)¶

Find a file field on the page and attach a file given its path. The file field can be found via its name, id, or label text.

page.attach_file(locator, "/path/to/file.png")

Parameters:	locator_or_path (str) – Which field to attach the file to, or the path of the file that will be attached. path (str, optional) – The path of the file that will be attached. Defaults to `locator_or_path`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Raises:	`FileNotFound` – No file exists at the given path.

body¶: Alias for html.

check(locator=None, allow_label_click=None, **kwargs)¶

Find a check box and mark it as checked. The check box can be found via name, id, or label text.

page.check("German")

Parameters:	locator (str, optional) – Which check box to check. allow_label_click (bool, optional) – Attempt to click the label to toggle state if element is non-visible. Defaults to `capybara.automatic_label_click`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

choose(locator=None, allow_label_click=None, **kwargs)¶

Find a radio button and mark it as checked. The radio button can be found via name, id, or label text.

page.choose("Male")

Parameters:	locator (str, optional) – Which radio button to choose. allow_label_click (bool, optional) – Attempt to click the label to toggle state if element is non-visible. Defaults to `capybara.automatic_label_click`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

cleanup()¶: Alias for reset().

click_button(locator=None, **kwargs)¶

Finds a button on the page and clicks it. This can be any <input> element of type submit, reset, image, or button, or it can be any <button> element. All buttons can be found by their id, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute.

Parameters:	locator (str, optional) – Which button to find. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

click_link(locator=None, **kwargs)¶

Finds a link by id, text, or title and clicks it. Also looks at image alt text inside the link.

Parameters:	locator (str, optional) – Text, id, title, or nested image’s alt attribute. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

click_link_or_button(locator=None, **kwargs)¶

Finds a button or link by id, text or value and clicks it. Also looks at image alt text inside the link.

Parameters:	locator (str, optional) – Text, id, or value of link or button. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

click_on(locator=None, **kwargs)¶

Finds a button or link by id, text or value and clicks it. Also looks at image alt text inside the link.

Parameters:	locator (str, optional) – Text, id, or value of link or button. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

current_host¶: str – Host of the current page.

current_path¶: str – Path of the current page, without any domain information.

current_scope¶: node.Base – The current node relative to which all interaction will be scoped.

current_url¶: str – Fully qualified URL of the current page.

current_window¶: Window – The current window.

dismiss_confirm(text=None, wait=None)[source]¶

Execute the wrapped code, dismissing a confirm.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

dismiss_prompt(text=None, wait=None)[source]¶

Execute the wrapped code, dismissing a prompt.

Parameters:	text (str \| RegexObject, optional) – Text to match against the text in the modal. wait (int \| float, optional) – Maximum time to wait for the modal to appear after executing the wrapped code.
Raises:	`ModalNotFound` – If a modal dialog hasn’t been found.

document[source]¶: Document – The document for the current page.

driver[source]¶: driver.Base – The driver for the current session.

evaluate_async_script(script, *args)[source]¶

Evaluate the given JavaScript and obtain the result from a callback function which will be passed as the last argument to the script.

Parameters:	script (str) – A string of JavaScript to evaluate. *args – Variable length argument list to pass to the executed JavaScript string.
Returns:	The result of the evaluated JavaScript (may be driver specific).
Return type:	object

evaluate_script(script, *args)[source]¶

Evaluate the given JavaScript and return the result. Be careful when using this with scripts that return complex objects, such as jQuery statements. execute_script() might be a better alternative.

Parameters:	script (str) – A string of JavaScript to evaluate. *args – Variable length argument list to pass to the executed JavaScript string.
Returns:	The result of the evaluated JavaScript (may be driver specific).
Return type:	object

execute_script(script, *args)[source]¶

Execute the given script, not returning a result. This is useful for scripts that return complex objects, such as jQuery statements. execute_script should be used over evaluate_script() whenever possible.

Parameters:	script (str) – A string of JavaScript to execute. *args – Variable length argument list to pass to the executed JavaScript string.

fieldset(locator)[source]¶

Execute the wrapped code within a specific fieldset given the id or legend of that fieldset.

Parameters:	locator (str) – The id or legend of the fieldset.

fill_in(locator=None, current_value=None, value=None, fill_options=None, **kwargs)¶

Locate a text field or text area and fill it in with the given text. The field can be found via its name, id, or label text.

page.fill_in("Name", value="Bob")

Parameters:	locator (str, optional) – Which field to fill in. current_value (str, optional) – The current value of the field. value (str, optional) – The value to fill in. Defaults to None. fill_options (Dict, optional) – Driver-specific options regarding how to fill fields. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

find(*args, **kwargs)¶

Find an Element based on the given arguments. find will raise an error if the element is not found.

find takes the same options as find_all().

page.find("#foo").find(".bar")
page.find("xpath", "//div[contains(., 'bar')]")
page.find("li", text="Quox").click_link("Delete")

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element
Raises:	`Ambiguous` – If more than one element matching element is found. `ElementNotFound` – If the element can’t be found before time expires.

find_all(*args, **kwargs)¶

Find all elements on the page matching the given selector and options.

Both XPath and CSS expressions are supported, but Capybara does not try to automatically distinguish between them. The following statements are equivalent:

page.find_all("css", "a#person_123")
page.find_all("xpath", "//a[@id='person_123']")

If the type of selector is left out, Capybara uses capybara.default_selector. It’s set to "css" by default.

page.find_all("a#person_123")

capybara.default_selector = "xpath"
page.find_all("//a[@id='person_123']")

The set of found elements can further be restricted by specifying options. It’s possible to select elements by their text or visibility:

page.find_all("a", text="Home")
page.find_all("#menu li", visible=True)

By default if no elements are found, an empty list is returned; however, expectations can be set on the number of elements to be found which will trigger Capybara’s waiting behavior for the expectations to match. The expectations can be set using:

page.assert_selector("p#foo", count=4)
page.assert_selector("p#foo", maximum=10)
page.assert_selector("p#foo", minimum=1)
page.assert_selector("p#foo", between=range(1, 11))

See capybara.result.Result.matches_count() for additional information about count matching.

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	A collection of found elements.
Return type:	Result
Raises:	`ExpectationNotMet` – The matched results did not meet the expected criteria.

find_button(locator=None, **kwargs)¶

Find a button on the page. This can be any <input> element of type submit, reset, image, or button, or it can be a <button> element. All buttons can be found by their id, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute.

Parameters:	locator (str, optional) – The id, value, title, text content, alt of image. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

find_by_id(id, **kwargs)¶

Find an element on the page, given its id.

Parameters:	id (str) – The id of the element. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

find_field(locator=None, **kwargs)¶

Find a form field on the page. The field can be found by its name, id, or label text.

Parameters:	locator (str, optional) – Name, id, placeholder, or text of associated label element. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

find_first(*args, **kwargs)¶

Find the first element on the page matching the given selector and options, or None if no element matches.

By default, no waiting behavior occurs. However, if capybara.wait_on_first_by_default is set to true, it will trigger Capybara’s waiting behavior for a minimum of 1 matching element to be found.

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element or None.
Return type:	Element

find_link(locator=None, **kwargs)¶

Find a link on the page. The link can be found by its id or text.

Parameters:	locator (str, optional) – ID, title, text, or alt of enclosed img element. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	The found element.
Return type:	Element

frame(locator=None, *args, **kwargs)[source]¶

Execute the wrapped code within the given iframe using the given frame or frame name/id. May not be supported by all drivers.

Parameters:	locator (str \| Element, optional) – The name/id of the frame or the frame’s element. Defaults to the only frame in the document.

go_back()[source]¶: Move back a single entry in the browser’s history.

go_forward()[source]¶: Move forward a single entry in the browser’s history.

has_all_of_selectors(selector, *locators, **kwargs)¶

Checks if allof the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_all_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_all_of_selectors("css", "#my_dif", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so all of the locators must be present within wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

has_button(locator, **kwargs)¶

Checks if the page or current node has a button with the given text, value, or id.

Parameters:	locator (str) – The text, value, or id of a button to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_checked_field(locator, **kwargs)¶

Checks if the page or current node has a radio button or checkbox with the given label, value, or id, that is currently checked.

Parameters:	locator (str) – The label, name, or id of a checked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_content(*args, **kwargs)¶

Checks if the page or current node has the given text content, ignoring any HTML tags.

Whitespaces are normalized in both the node’s text and the passed text parameter. Note that whitespace isn’t normalized in a passed regular expression as normalizing whitespace in a regular expression isn’t easy and doesn’t seem to be worth it.

By default it will check if the text occurs at least once, but a different number can be specified.

page.has_text("lorem ipsum", between=range(2, 5))

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	Whether it exists.
Return type:	bool

has_css(path, **kwargs)¶

Checks if a given CSS selector is on the page or a descendant of the current node.

page.has_css("p#foo")

By default it will check if the selector occurs at least once, but a different number can be specified.

page.has_css("p#foo", count=4)

This will check if the selector occurs exactly 4 times.

It also accepts all options that find_all() accepts, such as text and visible.

page.has_css("li", text="Horse", visible=True)

Parameters:	path (str) – A CSS selector. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the selector exists.
Return type:	bool

has_field(locator, **kwargs)¶

Checks if the page or current node has a form field with the given label, name, or id.

For text fields and other textual fields, such as textareas and HTML5 email/url/etc. fields, it’s possible to specify a value argument to specify the text the field should contain:

page.has_field("Name", value="Jonas")

Parameters:	locator (str) – The label, name, or id of a field to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_link(locator, **kwargs)¶

Checks if the page or current node has a link with the given text or id.

Parameters:	locator (str) – The text or id of a link to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_no_button(locator, **kwargs)¶

Checks if the page or current node has no button with the given text, value, or id.

Parameters:	locator (str) – The text, value, or id of a button to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_checked_field(locator, **kwargs)¶

Checks if the page or current node has no radio button or checkbox with the given label, value, or id that is currently checked.

Parameters:	locator (str) – The label, name, or id of a checked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_css(path, **kwargs)¶

Checks if a given CSS selector is not on the page or a descendant of the current node. Usage is identical to has_css().

Parameters:	path (str) – A CSS Selector. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the selector does not exist.
Return type:	bool

has_no_field(locator, **kwargs)¶

Checks if the page or current node has no form field with the given label, name, or id. See has_field().

Parameters:	locator (str) – The label, name, or id of a field to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_link(locator, **kwargs)¶

Checks if the page or current node has no link with the given text or id.

Parameters:	locator (str) – The text or id of a link to check for. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_select(locator, **kwargs)¶

Checks if the page or current node has no select field with the given label, name, or id. See has_select().

Parameters:	locator (str) – The label, name, or id of a select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_selector(*args, **kwargs)¶

Checks if a given selector is not on the page or a descendant of the current node. Usage is identical to has_selector().

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_table(locator, **kwargs)¶

Checks if the page or current node has no table with the given id or caption. See has_table().

Parameters:	locator (str) – The id or caption of a table. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_text(*args, **kwargs)¶

Checks if the page or current node does not have the given text content, ignoring any HTML tags and normalizing whitespace.

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_title(title, **kwargs)¶

Checks if the page doesn’t have the given title.

Parameters:	title (str \| RegexObject) – The string that the title should include. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	Whether it doesn’t match.
Return type:	bool

has_no_unchecked_field(locator, **kwargs)¶

Checks if the page or current node has no radio button or checkbox with the given label, value, or id, that is currently unchecked.

Parameters:	locator (str) – The label, name, or id of an unchecked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it doesn’t exist.
Return type:	bool

has_no_xpath(path, **kwargs)¶

Checks if a given XPath expression is not on the page or a descendant of the current node. Usage is identical to has_xpath().

Parameters:	path (str) – An XPath expression. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the expression does not exist.
Return type:	bool

has_none_of_selectors(selector, *locators, **kwargs)¶

Checks if none of the provided selectors are present on the given page or descendants of the current node. If options are provided, the assertion will check that each locator is present with those options as well (other than wait).

page.assert_none_of_selectors("custom", "Tom", "Joe", visible="all")
page.assert_none_of_selectors("css", "#my_div", "a.not_clicked")

It accepts all options that find_all() accepts, such as text and visible.

The wait option applies to all of the selectors as a group, so none of the locators must be present with wait (defaults to capybara.default_max_wait_time) seconds.

If the given selector is not a valid selector, the first argument is assumed to be a locator and the default selector will be used.

Parameters:	selector (str, optional) – The name of the selector to use. Defaults to `capybara.default_selector`. locators (str) – Variable length list of locators. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.

has_select(locator, **kwargs)¶

Checks if the page or current node has a select field with the given label, name, or id.

It can be specified which option should currently be selected:

page.has_select("Language", selected="German")

For multiple select boxes, several options may be specified:

page.has_select("Language", selected=["English", "German"])

It’s also possible to check if the exact set of options exists for this select box:

page.has_select("Language", options=["English", "German", "Spanish"])

You can also check for a partial set of options:

page.has_select("Language", with_options=["English", "German"])

Parameters:	locator (str) – The label, name, or id of a select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_selector(*args, **kwargs)¶

Checks if a given selector is on the page or a descendant of the current node.

page.has_selector("p#foo")
page.has_selector("xpath", ".//p[@id='foo']")

By default it will check if the expression occurs at least once, but a different number can be specified.

page.has_selector("p.foo", count=4)

This will check if the expression occurs exactly 4 times.

It also accepts all options that find_all() accepts, such as text and visible.

page.has_selector("li", text="Horse", visible=True)

has_selector can also accept XPath expressions generated by the xpath-py package:

from xpath import dsl as x

page.has_selector("xpath", x.descendant("p"))

Parameters:	args – Variable length argument list for `SelectorQuery`. *kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the expression exists.
Return type:	bool

has_table(locator, **kwargs)¶

Checks if the page or current node has a table with the given id or caption:

page.has_table("People")

Parameters:	locator (str) – The id or caption of a table. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_text(*args, **kwargs)¶

Checks if the page or current node has the given text content, ignoring any HTML tags.

Whitespaces are normalized in both the node’s text and the passed text parameter. Note that whitespace isn’t normalized in a passed regular expression as normalizing whitespace in a regular expression isn’t easy and doesn’t seem to be worth it.

By default it will check if the text occurs at least once, but a different number can be specified.

page.has_text("lorem ipsum", between=range(2, 5))

Parameters:	args – Variable length argument list for `TextQuery`. *kwargs – Arbitrary keyword arguments for `TextQuery`.
Returns:	Whether it exists.
Return type:	bool

has_title(title, **kwargs)¶

Checks if the page has the given title.

Parameters:	title (str \| RegexObject) – The string or regex that the title should match. **kwargs – Arbitrary keyword arguments for `TitleQuery`.
Returns:	Whether it matches.
Return type:	bool

has_unchecked_field(locator, **kwargs)¶

Checks if the page or current node has a radio button or checkbox with the given label, value, or id, that is currently unchecked.

Parameters:	locator (str) – The label, name, or id of an unchecked field. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	Whether it exists.
Return type:	bool

has_xpath(query, **kwargs)¶

Checks if a given XPath expression is on the page or a descendant of the current node.

session.has_xpath(".//p[@id='foo']")

has_xpath can also accept XPath expressions generated by the xpath-py package:

from xpath import dsl as x

session.has_xpath(x.descendant("p"))

Parameters:	query (str) – An XPath expression. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.
Returns:	If the expression exists.
Return type:	bool

html¶: str – A snapshot of the DOM of the current document, as it looks right now.

open_new_window()[source]¶

Open new window. The current window doesn’t change as a result of this call. It should be switched explicitly.

Returns:	The window that has been opened.
Return type:	Window

raise_server_error()[source]¶: Raise errors encountered by the server.

refresh()[source]¶: Refresh the page.

reset()[source]¶

Reset the session (i.e., remove cookies and navigate to a blank page).

This method does not: * accept modal dialogs if they are present (the Selenium driver does, but others may not), * clear the browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc., or * modify the state of the driver/underlying browser in any other way

as doing so would result in performance downsides and it’s not needed to do everything from the list above for most apps.

If you want to do anything from the list above on a general basis you can write a test teardown method.

reset_session()¶: Alias for reset().

save_page(path=None)[source]¶

Save a snapshot of the page.

If invoked without arguments, it will save a file to capybara.save_path and the file will be given a randomly generated filename. If invoked with a relative path, the path will be relative to capybara.save_path.

Parameters:	path (str, optional) – The path to where it should be saved.
Returns:	The path to which the file was saved.
Return type:	str

save_screenshot(path=None, **kwargs)[source]¶

Save a screenshot of the page.

If invoked without arguments, it will save a file to capybara.save_path and the file will be given a randomly generated filename. If invoked with a relative path, the path will be relative to capybara.save_path.

Parameters:	path (str, optional) – The path to where it should be saved. **kwargs – Arbitrary keywords arguments for the driver.
Returns:	The path to which the file was saved.
Return type:	str

scope(*args, **kwargs)[source]¶

Executes the wrapped code within the context of a node. scope takes the same options as find(). For the duration of the context, any command to Capybara will be handled as though it were scoped to the given element.

with scope("xpath", "//div[@id='delivery-address']"):
    fill_in("Street", value="12 Main Street")

Just as with find(), if multiple elements match the selector given to scope, an error will be raised, and just as with find(), this behavior can be controlled through the match and exact options.

It is possible to omit the first argument, in that case, the selector is assumed to be of the type set in capybara.default_selector.

with scope("div#delivery-address"):
    fill_in("Street", value="12 Main Street")

Note that a lot of uses of scope can be replaced more succinctly with chaining:

find("div#delivery-address").fill_in("Street", value="12 Main Street")

Parameters:	args – Variable length argument list for the call to `find()`. *kwargs – Arbitrary keywords arguments for the call to `find()`.

select(value=None, field=None, **kwargs)¶

If the field argument is present, select finds a select box on the page and selects a particular option from it. Otherwise it finds an option inside the current scope and selects it. If the select box is a multiple select, select can be called multiple times to select more than one option. The select box can be found via its name, id, or label text. The option can be found by its text.

page.select("March", field="Month")

Parameters:	value (str, optional) – Which option to select. field (str, optional) – The id, name, or label of the select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

source¶: Alias for html.

switch_to_frame(frame)[source]¶

Switch to the given frame.

If you use this method you are responsible for making sure you switch back to the parent frame when done in the frame changed to. frame() is preferred over this method and should be used when possible. May not be supported by all drivers.

Parameters:	frame (Element \| str) – The iframe/frame element to switch to.

switch_to_window(window, wait=None)[source]¶

If window is a lambda, it switches to the first window for which window returns a value other than False or None. If a window that matches can’t be found, the window will be switched back and WindowError will be raised.

Parameters:	window (Window \| lambda) – The window that should be switched to, or a filtering lambda. wait (int \| float, optional) – The number of seconds to wait to find the window.
Returns:	The new current window.
Return type:	Window
Raises:	`ScopeError` – If this method is invoked inside scope, :meth:`frame(), or `window()`. `WindowError` – If no window matches the given lambda.

table(locator)[source]¶

Execute the wrapped code within a specific table given the id or caption of that table.

Parameters:	locator (str) – The id or caption of the table.

text¶: str – The text of the node.

title¶: str – The current page title.

uncheck(locator=None, allow_label_click=None, **kwargs)¶

Find a check box and uncheck it. The check box can be found via name, id, or label text.

page.uncheck("German")

Parameters:	locator (str, optional) – Which check box to uncheck. allow_label_click (bool, optional) – Attempt to click the label to toggle state if element is non-visible. Defaults to `capybara.automatic_label_click`. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

unselect(value=None, field=None, **kwargs)¶

Find a select box on the page and unselect a particular option from it. If the select box is a multiple select, unselect can be called multiple times to unselect more than one option. The select box can be found via its name, id, or label text.

page.unselect("March", field="Month")

Parameters:	value (str, optional) – Which option to unselect. field (str, optional) – The id, name, or label of the select box. **kwargs – Arbitrary keyword arguments for `SelectorQuery`.

visit(visit_uri)[source]¶

Navigate to the given URL. The URL can either be a relative URL or an absolute URL. The behavior of either depends on the driver.

session.visit("/foo")
session.visit("http://google.com")

For drivers which can run against an external application, such as the Selenium driver, giving an absolute URL will navigate to that page. This allows testing applications running on remote servers. For these drivers, setting capybara.app_host will make the remote server the default. For example:

capybara.app_host = "http://google.com"
session.visit("/")  # visits the Google homepage

Parameters:	visit_uri (str) – The URL to navigate to.

window(window)[source]¶

This method does the following:

Switches to the given window (it can be located by window instance/lambda/string).
Executes the given block (within window located at previous step).
Switches back (this step will be invoked even if exception happens at second step).

Parameters:	window (Window \| lambda) – The desired `Window`, or a lambda that will be run in the context of each open window and returns `True` for the desired window.

window_opened_by(trigger_func, wait=None)[source]¶

Get the window that has been opened by the passed lambda. It will wait for it to be opened (in the same way as other Capybara methods wait). It’s better to use this method than windows[-1] as order of windows isn’t defined in some drivers.

Parameters:	trigger_func (func) – The function that should trigger the opening of a new window. wait (int \| float, optional) – Maximum wait time. Defaults to `capybara.default_max_wait_time`.
Returns:	The window that has been opened within the lambda.
Return type:	Window
Raises:	`WindowError` – If lambda passed to window hasn’t opened window or opened more than one window.

windows¶

Get all opened windows. The order of the windows in the returned list is not defined. The driver may sort windows by their creation time but it’s not required.

Returns:	A list of all windows.
Return type:	List[Window]

capybara.session_matchers module¶

class capybara.session_matchers.SessionMatchersMixin[source]¶

Bases: object

assert_current_path(path, **kwargs)[source]¶

Asserts that the page has the given path. By default this will compare against the path+query portion of the full URL.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

assert_no_current_path(path, **kwargs)[source]¶

Asserts that the page doesn’t have the given path.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	True
Raises:	`ExpectationNotMet` – If the assertion hasn’t succeeded during the wait time.

has_current_path(path, **kwargs)[source]¶

Checks if the page has the given path.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	Whether it matches.
Return type:	bool

has_no_current_path(path, **kwargs)[source]¶

Checks if the page doesn’t have the given path.

Parameters:	path (str \| RegexObject) – The string or regex that the current “path” should match. **kwargs – Arbitrary keyword arguments for `CurrentPathQuery`.
Returns:	Whether it doesn’t match.
Return type:	bool

capybara.utils module¶

class capybara.utils.Counter[source]¶

Bases: object

Keeps track of a running count.

value¶: int – The current value of the counter.

class capybara.utils.cached_property(func)[source]¶

Bases: property

Decorates an instance method, turning it into a property whose value is cached.

capybara.utils.decode_bytes(value)[source]¶: str: Decodes the given byte sequence.

capybara.utils.encode_string(value)[source]¶: bytes: Encodes the given string.

capybara.utils.find_available_port()[source]¶: int: A random available port.

capybara.utils.inner_content(node)[source]¶

Returns the inner content of a given XML node, including tags.

Parameters:	node (lxml.etree.Element) – The node whose inner content is desired.
Returns:	The inner content of the node.
Return type:	str

capybara.utils.inner_text(node)[source]¶

Returns the inner text of a given XML node, excluding tags.

Parameters:	node – (lxml.etree.Element): The node whose inner text is desired.
Returns:	The inner text of the node.
Return type:	str

capybara.utils.isbytes(value)[source]¶: bool: Whether the given value is a sequence of bytes.

capybara.utils.isregex(possible_regex)[source]¶

Returns whether the given object is (probably) a regular expression object.

Parameters:	possible_regex (object) – An object which may or may not be a regular expression.
Returns:	Whether the given object is (probably) a regular expression object.
Return type:	bool

capybara.utils.isstring(value)[source]¶: bool: Whether the given value is a string.

capybara.utils.normalize_url(url)[source]¶

Returns the given URL with all query keys properly escaped.

Parameters:	url (str) – The URL to normalize.
Returns:	The normalized URL.
Return type:	str

capybara.utils.setter_decorator(fset)[source]¶

Define a write-only property that, in addition to the given setter function, also provides a setter decorator defined as the property’s getter function.

This allows one to set the property either through traditional assignment, as a method argument, or through decoration:

class Widget(object):
    @setter_decorator
    def handler(self, value):
        self._handler = value

widget = Widget()

# Method 1: Traditional assignment
widget.handler = lambda input: process(input)

# Method 2: Assignment via method argument
widget.handler(lambda input: process(input))

# Method 3: Assignment via decoration
@widget.handler
def handler(input):
    return process(input)

# Method 3b: Assignment via decoration with extraneous parens
@widget.handler()
def handler(input):
    return process(input)

capybara.version module¶

capybara.window module¶

class capybara.window.Window(session, handle)[source]¶

Bases: object

The Window class represents a browser window.

You can get an instance of the class by calling either of:

windows
current_window
window_opened_by()
switch_to_window()

Note that some drivers (e.g. Selenium) support getting size of/resizing/closing only current window. So if you invoke such method for:

window that is current, Capybara will make 2 Selenium method invocations (get handle of current window + get size/resize/close).
window that is not current, Capybara will make 4 Selenium method invocations (get handle of current window + switch to given handle + get size/resize/close + switch to original handle)

Parameters:	session (Session) – Session that this window belongs to. handle (object) – An object that uniquely identifies the window within the session.

close()[source]¶

Close window.

If this method was called for the window that is current, then after calling this method future invocations of other Capybara methods should raise session.driver.no_such_window_error until another window is switched to.

If this method was called for a window that is not current, then after calling this method the current window should remain the same as it was before calling this method.

closed¶: bool – Whether the window is closed.

current¶: bool – Whether this window is the window in which commands are being executed.

exists¶: bool – Whether the window is not closed.

fullscreen()[source]¶: Fullscreen the window.

maximize()[source]¶

Maximize the window.

If this method was called for a window that is not current, then after calling this method the current window should remain the same as it was before calling this method.

resize_to(width, height)[source]¶

Resizes the window to the given dimensions.

If this method was called for a window that is not current, then after calling this method the current window should remain the same as it was before calling this method.

Parameters:	width (int) – The new window width in pixels. height (int) – The new window height in pixels.

size¶: List[int, int] – The window size.

Module contents¶

capybara.app = None¶: object – The WSGI-compliant app to test.

capybara.app_host = None¶: str – The default host to use when giving a relative URL to visit. Must be a valid URL.

capybara.automatic_label_click = False¶: bool – Whether checkbox/radio actions will try to click the label of invisible elements.

capybara.automatic_reload = True¶: bool – Whether to automatically reload elements as Capybara is waiting.

capybara.current_driver = None¶: str – The name of the driver currently in use.

capybara.current_session()[source]¶

Returns the Session for the current driver and app, instantiating one if needed.

Returns:	The `Session` for the current driver and app.
Return type:	Session

capybara.default_driver = 'werkzeug'¶: str – The name of the driver default driver to use.

capybara.default_max_wait_time = 2¶: int – The maximum number of seconds to wait for asynchronous processes to finish.

capybara.default_selector = 'css'¶: str – The name of the default selector used to find elements.

capybara.enable_aria_label = False¶: bool – Whether fields, links, and buttons will match against aria-label attributes.

capybara.exact = False¶: bool – Whether to match the exact label name/contents.

capybara.ignore_hidden_elements = True¶: bool – Whether to ignore hidden elements on the page.

capybara.javascript_driver = 'selenium'¶: str – The name of the driver to use when JavaScript is required.

capybara.match = 'smart'¶: str – The matching strategy to use.

capybara.raise_server_errors = True¶: bool – Whether errors raised in the server should be raised in the tests.

capybara.register_driver(name)[source]¶

Register a driver initialization function.

Parameters:	name (str) – The name of the driver.
Returns:	A decorator that takes a function that initializes a driver for the given WSGI-compliant app.
Return type:	Callable[[Callable[[object], object], None]

capybara.register_server(name)[source]¶

Register a server initialization function.

Parameters:	name (str) – The name of the server.
Returns:	A decorator that takes a function that initializes a server for the given WSGI-compliant app, host, and port.
Return type:	Callable[[Callable[[object, str, int], None]], None]

capybara.reset()¶: Alias for reset_sessions().

capybara.reset_sessions()[source]¶: Resets all sessions.

capybara.run_default_server(app, port)[source]¶

capybara.save_path = None¶: str, optional – Where to put saved pages and screenshots.

capybara.server_host = '127.0.0.1'¶: str – The IP address bound by the default server.

capybara.server_name = 'default'¶: str – The name of the server to use to serve the app.

capybara.server_port = None¶: int, optional – The port bound by the default server.

capybara.session_name = 'default'¶: str – The current session name.

capybara.string(html)[source]¶

Wraps the given string, which should contain an HTML document or fragment in a Simple which exposes MatchersMixin, FindersMixin, and DocumentMatchersMixin. This allows you to query any string containing HTML in the exact same way you would query the current document in a Capybara session.

Example: A single element

node = Capybara.string("""<a href="foo">bar</a>""")
anchor = node.find_first("a")
anchor["href"]  # => "foo"
anchor.text  # => "bar"

Example: Multiple elements

node = Capybara.string("""
  <ul>
    <li id="home">Home</li>
    <li id="projects">Projects</li>
  </ul>
""")

node.find("#projects").text  # => "Projects"
node.has_selector("li#home", text="Home")
node.has_selector("#projects")
node.find("ul").find("li:first-child").text  # => "Home"

Parameters:	html (str \| lxml.etree.Element) – An HTML fragment or document.
Returns:	A node which has Capybara’s finders and matchers.
Return type:	Simple

capybara.use_default_driver()[source]¶: Use the default driver as the current driver.

capybara.using_driver(driver)[source]¶

Execute the wrapped code using a specific driver.

Parameters:	driver (str) – The name of the desired driver.

capybara.using_session(name)[source]¶

Execute the wrapped code using a specific session name.

Parameters:	name (str) – The name of the session to use.

capybara.using_wait_time(seconds)[source]¶

Execute a context using a specific wait time.

Parameters:	seconds (int \| float) – The new wait time.

capybara.visible_text_only = False¶: bool – Whether to only consider visible text.

capybara.wait_on_first_by_default = False¶: bool – Whether find_first() should wait for at least one element to appear.

capybara package¶

Subpackages¶

Submodules¶

capybara.compat module¶

capybara.dsl module¶

capybara.exceptions module¶

capybara.helpers module¶

capybara.html module¶

capybara.pytest_plugin module¶

capybara.result module¶

capybara.server module¶

capybara.session module¶

capybara.session_matchers module¶

capybara.utils module¶

capybara.version module¶

capybara.window module¶

Module contents¶

Capybara

Navigation

Related Topics