Skip to content

Latest commit

 

History

History
649 lines (556 loc) · 35.4 KB

README.md

File metadata and controls

649 lines (556 loc) · 35.4 KB
Raw

Info

drawing Selenium WebDriver Elementor Toolkit ( SWET = light , in Russian) is a OS-independent successor to the Selenium WebDriver Page Recorder (SWD) by Dmytro Zharii and author. SWET is using Eclipse Standard Widget Toolkit with third party Opal widget library' for user interface (instead of Microsoft .Net Windows Forms) and the Jtwig template engine instead of ASP.Net Razor for code generation. NOTE: the Jtwig template engine project is no longer maintained,the source is still available for cloning at Jtwig Project github repository That is just one of the available template exngines - note, jtwig supports the original PHP Twig syntax as well.

SWET also allows generating the keyword driven framework flow and saving it into an Excel spreadsheet. This is a work in progress, since each keyword driven framework has its own list of keywords , currenlty SWET supports the SKDF framework developed by the author.

SWET was tested to work on 32 or 64 bit Windows, Mac or Linux platforms. SWET is currently beta quality: one can record, load and save sessions, update individual Page Element information, convert session to a code fragment in Java or C# language, or an Excel file with a Keyword Driven Framework workflow. The SWET project was originally written to offer similar functionality as SWD, but significantly less MVC-heavyy and also breaking its dependency on Windows Forms libraries, after an attempt to replace Windows Forms with XWT was made failed with conclysion that XWT look and feel of the time, did not seem equivalent. Eventually the full functionality of SWD is to be achieved, also SWET might become an Eclipse plugin.

The SWET application is being developed in Ecipse with SWT Designer/Window Builder plugin, on Ubuntu 16.04 and Windows. The javaFx port os SWET is in the works.

For Mac / Safari testing, the Sierra Final 10.12 Virtual Box by TechReviews is being used. Naturally, Apple only licenses OS X for use on their hardware, therefore the fact the author has been using able to boot Sierra and test the code to successfully compile and run does not imply he officialy asks anyone do the same, it simply proves the code being robust enough and very likely will run on a real Mac out of gitgub. Currently, recording page elements in SWET with Safari browser is somewhat flaky but possible.

The Virtualbox images are setup for Selenium 3.x testing (work in progress).

OSX Example

Ubuntu Example

Windows Example

Usage

In order to use SWET one will need to compile the application jar from the source - it is not difficult. Continue reading for info on how to get the dev environment setup.

Prerequisites

The project can be compiled and run from Eclipse or standalone, through the launcher script. The single executable jar is not being packages by default due to its size - anyone is free to try on one's own risk.

To build the project outside of Eclipse, JDK 1.8 or later and Maven need to be installed and added to the PATH. There launcher scripts is explained below.

As the time goes on, the following reusable parts of the SWET project became stanalone ones and have been eitherpublished to maven central or need to be cloned and installed locally using maven:

To skip smoke testing of those projects use the command

mvn -Dmaven.test.skip=true install

to have them available in ~/.m2/repositories. Eventually all of these prjects would go to maven central.

In the checked-in sample runner scripts, the JDK and Maven is expected to be installed under c:\java\ on Windows, or into the path /Library/Java/JavaVirtualMachines/jdk$JAVA_VERSION.jdk/Contents/Home(which is the default location) on the Mac, and made available on Linux with alternatives.

All project dependencies are pulled by Maven.

Updating the platform-specific information in the pom.xml

