capybara.node package

Submodules

capybara.node.actions module

class capybara.node.actions.ActionsMixin[source]

Bases: object

If the driver is capable of executing JavaScript, actions will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time find() will wait is controlled through capybara.default_max_wait_time.

attach_file(locator_or_path, path=None, **kwargs)[source]

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.
check(locator=None, allow_label_click=None, **kwargs)[source]

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)[source]

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.
click_button(locator=None, **kwargs)[source]

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.

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.

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)

Alias for click_link_or_button().

fill_in(locator=None, current_value=None, value=None, fill_options=None, **kwargs)[source]

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.
select(value=None, field=None, **kwargs)[source]

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.
uncheck(locator=None, allow_label_click=None, **kwargs)[source]

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)[source]

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.node.base module

class capybara.node.base.Base(session, base)[source]

Bases: capybara.node.finders.FindersMixin, capybara.node.actions.ActionsMixin, capybara.node.matchers.MatchersMixin, object

A Base represents either an element on a page through the subclass Element or a document through Document.

Both types of Node share the same methods, used for interacting with the elements on the page. These methods are divided into three categories: finders, actions, and matchers. These are found in the classes FindersMixin, ActionsMixin, and MatchersMixin respectively.

A Session exposes all methods from Document directly:

session = Session("selenium", my_app)
session.visit("/")
session.fill_in("Foo", value="Bar")  # from capybara.node.actions.ActionsMixin
bar = session.find("#bar")           # from capybara.node.finders.FindersMixin
bar.select("Baz", field="Quox")      # from capybara.node.actions.ActionsMixin
session.has_css("#foobar")           # from capybara.node.matchers.MatchersMixin
Parameters:
  • session (Session) – The session from which this node originated.
  • base (driver.Node) – The underlying driver node.
all_text

str – All of the text of the node.

reload()[source]

Reloads the underlying driver node.

Returns:This node.
Return type:node.Base
synchronize(func=None, wait=None, errors=())[source]

This method is Capybara’s primary defense against asynchronicity problems. It works by attempting to run a given decorated function until it succeeds. The exact behavior of this method depends on a number of factors. Basically there are certain exceptions which, when raised from the decorated function, instead of bubbling up, are caught, and the function is re-run.

Certain drivers have no support for asynchronous processes. These drivers run the function, and any error raised bubbles up immediately. This allows faster turn around in the case where an expectation fails.

Only exceptions that are ElementNotFound or any subclass thereof cause the block to be rerun. Drivers may specify additional exceptions which also cause reruns. This usually occurs when a node is manipulated which no longer exists on the page. For example, the Selenium driver specifies selenium.common.exceptions.StateElementReferenceException.

As long as any of these exceptions are thrown, the function is re-run, until a certain amount of time passes. The amount of time defaults to capybara.default_max_wait_time and can be overridden through the wait argument. This time is compared with the system time to see how much time has passed. If the return value of time.time() is stubbed out, Capybara will raise FrozenInTime.

Parameters:
  • func (Callable, optional) – The function to decorate.
  • wait (int, optional) – Number of seconds to retry this function.
  • errors (Tuple[Type[Exception]], optional) – Exception types that cause the function to be rerun. Defaults to driver.invalid_element_errors + ElementNotFound.
Returns:

The decorated function, or a decorator function.
Return type:

Callable
Raises:

FrozenInTime – If the return value of time.time() appears stuck.
text

str – The text of the node.

visible_text

str – Only the visible text of the node.

capybara.node.base.synchronize(func)[source]

Decorator for synchronize().

capybara.node.document module

class capybara.node.document.Document(session, base)[source]

Bases: capybara.node.document_matchers.DocumentMatchersMixin, capybara.node.base.Base

A Document represents an HTML document. Any operation performed on it will be performed on the entire document.

all_text

str – All of the text of the document.

text

str – The text of the document.

title

str – The current page title.

visible_text

str – Only the visible text of the document.

capybara.node.document_matchers module

class capybara.node.document_matchers.DocumentMatchersMixin[source]

Bases: object

assert_no_title(title, **kwargs)[source]

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_title(title, **kwargs)[source]

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.
has_no_title(title, **kwargs)[source]

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_title(title, **kwargs)[source]

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.node.element module

class capybara.node.element.Element(session, base, query_scope, query)[source]

Bases: capybara.node.base.Base

An Element represents a single element on the page. It is possible to interact with the contents of this element the same as with a document:

session = Session("selenium", my_app)

