Webdriver++

A C++ client library for Selenium Webdriver. You can use this library in any C++ project.

Only 4.x and more Selenium Server.

COPYRIGHTS

• 2018 - Current Herman Semenov ([email protected])
• 2014 - 2018 Sergey Kogan ([email protected])
• 2017 Ilya Durdyev (IDurdyev)

SPECIAL THANKS

• 2019 xingyun86 ([email protected])
• 2020 xloem ([email protected])
• 2021 SrMilton ([email protected]), Mecanik ([email protected])
• 2022 Mecanik ([email protected]), No-47 ([email protected])

Cloning repository

git clone --recurse-submodules https://github.com/GermanAizek/webdriverxx.git
cd webdriverxx

Compilation requirements

Debian

sudo apt-get install cmake g++ make curl

Ubuntu and Ubuntu Touch

sudo apt-get install cmake g++ make curl libcurl4-openssl-dev

Arch Linux

sudo pacman -Syu cmake g++ make curl

Gentoo

sudo emerge -av dev-util/cmake sys-devel/gcc sys-devel/make net-misc/curl

Compile on Linux, FreeBSD, OpenBSD

mkdir build && cd build && cmake ../src
sudo make

Compile on Windows

mkdir build
cd build
cmake ../src
# For example, open a solution in Visual Studio

Install GeckoDriver or ChromeDriver on Linux

GeckoDriver

To work with GeckoDriver, you need any browser built on the Gecko engine.

Firefox (ESR, Nightly), IceCat, Waterfox, Pale Moon, SeaMonkey and etc.

In our examples, we will install official stable Firefox.

Debian, Ubuntu, Ubuntu Touch

sudo apt-get install geckodriver

Arch Linux

sudo pacman -Syu geckodriver

Gentoo

USE="geckodriver" sudo emerge -av www-client/firefox

ChromeDriver

To work with chromedriver, you need any browser built on the Chromium engine.

Chromium, Google Chrome, Opera, Vivaldi and etc.

In our examples, we will install official stable Google Chrome.

Debian, Ubuntu, Ubuntu Touch

sudo apt-get install chromium-driver

Arch Linux

sudo yay -S --aur aur/chromedriver

Gentoo

sudo emerge -av www-client/chromedriver-bin

A quick example

Dependencies

The first thing you need is full runtime environment Java.

You need to download and run selenium-server-standalone.

Windows

Download latest OpenJDK and unpack: https://openjdk.java.net/

Official Selenium server can be seen here: https://selenium-release.storage.googleapis.com/index.html

Set the path enviroment variable to OpenJDK or move to the OpenJDK folder

java -jar /path_to/selenium-server-4.0.0-beta-4.jar standalone

Linux

Download latest OpenJDK from packet manager distributions Linux.

Debian, Ubuntu, Ubuntu Touch

sudo apt-get install default-jre

Arch Linux

sudo pacman -Syu jre-openjdk jre-openjdk-headless

Gentoo

sudo emerge -av virtual/jre

Official Selenium server can be seen here: https://selenium-release.storage.googleapis.com/index.html

wget https://selenium-release.storage.googleapis.com/4.0-beta-4/selenium-server-4.0.0-beta-4.jar

or download from AUR here:

sudo yay -S --aur aur/selenium-server-standalone

After now you can start.

Any Linux distribution

java -jar selenium-server-4.0.0-beta-4.jar standalone

If Selenium server standalone was downloaded from AUR (Arch Linux), then:

java -jar /usr/share/selenium-server/selenium-server-standalone.jar

Run Google Test for testing html pages

On Windows:

cd src/vcprojects/
# Open a solution 'webdriverxx.sln' in Visual Studio and compile it

More info in MSDN: Build and run a C++ app project

Examples

Build CMakeLists in 'examples' folder and run binary.

On Linux:

cd examples/example_start_browsers
mkdir build && cd build
cmake ..
make
./example_start_browsers

Features

• Very lightweight framework (When compared with all implementations of api selenium)
• Chainable commands
• Value-like objects compatible with STL containers
• Header-only
• Lightweight dependencies:
  • libcurl
  • picojson
• Can be used with any testing framework
• Linux, FreeBSD, OpenBSD, Mac and Windows
• Tested on GCC 9.x, Clang 10.x and MSVC Visual Studio 2019

More examples

All examples are in 'examples' folder.

Use proxy

WebDriver ie = Start(InternetExplorer().SetProxy(
	SocksProxy("127.0.0.1:3128")
		.SetUsername("user")
		.SetPassword("12345")
		.SetNoProxyFor("custom.host")
	));

WebDriver ff = Start(Firefox().SetProxy(DirectConnection()));

Navigate browser

driver
	.Navigate("http://facebook.com")
	.Navigate("http://twitter.com")
	.Back()
	.Forward()
	.Refresh();

Find elements

// Throws exception if no match is found in the document
Element menu = driver.FindElement(ById("menu"));

// Returns empty vector if no such elements
// The search is performed inside the menu element
std::vector<Element> items = menu.FindElements(ByClass("item"));

Send keyboard input