There are profiles in the project pom.xml which make selection of the platform-specific swt.jar dependency automatic:

    <profile>
      <id>windows64</id>
      <activation>
        <os>
          <family>dos</family>
          <arch>amd64</arch>
        </os>
      </activation>
      <properties>
        <eclipse.swt.artifactId>org.eclipse.swt.win32.win32.x86_64</eclipse.swt.artifactId>
        <build_os>win64</build_os>
      </properties>
    </profile>
    <profile>
      <id>mac64</id>
      <activation>
        <os>
          <family>mac</family>
          <arch>x86_64</arch>
        </os>
      </activation>
      <properties>
        <build_os>mac64</build_os>
        <eclipse.swt.artifactId>org.eclipse.swt.cocoa.macosx.x86_64</eclipse.swt.artifactId>
      </properties>
    </profile>
    <profile>
      <id>unix32</id>
      <activation>
        <os>
          <family>unix</family>
          <arch>i386</arch>
        </os>
      </activation>
      <properties>
        <build_os>unix32</build_os>
        <selenium.version>2.53.1</selenium.version>
        <eclipse.swt.artifactId>org.eclipse.swt.gtk.linux.x86</eclipse.swt.artifactId>
      </properties>
    </profile>
    <profile>
      <id>unix64</id>
      <activation>
        <os>
          <family>unix</family>
          <arch>amd64</arch>
        </os>
      </activation>
      <properties>
        <build_os>unix64</build_os>
        <eclipse.swt.artifactId>org.eclipse.swt.gtk.linux.x86_64</eclipse.swt.artifactId>
      </properties>
    </profile>

The correct profile is likely be selected automatically. If this does not work for some reason, one will need to copy the relevant artifactId property definition into the

  <properties>
    <eclipse.swt.version>4.3</eclipse.swt.version>
    <eclipse.swt.artifactId>org.eclipse.swt.win32.win32.x86_64</eclipse.swt.artifactId>
  </properties>
  <dependencies>
    <dependency>
			<groupId>org.eclipse.swt</groupId>
			<artifactId>${eclipse.swt.artifactId}</artifactId>
      <version>${eclipse.swt.version}</version>
		</dependency>
    ...

Due to some problem with JVM loader, all these platform-dependent jars cannot be included simultaneously. One alternative is to package the spring-boot style uber-jar file as explained in Multiplatform SWT project. Unfortulately it is not very practical: the resulting bare-bones multiplatform-swt-loader.jar file is almost 10 Mb and with all Selenium JSON POI and TWIG dependencies the size of SWET jar exceeds 30 Mb. The conversion to javaFx is currently underway. Therefore, we recommend to rely on maven profile facility to pick the required dependency and to modify the pom.xml and use runner scripts to compile it as explained below.

Runner Scripts

After the project is cloned or downloaded from from github, one will find the following run.* scripts helpful to compile and start the application: On Windows, use either Powershell script

. .\run.ps1

or a batch file

run.cmd

On Unix or a Mac, launcher is a bash script

./run.sh

Debugging and adding Features

The SWET application is a Gimp style multi dialog desktop app. Practically every class (SWT or console) in the project directory can be started standalone with the help of the launcher script(s) run.cmd, run.ps1 in Windows OS and run.sh in OSX or Linux os like e.g.:

run.cmd ComplexFormEx

compiles the app and launches the specific class' main method which most of the classes already provide:

@SuppressWarnings("unused")
public static void main(String[] arg) {
  ComplexFormEx o = new ComplexFormEx(null, null);
  o.render();
}

Running and debugging Form Example

The script has ability to also download the dependency jar(s), if there are ones not hosted on Maven Central repository ( this is no longer necessary ), then to compile and package the project using maven and run the application main class from the target directory jar and libraries.

The script configuration needs to be updated with the actual paths to Java and Maven:

$MAVEN_VERSION = '3.3.9'
$JAVA_VERSION = '1.8.0_101'
$env:JAVA_HOME = "c:\java\jdk${JAVA_VERSION}"
$env:M2_HOME = "c:\java\apache-maven-${MAVEN_VERSION}"
$env:M2 = "${env:M2_HOME}\bin"
if "%JAVA_VERSION%"=="" set JAVA_VERSION=1.8.0_101
set JAVA_HOME=c:\java\jdk%JAVA_VERSION%
if "%MAVEN_VERSION%"=="" set MAVEN_VERSION=3.3.9
set M2_HOME=c:\java\apache-maven-%MAVEN_VERSION%
JAVA_VERSION='1.8.0_121'
MAVEN_VERSION='3.3.9'

After the project compiled once, it can be run the jar through the command (assuming java is in the PATH):

java.exe -cp target\swet-0.0.5-SNAPSHOT.jar;target\lib\* com.github.sergueik.swet.SimpleToolBarEx

