Playwrightium

Intro

Playwrightium is the implementation of Webdriver interface with Playwright Java inside.
This combination allows us to run Selenide tests with Playwright without rewriting the code.

The story

I like Java. I like Selenium. I like Selenide. But also I like Playwright Java. But I want to use all (or almost all) features of Playwright and continue using Selenide syntax.

What should I do? I developed Playwrightium.

How to install

Maven

Add to your pom.xml

Add dependency

<dependency>
    <groupId>io.github.britka</groupId>
    <artifactId>playwrightium</artifactId>
    <version>LAST_VERSION</version>
</dependency>

Gradle

implementation 'io.github.britka:playwrightium:LAST_VERSION'

This dependency encapsulates

• Selenide
• Playwright Java

How to use as regular webdriver

You can use it like a regular Webdriver For example:

WebDriver driver = new PlaywrightiumDriver();
driver.get("https://example.com");
driver.findElement(By.name("username")).sendKeys("Some value");
driver.findElement(By.cssSelector("input[value=submit][name=submitbutton]")).click();

If you need more example please refer to the playwrightium tests

Note

For the first time Playwright will install browsers images:

• chromium
• firefox
• webkit (Safari)

After installation your test will run.

Note

If you want to skip browsers download you should set up this using PlaywrightiumOptions and tell Playwrightium to use local browser

Example:

PlaywrightiumOptions playwrightiumOptions = new PlaywrightiumOptions();
playwrightiumOptions.setSkipDownloadBrowsers(true);
playwrightiumOptions.setBrowserName(Browsers.CHROME_CHANNEL);
PlaywrightiumDriver playwrightiumDriver = new PlaywrightiumDriver(playwrightiumOptions);

What Playwrightium can do

Navigate to url

driver.get("https://examle.com");

Search for element and element collections by different locators:

* By.xpath
* By.cssSelector
* By.id
* By.name
* By.linkText
* By.partialLinkText
* By.className
* By.tagName

For example:

WebElement xpathElement = driver.findElement(By.xpath("//label[text()='Some text']"));
WebElement cssElement = driver.findElement(By.xpath("//label[text()='Some text']"));

List<WebElement> elementList = driver.findElements(By.name("any name"));

Also you can use Playwright locators See documentation

For this use PlaywrightiumBy class:

• PlaywrightiumBy.byRole
• PlaywrightiumBy.byAltTextbyLabel
• PlaywrightiumBy.byPlaceholder
• PlaywrightiumBy.byTestId
• PlaywrightiumBy.byText
• PlaywrightiumBy.byTitle

For example:

import org.openqa.selenium.WebElement;

WebElement submitButton = driver.findElement(PlaywrightiumBy.byRole(AriaRole.BUTTON, AriaRoleOptions.builder().setName("submit").build()));
WebElement driver.findElement(PlaywrightiumBy.byLabel("LabeText", true));

Work with WebElements

For example

var name = element.getAttribute("name");
element.click();
element.isDisplayed();
element.getText();

Important

Method sendKeys works quickly amd smooth. But Selenide method setValue can work slowly. This method makes many things. So if it is possible use sendKey from Playwrightium

Switch to frame

driver.switchTo().frame("frameName");

Works with Select webelement

ISelect select = new PlaywrightiumSelect(driver.findElement(By.name("dropdown"))); 
select.selectByValue("dd"+faker.number().numberBetween(1,7));
String selectValue = select.getFirstSelectedOption().getAttribute("value");

• Use waiters

 new WebDriverWait(driver, Duration.ofSeconds(10)).
    until(ExpectedConditions.visibilityOfElementLocated(By.xpath("//h1[contains(.,'Processed Form Details')]")));

Use alerts

Note

To use alerts you should know how it works in Playwright

So the example will be

// At first describe what we want to do with alert
Alert alert = driver.switchTo().alert();
alert.sendKeys(testString);
alert.accept();

// After we do some actions that will lead to alert appearance.
driver.findElement(By.id("promptexample")).click();

// After we can make some checks
assertThat(alert.getText()).isEqualTo("I prompt you");

Use Actions class

new Actions(driver).moveToElement(driver.findElement(By.id("someId"))).build().perform();

Important

Some functionality is on WIP. So I cannot guarantee that all will work fine

Run JavaScript scripts

((JavascriptExecutor)driver).executeScript("return alert();");

Record video

Initialize Playwrightium driver using PlaywrightiumOptions class