bar = session.find("#bar")       # from capybara.node.finders.FindersMixin
bar.select("Baz", field="Quox")  # from capybara.node.actions.ActionsMixin

Element also has access to HTML attributes and other properties of the element:

bar.value
bar.text
bar["title"]
all_text

str – All of the text of the element.

checked

bool – Whether or not the element is checked.

click(*keys, **offset)[source]

Click the element.

Both x and y must be specified if an offset is wanted. If not specified, the click will occur at the middle of the element.

Parameters:
  • keys (List[Keys], optional) – Keys to be held down when clicking.
  • offset (Dict[str, int], optional) – X- and Y-coordinates to offset the click location from the toop left corner of the element.
disabled

bool – Whether or not the element is disabled.

double_click(*keys, **offset)[source]

Double-click the element.

Both x and y must be specified if an offset is wanted. If not specified, the click will occur at the middle of the element.

Parameters:
  • keys (List[Keys], optional) – Keys to be held down when clicking.
  • offset (Dict[str, int], optional) – X- and Y-coordinates to offset the click location from the toop left corner of the element.
drag_to(node)[source]

Drag the element to the given other element.

source = page.find("#foo")
target = page.find("#bar")
source.drag_to(target)
Parameters:node (Element) – The element to drag to.
evaluate_async_script(script, *args)[source]
evaluate_script(script, *args)[source]
execute_script(script, *args)[source]
hover()[source]

Hover on the element.

multiple

bool – Whether or not the element supports multiple results.

native

object – The native element from the driver.

path

str – An XPath expression describing where on the page the element can be found.

readonly

bool – Whether or not the element is readonly.

reload()[source]

Reloads the underlying driver node.

Returns:This node.
Return type:node.Base
right_click(*keys, **offset)[source]

Right-click the element.

Both x and y must be specified if an offset is wanted. If not specified, the click will occur at the middle of the element.

Parameters:
  • keys (List[Keys], optional) – Keys to be held down when clicking.
  • offset (Dict[str, int], optional) – X- and Y-coordinates to offset the click location from the toop left corner of the element.
select_option()[source]

Select this node if it is an option element inside a select tag.

selected

bool – Whether or not the element is selected.

send_keys(*args)[source]

Send keystrokes to the element.

Examples:

from selenium.webdriver.common.keys import Keys

element.send_keys("foo")                  # => value: "foo"
element.send_keys("tet", Keys.LEFT, "s")  # => value: "test"
Parameters:*args – Variable length list of keys to send.
set(value, **options)[source]

Set the value of the form element to the given value.

Parameters:
  • value (bool | str) – The new value.
  • **options – Driver-specific options for how to set the value.
style(*styles)[source]

Retrieve the given CSS styles.

element.style("color", "font-size")  # => Computed values of CSS "color" and "font-size" styles
Parameters:*styles (str) – Names of the desired CSS properties.
Returns:Dictionary of the CSS property names to computed values.
Return type:Dict[str, str]
tag_name

str – The tag name of the element.

text

Retrieve the text of the element. If capybara.ignore_hidden_elements is True, which it is by default, then this will return only text which is visible. The exact semantics of this may differ between drivers, but generally any text within elements with display: none is ignored.

Returns:The text of the element.
Return type:str
unselect_option()[source]

Unselect this node if it is an option element inside a multiple select tag.

value

str – The value of the form element.

visible

bool – Whether or not the element is visible.

visible_text

str – Only the visible text of the element.

capybara.node.finders module

class capybara.node.finders.FindersMixin[source]

Bases: object

If the driver is capable of executing JavaScript, finders will wait for a set amount of time and continuously retry finding the element until either the element is found or the time expires. The length of time find() will wait is controlled through capybara.default_max_wait_time and defaults to 2 seconds.

ancestor(*args, **kwargs)[source]

Find an Element based on the given arguments that is also an ancestor of the element called on. ancestor will raise an error if the element is not found.

ancestor takes the same options as find().

element.ancestor("#foo").find(".bar")
element.ancestor("xpath", "//div[contains(., 'bar')]")
element.ancestor("li", text="Quox").click_link("Delete")
Parameters:
  • *args – Variable length argument list for AncestorQuery.
  • **kwargs – Arbitrary keyword arguments for AncestorQuery.
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(*args, **kwargs)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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 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
sibling(*args, **kwargs)[source]

Find an Element based on the given arguments that is also a sibling of the element called on. sibling will raise an error if the element is not found.

sibling takes the same options as find().