// Sends text input or a shortcut to the element
driver.FindElement(ByTag("input")).SendKeys("Hello, world!");

// Sends text input or a shortcut to the active window
driver.SendKeys(Shortcut() << keys::Control << "t");

Emulate mobile devices (only Chrome)

chrome::MobileEmulation me;
me.SetdeviceName(chrome::device::Get("Galaxy Note 3"));
WebDriver ff = Start(Chrome().SetMobileEmulation(me));

Execute Javascript

// Simple script, no parameters
driver.Execute("console.log('Hi there!')");

// A script with one parameter
driver.Execute("document.title = arguments[0]", JsArgs() << "Cowabunga!");

// A script with more than one parameter
driver.Execute("document.title = arguments[0] + '-' + arguments[1]",
		JsArgs() << "Beep" << "beep");

// Arrays or containers can also be used as parameters
const char* ss[] = { "Yabba", "dabba", "doo" };
driver.Execute("document.title = arguments[0].join(', ')", JsArgs() << ss);

// Even an Element can be passed to a script
auto element = driver.FindElement(ByTag("input"));
driver.Execute("arguments[0].value = 'That was nuts!'", JsArgs() << element);

Get something from Javascript

// Scalar types
auto title = driver.Eval<std::string>("return document.title")
auto number = driver.Eval<int>("return 123");
auto another_number = driver.Eval<double>("return 123.5");
auto flag = driver.Eval<bool>("return true");

// Containers (all std::back_inserter compatible)
std::vector<std::string> v = driver.Eval<std::vector<std::string>>(
		"return [ 'abc', 'def' ]"
		);

// Elements!
Element document_element = driver.Eval<Element>("return document.documentElement");

Wait implicitly for asynchronous operations

driver.SetImplicitTimeoutMs(5000);

// Should poll the DOM for 5 seconds before throwing an exception.
auto element = driver.FindElement(ByName("async_element"));

Wait explicitly for asynchronous operations

#include <webdriverxx/wait.h>

auto find_element = [&]{ return driver.FindElement(ById("async_element")); };
Element element = WaitForValue(find_element);

#include <webdriverxx/wait.h>

auto element_is_selected = [&]{
	return driver.FindElement(ById("asynchronously_loaded_element")).IsSelected();
	};
WaitUntil(element_is_selected);

Use matchers from Google Mock for waiting

#define WEBDRIVERXX_ENABLE_GMOCK_MATCHERS
#include <webdriverxx/wait_match.h>

driver.Navigate("http://initial_url.host.net");
auto url = [&]{ return driver.GetUrl(); };
using namespace ::testing;
auto final_url = WaitForMatch(url, HasSubstr("some_magic"));

Testing with real browsers

Prerequisites:

• Selenium Server (4.x and more)

Linux

java -jar selenium-server.jar standalone &
./webdriverxx --browser=<firefox|chrome|...>

Windows

java -jar selenium-server.jar standalone
webdriverxx.exe --browser=<firefox|chrome|...>

Advanced topics

Unicode

The library is designed to be encoding-agnostic. It doesn't make any assumptions about encodings. All strings are transferred as is, without modifications.

The WebDriver protocol is based on UTF-8, so all strings passed to the library/received from the library should be/are encoded using UTF-8.

Thread safety

• Webdriver++ objects are not thread safe. It is not safe to use neither any single object nor different objects obtained from a single WebDriver concurrently without synchronization. On the other side, Webdriver++ objects don't use global variables so it is OK to use different instances of WebDriver in different threads.

• The CURL library should be explicitly initialized if several WebDrivers are used from multiple threads. Call curl_global_init(CURL_GLOBAL_ALL); from <curl/curl.h> once per process before using this library.

Use common capabilities for all browsers

Capabilities common;
common.SetProxy(DirectConnection());
auto ff = Start(Firefox(common));
auto ie = Start(InternetExplorer(common));
auto gc = Start(Chrome(common));

Use required capabilities

Capabilities required = /* ... */;
auto ff = Start(Firefox(), required);

Use custom URL for connecting to WebDriver

const char* url = "http://localhost:4444/wd/hub/";

auto ff = Start(Firefox(), url);

// or
auto ff = Start(Firefox(), Capabilities() /* required */, url);

Transfer objects between C++ and Javascript

namespace custom {

struct Object {
	std::string string;
	int number;
};

// Conversion functions should be in the same namespace as the object
picojson::value CustomToJson(const Object& value) {
	return JsonObject()
		.Set("string", value.string)
		.Set("number", value.number);
}

void CustomFromJson(const picojson::value& value, Object& result) {
	assert(value.is<picojson::object>());
	result.string = FromJson<std::string>(value.get("string"));
	result.number = FromJson<int>(value.get("number"));
}

} // namespace custom

custom::Object o1 = { "abc", 123 };
driver.Execute("var o1 = arguments[0];", JsArgs() << o1);
custom::Object o1_copy = driver.Eval<custom::Object>("return o1");
custom::Object o2 = driver.Eval<custom::Object>("return { string: 'abc', number: 123 }");

---