PlaywrightiumOptions playwrightiumOptions = new PlaywrightiumOptions();
playwrightiumOptions.setRecordVideo(true);

driver =new PlaywrightiumDriver(playwrightiumOptions);

Important

This will create folder 'builds/video' in the root of your project

or to initialize records folder

PlaywrightiumOptions playwrightiumOptions = new PlaywrightiumOptions();
playwrightiumOptions.setRecordVideo(true);
playwrightiumOptions.setRecordsFolder(Path.of("videosFolder"));
driver =new PlaywrightiumDriver(playwrightiumOptions);

Important

This will create folder 'videosFolder' in the root of your project

Important

If you initialize driver in BeforeAll(or similar) section it will record all tests as 1 video file To record video of separate tests you should initialize browser before each test.

Important

This method will work everywhere: locally, in Selenoid, Selenium Grid, Aerokube Moon

How this feature works.

For chromium based browsers Playwright is trying to use CDP protocol to screencast browser context and collect screenshots and after that it uses ffmpeg to create video from images.

• See CDP protocol. Page.
  • Page.startScreencast
  • Page.stopScreencast
  • Page.screencastFrameAck
  • Page.screencastFrame
• See ffmpeg
  • ffmpeg FAQ about image2pipe approach

Run remotely.

Using Selenoid or Selenium Grid

Important

This will work with Chromium-based browsers (Chromium, Chrome, MS Edge, Opera etc.)

Initialize Playwrightium driver using PlaywrightiumOptions class

PlaywrightiumOptions playwrightiumOptions = new PlaywrightiumOptions();
playwrightiumOptions.setConnectionByWS(false);
playwrightiumOptions.setHeadless(true);
return new PlaywrightiumDriver("http://localhost:4444/wd/hub",chromeOptions);

Important

chromeOptions.setConnectionByWS(false); is telling us that we will use http connections as we do in regular connection to Selenoid or Selenium Grid.

Using Aerokube Moon

Important

Works for all browsers.

Initialize Playwrightium driver using PlaywrightiumOptions class

PlaywrightiumOptions playwrightiumOptions = new PlaywrightiumOptions();
playwrightiumOptions.setConnectionByWS(true);
playwrightiumOptions.setHeadless(true);
return new PlaywrightiumDriver("http://localhost:4444/wd/hub",playwrightiumOptions);

Important

chromeOptions.setConnectionByWS(true); is telling us that we will use ws connections as we do in regular connection to Aerokube Moon.

How to use it with Selenide

To use it with Selenide you should implement WebDriverProvider interface. For example:

public class PWDriverProvider implements WebDriverProvider {
    @Nonnull
    @Override
    public WebDriver createDriver(@Nonnull Capabilities capabilities) {
        PlaywrightWebdriverOptions playwrightiumOptions = new PlaywrightWebdriverOptions();
        playwrightiumOptions.merge(capabilities);
        return new PlaywrightiumDriver(playwrightiumOptions);
    }
}

Then you should use it with Configuration E.g.

Configuration.browser = PWDriverProvider.class.getName();

Playwrightium options

Option name	Type	Description
headless	boolean	Run tests in "headless" node or not
browserName	string or Browsers	What browser to run. Available values: chromium, firefox, webkit
recordVideo	boolean	Indicates will the video be recorded or not
recordsFolder	string	The folder where video recordings will be saved. Default {project.basedir}/build/video
connectionByWS	boolean	Indicates how we will run tests remotely. If we will use Selenoid/Selenium grid then we should choose false (works for chrome only), if we will use Moon then we should choose true
emulation	Device	Emulates the device
locale	Locale	Emulates locale
timeZone	TimeZone	Emulates timezone
geolocation	Geolocation	Emulates geolocation
permissions	List<Permissions>	Switch on permissions
enableTracing	boolean	Enables tracing for test run
tracingOptions	TracingOptions	Sets tracing options when tracing options are enabled
skipDownloadBrowsers	boolean	Skips downloads of predefined Playwright browsers

Important

For now all this options might be set only by PlaywrightiumOptions

Tracing

When tests were run using enableTracing option by default tracing.zip file should be created in {projectRootDirectory}/tracing/ directory.
To run tracing viewer you can use:

• viewTracing.bat or viewTracing.sh scripts depends on you OS.

viewTracing.sh path/to/your/tracing.zip

• run in commandline

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="show-trace path\to\your\trace.zip"

• or use Online trace viewer

Important

Be careful!!! This may decrease the speed of test running

And that's all. You can easily use it with Selenide. See test for Selenide

Enjoy!