or

java.exe -cp target/swet-0.0.5-SNAPSHOT.jar:target/lib/* com.github.sergueik.swet.SimpleToolBarEx
  • without changing to the source, there is little reason to recompile it every time. Adding the META-INF/MANIFEST.MF is a work in progress.

Paths to the browsers and browser drivers are read from the src/main.resources/application.properties file

# username / password not currently used - reserved for Sauce Labs or browserStack
username: username
password: password
# no quotes should be put around paths. Trailing whitespace is ok
# use the following syntax for environment variables: ${USERPROFILE}\\desktop\\chromedriver.exe
chromeDriverPath: ${USERPROFILE}\\desktop\\chromedriver.exe
# chromeDriverPath: ${HOME}/Downloads/chromedriver
geckoDriverPath: c:/java/selenium/geckodriver.exe
firefoxBrowserPath: C:/Program Files (x86)/Mozilla Firefox/firefox.exe
# firefoxBrowserPath: /Applications/Firefox.app/Contents/MacOS/firefox
geckoDriverPath: c:/java/selenium/geckodriver.exe
# geckoDriverPath: ${HOME}/Downloads/geckodriver
ieDriverPath: c:/java/selenium/IEDriverServer.exe
edgeDriverPath: C:/Program Files (x86)/Microsoft Web Driver/MicrosoftWebDriver.exe

Eventually other common formats: YAML, JSON, POI or Java properties file - will be supported.

Recording the page elements with SWET.

Toolbar Buttons

launch launches the browser

launch injects the SWD Element Searcher script into the page, then starts polling the page waiting for user to select some element via SWD Mouse Action CTRL + right click and to fill and submit the form: SWD Table

The Java reads back the result once it available and adds a breadcrump button: breadcumps

The breadcrump button opens the form dialog with the details of the element: form

The save and load buttons flowchart flowchart save and restore the test session in YAML format. flowchart

The code generation button flowchart

starts code generation using Jtwig tempate and elementData hash and opens result in a separate dialog: codegen

The flow export toolbar buton flowchart converts SWET recording into a Keyword Driven Framework flow that can be later saved in the Excel file. There exist a big number of Keyword-Driven Frameworks with Selenium, e.g. sergueik/skdf. These allow storing the test flow in e.g. Excel file in a format: icon The actual keyword (like clickButton, getText , verifyAttr or something else) of the step is not known during the recording, and has to be filled using this form. The rest of the columns gets read from the saved recording. It is possible to save the resul as Excel file: icon

The preferences button preferences opens the configuration dialog config Currently the browser and template selection are configurable, one also can set the base URL.

Currently project is hardcoded to start using Chrome browser on Windows, Safari on Mac and Firefox on the rest of platforms. Alternative browser can be selected during the session, but this preference is not saved. Saving / loading the session configuration from the YAML configuration file is a work in progress.

Operation

Both SWD and SWET inject certain Javascript code ElementSearch.js into the page, that the user may interact with with the SWD Mouse Action CTRL key + mouse right-click. After injecting the script the IDE waits polling for the speficic document.swdpr_command object to be created on that page. This object is created by the ElementSearch.js after user selects the specific element on the page, fills the form defining the name of that element and confirms the selection by clicking the 'Add Element' button. The document.swdpr_command object received by SWD application will contain the following properties of the selected element:

  • Legacy "indexed" xpath, that looks like /div[1]/div[1]/table[1]/tbody[1]/tr[1]/td[1]/a[1]/img[1] - all node attributes are ignored, sibling counts are evaluated.
  • Attribute-extended xpath that looks like //a[@href="/script/answers"]/img[@src="https://codeproject.net/images/question.png" and @alt = 'post an article' ]
  • Firebug-style css selector, that look like ul.nav-links li.nav-links__item div.central.featured.logo-wrapper > img.central.featured-logo every classes node has all class attributes attached.
  • Element text (translated under the hood into XPath [contains()] expression).
  • Input for Angular Protractor-specific locators repeater, binding, model, repeaterRow etc. (WIP)
  • Element ID (when available)
  • Element tag name, which is often helpful together with element's text content in constructing element locators like
IWebElement element = driver.FindElements(By.TagName("{{TAG_NAME}}")).First(o => String.Compare("{{TEXT}}", o.Text, StringComparison.InvariantCulture) == 0);

or

WebElement element = driver.findElement(
By.xpath("//{{TAG_NAME}}[contains(normalize-space(text()), '{{TEXT}}')]")

or

WebElement element = driver.findElements(  By.tagName("{{ {{TAG_NAME}} }}"
            .stream().filter(o -> o.getText().contains("{{ TEXT }}") ).findFirst();

Automation of Locator Shortening

Auto-generated locators often become unnecessarily long, e.g. for the facebook logo one may get:

div#blueBarDOMInspector > div._53jh > div.loggedout_menubar_container >
div.clearfix.loggedout_menubar > div.lfloat._ohe >
h1 > a > i.fb_logo.img.sp_Mlxwn39jCAE.sx_896ebb

Currently SWET has no algorythm for shortening such locators. Adding a smart locator trimmers is a work in progress.

Dependencies Versions

As typical with Selenium, the SWET application only run smoothly with certain Selenium jar version and it's compatible version of browser driver and browser itself is used. The SWET application master branch is being developed with
SELENIUM_VERSION 3.5.1
FIREFOX_VERSION 45.0.1
CHROME_VERSION 61.0.X
CHROMEDRIVER_VERSION 2.32

and
SELENIUM_VERSION 2.53.1
FIREFOX_VERSION 45.0.1
CHROME_VERSION 56.0.X
CHROMEDRIVER_VERSION 2.29

Some of partially supported version combinations are listed below. Some versions of Selenium ( 3.0.1 or 3.3.1 ) have been found unstable.
SELENIUM_VERSION 3.2.0
FIREFOX_VERSION 52.0 (32 bit)
GECKODRIVER_VERSION 0.14 (32 bit)
CHROME_VERSION 57.0.X
CHROMEDRIVER_VERSION 2.29

Branches selenium_301 and selenium_3x created until this code is stable in the original project location (https://github.com/sergueik/selenium_java/tree/master/swd_recorder). Stabilizing against the most recent builds of Selenium is a work in progress.

One can download virtually every old build of Firefox from https://ftp.mozilla.org/pub/firefox/releases, and selected old builds of Chrome from http://www.slimjetbrowser.com/chrome/, for other browsers the download locations vary.

This is why it may be worthwhile setting up Virtual Box e.g. selenium-fluxbox to run the appliation with fixed downlevel browser versions.

Safari Testing

If you have Mac 10.12.X Sierra / Safari 10.X , then the Apple Safari driver would be installed automatically, but it does not seems to work with Selenium 2.53. For earlier OS X releases, you have to downgrade the Selenium version in the pom.xml to 2.48 then follow the Running Selenium Tests in Safari Browser.

Code Templates

The code is generated using jtwig templates which look like

{#
template: Basic Page Objects (Java)
#}
class TestPage (Page) {
  // {{ ElementText }}
  {% if (ElementSelectedBy == 'ElementCssSelector') -%}
  @FindBy( how = How.CSS, using = "{{ ElementCssSelector }}" )
{% elseif (ElementSelectedBy == 'ElementXPath') -%}
  @FindBy( how = How.XPATH, using = "{{ ElementXPath }}" )
{% elseif (ElementSelectedBy == 'ElementId') -%}
  @FindBy( how = How.ID, using =  "{{ ElementId }}" )
{% endif -%}
{% if (ElementVariable != '') -%}
  private WebElement {{ ElementVariable }};
{% else -%}
  private WebElement element;
{% endif -%}

Any language syntax can be supported. The comment

{#
template: Name of the Template
#}

is reserved for the name of the template, when creator is allowed to provide the path to template during session configuration - every teplate file template.twig will be found and added to the formatter selection (one may need to reopen the configuration dialog to actually see the new templates). For the example above it will be shown as

Ubuntu Example Ubuntu Example

Configuration, saving and loading

SWET may be saved the element locators in the YAML format, using snakeyaml. Example:

version: '1.0'
created: '2017-02-21'
seleniumVersion: '2.53.1'

# Browser parameters
browser:
  name: firefox
  platform: linux
  version: '45.0.1'

# Browser parameters
browser:
  name: chrome
  platform: windows
  version: '54.0.2840.71'
  driverVersion: '2.24'
  driverPath: 'c:/java/selenium/chromedriver.exe'

# Selenium Browsers
browsers:
  - chrome
  - firefox

# Elements
elements:
  ce094429-d4bd-4eb0-83ab-6d10c563f456:
    ElementCssSelector: div[id = "page-body"] > div.main-container > section.main-content > div.main-content-right > div.row.highlight > section.card.titled > section.project-info > header > h3 > a
    ElementCodeName: 'sourceforge project link'
    Command: AddElement
    Caller: addElement
    ElementPageURL: https://sourceforge.net/
    CommandId: ce094429-d4bd-4eb0-83ab-6d10c563f456
    ElementStepNumber: 1
    ElementSelectedBy: ElementXPath
    ElementText: Staff Choice Outlook CalDav Synchronizer
    ElementId: ''
    ElementVariable: userSelectedVariableName
    ElementXPath: id("page-body")/div[1]/section[1]/div[2]/div[2]/section[1]/section[2]/header[1]/h3[1]/a[@href="/projects/outlookcaldavsynchronizer/?source=frontpage&position=1"]

Custom Configuration

The SWET configirarion file is in src/main.resources/application.properties:

username: username
password: password
# no quotes around paths. Trailing whitespace is ok
# use the following syntax for environment variables: ${USERPROFILE}\\desktop\\chromedriver.exe
chromeDriverPath: ${USERPROFILE}\\desktop\\chromedriver.exe
geckoDriverPath: c:/java/selenium/geckodriver.exe
firefoxBrowserPath: c:/Program Files (x86)/Mozilla Firefox/firefox.exe
ieDriverPath: c:/java/selenium/IEDriverServer.exe

The username and password entris are not currently used - these are reserved for possible users with accounts on Sauce Labs or browserStack.

Testing Individual Forms

One can useshell / cmd script to build and test individual forms (ElementAttributeEditor, RecorderConfigurationEditor, ScrolledTextEx etc.) like

run.cmd ElementAttributeEditor

and

./run.ps1 ElementAttributeEditor

and

./run.sh ElementAttributeEditor
  • one can pass form arguments field by field like
run.cmd ElementAttributeEditor -init -ElementCodeName test123

or to skip time consuming compilation part one can

java  -cp "target\swet-0.17.0-SNAPSHOT.jar;target\lib\*"  com.github.sergueik.swet.ElementAttributeEditor -init -ElementSelectedBy ElementCssSelector -ElementCssSelector a#myid -ElementId myid -ElementXPath //div[@someclass]/a

or

launch.cmd ElementAttributeEditor -init -ElementSelectedBy ElementCssSelector -ElementCssSelector a#myid -ElementId myid -ElementXPath //div[@someclass]/a

Custom Argument init Example

Note: Powershell is rejecting undeclated arguments and refusing to run e.g.

 ./run.ps1 ElementAttributeEditor "-init" "-ElementSelectedBy" "ElementCssSelector" "-ElementCssSelector" "a#myid"  "-ElementXPath" "//div[@someclass]/a"

leads to

run.ps1 : A positional parameter cannot be foundthat accepts argument '//div[@someclass]/a'.

License

__SWET__is licensed under Apache License, Version 2.0

Links

SWT

Eclipse Plugins

Code Generation

Existing Selenium Test Generation recorders and plugins

Selenium Locator Strategies

YAML

Javascript injection

Misc.

Note

Swet - according to urbanictionary, describes something that's hot. Or something that would typically take a lot of skill and practice to do, therefore causing the person to sweat.

Source Code History

The code was originally located inside a much larger repository: https://github.com/sergueik/selenium_java/tree/master/swd_recorder. On April 11 2017 the master branch HEAD was copied into separate project, to track past histories and branches please review the original project location.

License

This project is licensed under the terms of the MIT license.

Author

Serguei Kouzmine