Documentation

Selenide 4.4.1 released

Blog

Documentation

Poor software doesn't have documentation. Brilliant software doesn't need documentation.

We are proud to claim that Selenide is so simple that you don't need to read tons of documentation.
The whole work with Selenide consists of three simple things!

Three simple things:

1. Open the page
2. $(element).doAction()
3. $(element).check(condition)

  open("/login");
  $("#submit").click();
  $(".message").shouldHave(text("Hello"));

Use the power of IDE

Selenide API consists of few classes. We suggest you to stop reading, open your IDE and start typing.

Just type: $(selector). - and IDE will suggest you all available options.

Selenide API: Just start typing

Use the power of todays development environments instead of bothering with documentation!


Selenide API

Here is a full Selenide javadoc.

Just for reference, these are Selenide classes you will probably need for work:

com.codeborne.selenide.Selenide [src] [javadoc]

The core of the library. Main methods are open, $ and $$ (import static com.codeborne.selenide.Selenide.* for readability):

  • open(String URL) opens the browser (if yet not opened) and loads the URL
  • $(String cssSelector) – returns object of the SelenideElement class that represents first element found by CSS selector on the page.
  • $(By) – returns "first SelenideElement" by the locator of the By class.
  • $$(String cssSelector) – returns object of type ElementsCollection that represents collection of all elements found by a CSS selector.
  • $$(By) – returns "collection of elements" by the locator of By type.

Usually, when you get a SelenideElement object by the Dollar $ command, you can perform some action on it:

  • $(byText("Sign in")).click();

or even several actions at once:

  • $(byName("password")).setValue("qwerty").pressEnter();

or you can check some condition:

  • $(".welcome-message").shouldHave(text("Welcome, user!")).

The “Double Dollar” command ($$) can be useful when a needed element is a one of a same type. For example, instead of:

$(byXpath("//*[@id='search-results']//a[contains(text(),'selenide.org')]")).click();

you can use more readable and verbose alternative:

$$("#search-results a").findBy(text("selenide.org")).click();

The majority of operations on elements, acquired by the $ and $$ commands, have built-in implicit waits depending on a context. This allows in most cases to be not distracted by handling explicitly the waiting for loading of elements while automating testing of dynamic web applications.

Don’t be shy to search for more methods inside the Selenide class that can suit your needs. Just type in your IDE Selenide. and choose the needed option among available IDE proposals.

Here are just a few examples:

sleep(), refresh() and title(), executeJavaScript(String jsCode, Object… arguments).

Look for more details in Selenide gitbook.

com.codeborne.selenide.SelenideElement [src] [javadoc]

The SelenideElement class describes an element found on the page. The object of this class can be acquired e.g. by the $ command. The following useful methods are defined in the class.

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.

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

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

Methods to check element state - assertions

  • 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

  • click()
  • doubleClick()
  • contextClick()
  • hover()
  • setValue(String) / val(String)
  • pressEnter()
  • pressEscape()
  • pressTab()
  • selectRadio(String value)
  • selectOption(String)
  • append(String)
  • dragAndDropTo(String)

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

  • getValue() / val()
  • data()
  • attr(String)
  • text() // returns “visible text on a page”
  • innerText() // returns “text of element in DOM”
  • getSelectedOption()
  • getSelectedText()
  • getSelectedValue()
  • 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…)

Look for more details in Selenide gitbook

com.codeborne.selenide.Condition [src] [javadoc]

Conditions are used in should / shouldNot / waitUntil / waitWhile constructs. We recommend to import corresponding conditions statically to receive all the advantages of readable code:

  • visible / appear // e.g. $(“input”).shouldBe(visible)
  • present / exist // // conditions to wait for element existence in DOM (it can be still hidden)
  • hidden / disappear // not(visible)
  • readonly // e.g. $(“input”).shouldBe(readonly)
  • name // e.g. $(“input”).shouldHave(name(“fname”))
  • value // e.g. $(“input”).shouldHave(value(“John”))
  • type // e.g. $(“#input”).shouldHave(type(“checkbox”))
  • id // e.g. $(“#input”).shouldHave(id(“myForm”))
  • empty // e.g. $(“h2”).shouldBe(empty)
  • attribute(name) // e.g. $(“#input”).shouldHave(attribute(“required”))
  • attribute(name, value) // e.g. $(“#list li”).shouldHave(attribute(“class”, “active checked”))
  • cssClass(String) // e.g. $(“#list li”).shouldHave(cssClass(“checked”))
  • focused
  • enabled
  • disabled
  • selected
  • matchText(String regex)
  • text(String substring)
  • exactText(String wholeText)
  • textCaseSensitive(String substring)
  • exactTextCaseSensitive(String wholeText)

