# thirtyfour

[![Crates.io](https://img.shields.io/crates/v/thirtyfour.svg)](https://crates.io/crates/thirtyfour)
[![docs.rs](https://docs.rs/thirtyfour/badge.svg)](https://docs.rs/thirtyfour)
[![Build Status](https://img.shields.io/github/actions/workflow/status/stevepryde/thirtyfour/test.yml?branch=main)](https://github.com/stevepryde/thirtyfour/actions)
[![codecov](https://codecov.io/gh/stevepryde/thirtyfour/branch/main/graph/badge.svg?token=OVORQE9PZK)](https://codecov.io/gh/stevepryde/thirtyfour)

Thirtyfour is a Selenium / WebDriver library for Rust, for automated website UI testing.

It supports the [W3C WebDriver v1 spec](https://www.w3.org/TR/webdriver1/). Tested with Chrome and Firefox although any W3C-compatible WebDriver should work.

## Why is it called "thirtyfour" ?

34 is the atomic number for the Selenium chemical element (Se) ⚛️.

## Getting Started

Check out [The Book](https://stevepryde.github.io/thirtyfour/) 📚!

## Features

- All W3C WebDriver and WebElement methods supported
- Create new browser session directly via WebDriver (e.g. chromedriver)
- Create new browser session via Selenium Standalone or Grid
- Find elements (via all common selectors e.g. Id, Class, CSS, Tag, XPath)
- Send keys to elements, including key-combinations
- Execute Javascript
- Action Chains
- Get and set cookies
- Switch to frame/window/element/alert
- Shadow DOM support
- Alert support
- Capture / Save screenshot of browser or individual element as PNG
- Chrome DevTools Protocol (CDP) support (limited)
- Advanced query interface including explicit waits and various predicates
- Component Wrappers (similar to `Page Object Model`)

## Feature Flags

- `rustls-tls`: (Default) Use rustls to provide TLS support (via reqwest).
- `native-tls`: Use native TLS (via reqwest).
- `component`: (Default) Enable the `Component` derive macro (via thirtyfour_macros).

## Examples

The examples assume you have `chromedriver` running on your system.

You can use Selenium (see instructions below) or you can use chromedriver 
directly by downloading the chromedriver that matches your Chrome version,
from here: [https://chromedriver.chromium.org/downloads](https://chromedriver.chromium.org/downloads)

Then run it like this:

    chromedriver

### Example (async):

To run this example:

    cargo run --example tokio_async

```rust
use thirtyfour::prelude::*;

#[tokio::main]
async fn main() -> WebDriverResult<()> {
     let caps = DesiredCapabilities::chrome();
     let driver = WebDriver::new("http://localhost:9515", caps).await?;

     // Navigate to https://wikipedia.org.
     driver.goto("https://wikipedia.org").await?;
     let elem_form = driver.find(By::Id("search-form")).await?;

     // Find element from element.
     let elem_text = elem_form.find(By::Id("searchInput")).await?;

     // Type in the search terms.
     elem_text.send_keys("selenium").await?;

     // Click the search button.
     let elem_button = elem_form.find(By::Css("button[type='submit']")).await?;
     elem_button.click().await?;

     // Look for header to implicitly wait for the page to load.
     driver.find(By::ClassName("firstHeading")).await?;
     assert_eq!(driver.title().await?, "Selenium - Wikipedia");
    
     // Always explicitly close the browser.
     driver.quit().await?;

     Ok(())
}
```

## Compared to Fantoccini

The [fantoccini](https://github.com/jonhoo/fantoccini) crate offers a more lightweight 
browser automation experience and (so far) seems to stick closer to the WebDriver specification.

Thirtyfour aims to provide a more "batteries-included" automated testing experience,
with more advanced element queries and Page Object Model support.

Support for newer specs like [Selenium 4.x](https://www.selenium.dev/), 
[Chrome DevTools Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/), 
[WebDriver V2](https://www.w3.org/TR/webdriver2/) and 
[WebDriver BIDI](https://w3c.github.io/webdriver-bidi/) are planned.

## Compared to tools like Cypress, Playwright, etc.

Most browser automation tools other than Selenium tend to be (very polished) wrappers around 
Chrome DevTools Protocol and as such they actually only provide a subset of the 
functionality that Selenium can provide. This is often not a significant limitation, however.
It really depends on what you want to achieve, and which framework you prefer to work with.

Thirtyfour aims to provide a Selenium-based experience on par with any other tool.
There's still a long way to go. If you'd like to contribute, please get in touch!

## Minimum Supported Rust Version

The MSRV for `thirtyfour` is currently 1.66 and will be updated as needed by dependencies.

## LICENSE

This work is dual-licensed under MIT or Apache 2.0.
You can choose either license if you use this work.

See the NOTICE file for more details.

`SPDX-License-Identifier: MIT OR Apache-2.0`
