com.codeborne.selenide.SelenideElement [src]

The SelenideElement class is a wrapper over Selenium WebElement that adds some rather useful methods.

The object returned by the $ command is called a "proxy-element". At the moment of creation of proxy-element the real search of element on the page is not initiated. But on any subsequent action or condition check - the actual replica of the page element will be acquired by the "proxy-element", and the corresponding action or condition check will be "proxied" to it.

Firstly, this allows to use Selenide to automate testing of modern dynamic web application that dynamically change the state of page elements.

Secondly, you can build the objects modeling your pages with such proxy-elements according to the PageObject pattern. It is possible to store the "proxy-element" into the PageObject field before loading the corresponding page in the browser exactly because the "proxy-element" will not start its search at the moment of creation.

//before opening a browser and loading a page url
class HomePage {
  private SelenideElement menu = $("#menu");

  public void openStream() {
      this.menu.find(byLinkText("Stream")).click();
  }

  public void openProfile() {
      this.menu.find(byLinkText("Profile")).click();
  }
}
HomePage home = new HomePage();
//now the $ command was executed and the SelenideElement object was created, but the browser has not been opened yet
//...
open("/home"); //the browser has been opened and the page has been loaded
home.openProfile(); // exactly here the search was initiated and the actual replica of the page menu element was got, then its inner stream element was found and the click command was "proxied" to it.
//...something else might happen
home.openStream(); //and now, before finding the element-link with the "Profile" text to click on it - again, the actual version of the menu element was found on the page.
//...

Methods of the following types are defined for the SelenideElement:

• inner elements search methods

  • more precisely: the methods for creating proxy-elements that represents corresponding inner elements

• methods to check element state - assertions

• methods-actions on element

• methods to get element statuses and attribute values

• others

All these methods has some built-in features for their convenient usage. The majority of them has built-in implicit waits. This allows to work with dynamically loading elements without additional efforts spent for configuring more complicated explicit waits.

Inner elements search methods

• find(String cssSelector) | $(String cssSelector)

• find(By) | $(By)

• findAll(String cssSelector) | $$(String cssSelector)

• findAll(By) | $$(By)

Here $ and $$ are just more concise "aliases" of find and findAll methods correspondingly.

All these methods return "proxy-elements", i.e. they do not start the search of actual elements on the page until you call some action like .click().

Thus, you can specify the search path step by step, building the "locators chain":

$("#header").find("#menu").findAll(".item")

Herewith, you can save the "search chain" of any length to the variable, regardless of the fact whether a page is loaded or not at the moment of defining the variable:

//before opening browser and loading a page
SelenideElement menu = $("#menu");
SelenideElement streamMenu = menu.$(By.linkText("Stream"));
SelenideElement profileMenu = menu.$(By.linkText("Profile"));
//...
open("/main");  // loading the page (in automatically opened browser)
profileMenu.click();
//...
streamMenu.click();
//...

Methods to check element state - assertions

Assertion methods - trigger the search of actual element on a page for the proxy-element, performs the check based on condition (an object the Condition class), and return back the object of SelenideElement (i.e. proxy-element) again allowing to build chains of further methods calls.

• should(Condition) | shouldBe(Condition) | shouldHave(Condition)

• shouldNot(Condition) | shouldNotBe(Condition) | shouldNotHave(Condition)

We recommend to choose the convenient alias so the line of code can be easily read like a common english phrase, for example:

$("input").should(exist);  
$("input").shouldBe(visible);
$("input").shouldHave(exactText("Some text"));

Assertions play role of explicit waits in Selenide. They wait for condition (visible, enabled, text("some text")) to be satisfied until timeout reached (the value of Configuration.timeout that is set to 4000 ms by default).

You can use "should-methods" explicitly in order to wait the needed state of element before corresponding action, for example:

$("#submit").shouldBe(enabled).click();

There are also versions of "Selenide explicit waits" with ability to set timeout explicitly:

• waitUntil(Condition, milliseconds)

• waitWhile(Condition, milliseconds)

Methods-actions on element

Element actions methods:

• click()

• doubleClick()

• contextClick()

• hover()

• setValue(String) | val(String)

• pressEnter()

• pressEscape()

• pressTab()

• selectRadio(String value)

• selectOption(String)

• append(String)

• dragAndDropTo(String)

• ...

trigger the search for proxy-elements and perform corresponding action.

Actions have built-in implicit waits for visibility of element until a timeout is reached (the value of Configuration.timeout property that is set to 4000 ms by default).

Thus the code $("#submit").shouldBe(visible).click() is redundant. The following code - $("#submit").click() - will effectively do the same.

The majority of actions returns the object of SelenideElement (the same proxy-element) allowing to build concise method chains:

$("#edit").setValue("text").pressEnter();

Methods to get element statuses and attribute values

Trigger the search for proxy-elements and have different logic of implicit waiting:

• The following methods implicitly wait for availability in DOM (i.e. method may be hidden on the page, but should be still available in Document Object Model):

  • getValue() | val()

  • data()

  • attr(String)

  • text() // returns "visible text on a page"

  • innerText() // returns "text of element in DOM"

  • getSelectedOption()

  • getSelectedText()

  • getSelectedValue()

• The following methods do not wait:

  • isDisplayed() //returns false, if element is hidden (invisible) or if element does not exist in DOM; otherwise - true

  • exists() //returns true, if element exists in DOM, otherwise - false

Other useful methods

• uploadFromClasspath(String fileName)

• download()

• toWebElement()

• uploadFile(File...)