Look for more details in Selenide gitbook

com.codeborne.selenide.Selectors [src] [javadoc]

The class contains some By selectors to locate elements by text or attributes (that may be missed in standard Selenium WebDriver API):

// Examples:
$(byText("Login")).shouldBe(visible));
$(By.xpath("//div[text()='Login']")).shouldBe(visible);  // any org.openqa.selenium.By.* selector can be used
$(byXpath("//div[text()='Login']")).shouldBe(visible);  // or any its alternative from Selectors class 

Look for more details in Selenide gitbook

com.codeborne.selenide.ElementsCollection [src] [javadoc]

This is the class that describes a collection of elements on the page, found by the locator. Usually the object of the ElementsCollection class can be acquired by the $$ method. The class contains rather useful methods.

Assertions

  • shouldBe - e.g. $$(".errors").shouldBe(empty)
  • shouldHave - e.g. $$("#mytable tbody tr").shouldHave(size(2))

Assertions also play role of explicit waits. They wait for condition (e.g. size(2), empty, texts("a", "b", "c")) to be satisfied until timeout reached (the value of Configuration.collectionsTimeout that is set to 6000 ms by default).

Methods to get statues and attributes of elements collection

  • size()
  • isEmpty()
  • getTexts() // returns the array of visible elements collection texts, e.g. for elements: <li>a</li><li hidden>b</li><li>c</li> will return the array ["a", "", "c"]

Methods-selectors of specific collection elements

  • filterBy(Condition) – returns collection (as ElementsCollection) with only those original collection elements that satisfies the condition, e.g. $$("#multirowTable tr").filterBy(text("Norris"))
  • excludeWith(Condition) – e.g. $$("#multirowTable tr").excludeWith(text("Chuck"))
  • get(int) - returns nth element (as SelenideElement);
  • findBy(Condition) - returns the first collection element (as SelenideElement) that satisfied the condition.

Look for more details in Selenide gitbook

com.codeborne.selenide.CollectionCondition [src] [javadoc]

Collection conditions are used in the shouldBe/shouldHave constructs for the object of ElementsCollection class. It is recommended to import needed conditions statically in order to achive all advantages of the readable code.

  • empty // e.g. $$("#list li").shouldBe(empty)
  • size(int) // e.g. $$("#list li").shouldHave(size(10))
  • sizeGreaterThan(int)
  • sizeGreaterThanOrEqual(int)
  • sizeLessThan(int)
  • sizeLessThanOrEqual(int)
  • sizeNotEqual(int)
  • texts(String... substrings)
  • exactTexts(String... wholeTexts)

Look for more details in Selenide gitbook

com.codeborne.selenide.WebDriverRunner [src] [javadoc]

This class defines some browser management methods:

  • isChrome()
  • isFirefox()
  • isHeadless()
  • url() - returns current URL
  • source() - returns source HTML code of current page
  • getWebDriver() - returns the WebDriver instance (created by Selenide automatically or set up by the user), thus giving to the user the raw API to Selenium if needed
  • setWebDriver(WebDriver) - tells Selenide to use driver created by the user. From this moment the user himself is responsible for closing the driver (e.g. by calling getWebDriver().quit()).

Look for more details in Selenide gitbook

com.codeborne.selenide.Configuration [src] [javadoc]

This class contains different configuration options to configure execution of Selenide-based tests, e.g.:

  • timeout - waiting timeout in milliseconds, that is used in explicit (should/shouldNot/waitUntil/waitWhile) and implicit waiting for SelenideElement; set to 4000 ms by default; can be changed for specific tests, e.g. Configuration.timeout = 6000;
  • collectionsTimeout - waiting timeout in milliseconds, that is used in explicit (should/shouldNot/waitUntil/waitWhile) and implicit waiting for ElementsCollection; set to 6000 ms by default; can be changed for specific tests, e.g. Configuration.collectionsTimeout = 8000;
  • browser (e.g. "chrome", "ie", "firefox")
  • baseUrl
  • reportsFolder

Additionally, it is possible to pass configuration options as system properties e.g. when configuration tests execution on CI servers (continuous integration), e.g. -Dselenide.baseUrl=http://staging-server.com/start

Look for more details in Selenide gitbook

Stay tuned!



blog comments powered by Disqus

The project is maintained by