element.sibling("#foo").find(".bar")
element.sibling("xpath", "//div[contains(., 'bar')]")
element.sibling("li", text="Quox").click_link("Delete")
Parameters:
  • *args – Variable length argument list for SiblingQuery.
  • **kwargs – Arbitrary keyword arguments for SiblingQuery.
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.node.matchers module

class capybara.node.matchers.MatchersMixin[source]

Bases: object

assert_all_of_selectors(selector, *locators, **kwargs)[source]

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_matches_selector(*args, **kwargs)[source]

Asserts that the current node matches a given selector.

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

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

node.assert_matches_selector("li", text="Horse", visible=True)
Parameters:
  • *args – Variable length argument list for SelectorQuery.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

True
Raises:

ExpectationNotMet – If the selector does not match.
assert_no_selector(*args, **kwargs)[source]

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)[source]

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_none_of_selectors(selector, *locators, **kwargs)[source]

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_not_match_selector(*args, **kwargs)[source]

Asserts that the current node does not match a given selector. See assert_matches_selector().

Parameters:
  • *args – Variable length argument list for SelectorQuery.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

True
Raises:

ExpectationNotMet – If the selector matches.
assert_selector(*args, **kwargs)[source]

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)[source]

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)[source]

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.
has_all_of_selectors(selector, *locators, **kwargs)[source]

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)[source]

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)[source]

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)

Alias for has_text().

has_css(path, **kwargs)[source]

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)[source]

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

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)[source]

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)[source]

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_content(*args, **kwargs)

Alias for has_no_text().

has_no_css(path, **kwargs)[source]

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)[source]

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

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)[source]

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)[source]

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)[source]

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)[source]

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_unchecked_field(locator, **kwargs)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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_style(styles, **kwargs)[source]

Checks if an element has the specified CSS styles.

element.has_style({"color": "rgb(0,0,255)", "font-size": re.compile(r"px")})
Parameters:styles (Dict[str, str | RegexObject]) – The expected styles.
Returns:Whether the styles match.
Return type:bool
has_table(locator, **kwargs)[source]

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)[source]

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_unchecked_field(locator, **kwargs)[source]

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)[source]

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
matches_css(css, **kwargs)[source]

Checks if the current node matches the given CSS selector.

Parameters:
  • css (str) – The CSS selector to match against the current node.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

Whether it matches.
Return type:

bool
matches_selector(*args, **kwargs)[source]

Checks if the current node matches the given selector.

Parameters:
  • *args – Variable length argument list for SelectorQuery.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

Whether it matches.
Return type:

bool
matches_xpath(xpath, **kwargs)[source]

Checks if the current node matches the given XPath expression.

Parameters:
  • xpath (str | xpath.expression.Expression) – The XPath expression to match against the current node.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

Whether it matches.
Return type:

bool
not_match_css(css, **kwargs)[source]

Checks if the current node does not match the given CSS selector.

Parameters:
  • css (str) – The CSS selector to match against the current node.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

Whether it doesn’t match.
Return type:

bool
not_match_selector(*args, **kwargs)[source]

Checks if the current node does not match the given selector. 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 match.
Return type:

bool
not_match_xpath(xpath, **kwargs)[source]

Checks if the current node does not match the given XPath expression.

Parameters:
  • xpath (str | xpath.expression.Expression) – The XPath expression to match against the current node.
  • **kwargs – Arbitrary keyword arguments for SelectorQuery.
Returns:

Whether it doesn’t match.
Return type:

bool
refute_matches_selector(*args, **kwargs)

Alias for assert_not_match_selector().

refute_selector(*args, **kwargs)

Alias for assert_no_selector().

capybara.node.simple module

class capybara.node.simple.Simple(native)[source]

Bases: capybara.node.finders.FindersMixin, capybara.node.matchers.MatchersMixin, capybara.node.document_matchers.DocumentMatchersMixin, object

A Simple is a simpler version of Base which includes only FindersMixin and MatchersMixin and does not include ActionsMixin. This type of node is returned when using capybara.string().

It is useful in that it does not require a session, an application, or a driver, but can still use Capybara’s finders and matchers on any string that contains HTML.

allow_reload
checked

bool – Whether or not the element is checked.

disabled

bool – Whether or not the element is disabled.

multiple

bool – Whether or not the select supports multiple values.

path

str – An XPath expression describing where on the page the element can be found.

readonly

bool – Whether or not the element is readonly.

selected

bool – Whether or not the element is selected.

synchronize(func=None, **kwargs)[source]
tag_name

str – The tag name of the element.

text

str – The text of the element.

title

str – The current page title.

value

str – The value of the form element.

visible

bool – Whether or not the element is visible.

Module contents