Config file is by default searched in src/test/resources folder. The name of the config file is by default considered as selenium-config.yaml.

Sample Config file

src/test/resources/selenium-config.yaml

browsers:
  local_browser:
    browser: CHROME           # CHROME, SAFARI, EDGE, FIREFOX, IE.
    url: http://demo.guru99.com/V4/   # Application URL.
    headless_mode: false      # true, for headless, else false.
    driver: # Driver manager specific settings.
      force_cache: true       # true, false (default). Forces to use cached driver.
      force_download: true    # true, false (default). Forces to download driver each time.
      path: /drivers/         # Local path where drivers will searched for.
      version: 2.14           # Version of driver.
      exe_url: https://driver/download/url    # Driver download URL.
    remote: # Remote settings block (required when Browser is Remote).
      user_id: ${CLOUD_USER}  # Cloud User. Not required for Grid.
      password: ${CLOUD_KEY}  # Cloud Key. Not required for Grid.
      protocol: HTTPS         # HTTP, HTTPS. Default HTTP.
      url: hub-cloud.browserstack.com   # Remote hub URL
      source: BROWSERSTACK    # BROWSERSTACK, GRID, SAUCELABS
      capabilities: # Remote capabilities.
        browser: Chrome
        browser_version: 75.0
        os: Windows
        os_version: 10
        resolution: 1024x768
        name: Any Test name
      cloud_capabilities: # Cloud specific capabilities.
        seleniumVersion: 3.141.59
        name: Sauce-[Java] Sample Test
    params: # test specific map.
      user: <test-specific-user>
      password: <test-specific-password>
    playback: # Playback settings.
      screen_state: NORMAL  # FULL_SCREEN, MAXIMIZED, NORMAL
      highlight: true       # true, to highlight elements, else false.
      screen_resolution: # Screen resolution settings.
        width: 1280     # Screen width.
        height: 768     # Screen height.
      recording:
        enable: true    # true, to enable recording, else false.
        path: ./video   # Video recording path.
        prefix: VID     # Video file prefix.
      delays: # On demand delay settings.
        implicit: 60          # Implicit waits in seconds.
        explicit: 60          # Explicit waits in seconds.
        after_frame_switch: 500   # Delay after iFrame switch in milliseconds.
        after_window_switch: 500  # Delay after Window switch in milliseconds.
        before_key_press: 0   # delay before key press in milliseconds.
        after_key_press: 0    # delay after key press in milliseconds.
        before_mouse_move: 0  # delay before mouse move in milliseconds.
        after_mouse_move: 0   # delay after mouse move in milliseconds.
        before_click: 0       # delay before mouse click in milliseconds.
        after_click: 0        # delay after mouse click in milliseconds.
        page_load: 60         # page load timeout in seconds.
        script_load: 60       # script load timeout in seconds.
        highlight: 500        # highlight delay in milliseconds.
      screenshot: # Screenshot settings.
        path: ~/screenshots     # default screenshot path.
        prefix: SCR             # screenshot file prefix.
        extension: jpeg         # screenshot file extension.
        capture_on_error: false # screenshot on error.
        capture_all: true       # always capture screenshot on each event, when true.

Note: If you find any config not working, feel free to raise [an issue][].

Checkout the following examples which will guide you in writing tests. Let's have a look at the Login page of Guru99 demo site.

Remember, BrowserPage class needs to be extended for every page and also a flavour of inheritance can be added as per requirement.

Sample Page object

package com.github.wasiqb.coteafs.selenium.pages;

import com.github.wasiqb.coteafs.selenium.core.element.ITextBoxActions;
import org.openqa.selenium.By;

import com.github.wasiqb.coteafs.selenium.core.BrowserPage;
import com.github.wasiqb.coteafs.selenium.core.element.IMouseActions;

public class LoginPage extends BrowserPage {
    public ITextBoxActions password () {
        return form ().find (By.name ("password"), "Password");
    }

    public IMouseActions signIn () {
        return form ().find (By.name ("btnLogin"), "Login");
    }

    public ITextBoxActions userId () {
        return form ().find (By.name ("uid"), "User ID");
    }

    private IMouseActions form () {
        return onClickable (By.name ("frmLogin"), "Form");
    }
}

This is a new concept, here you can define actions specific to each page. This approach abstracts out the page action flows and helps in modularising the classes. So whenever the flow of the page changes, you need to change only at single place.

For every page action you need to extend AbstractPageAction. Since it is a generic class, you need to pass the action class name as it's generic type. Also, perform method needs to be implemented for every action class.

Sample page action

package com.github.wasiqb.coteafs.selenium.pages.action;

import static java.text.MessageFormat.format;

import com.github.wasiqb.coteafs.selenium.core.page.AbstractPageAction;
import com.github.wasiqb.coteafs.selenium.pages.LoginPage;
import com.github.wasiqb.coteafs.selenium.pages.MainPage;

public class LoginPageAction extends AbstractPageAction<LoginPageAction> {
    public static final String PASS    = "password";
    public static final String USER_ID = "userId";

    @Override
    public void perform () {
        final LoginPage login = new LoginPage ();
        login.userId ()
            .enterText (value (USER_ID));
        login.password ()
            .enterText (value (PASS));
        login.signIn ()
            .click ();

        login.nextPage (MainPage.class)
            .managerIdBanner ()
            .verifyText ()
            .endsWith (format ("Manger Id : {0}", value (USER_ID).toString ()));
    }
}

Test which are written using this framework are slightly different than usual. In the tests, Page actions is used instead of page objects. This can be demonstrated as shown below:

Sample Test

Every test class extends BrowserTest class.

package com.github.wasiqb.coteafs.selenium;

import static com.github.wasiqb.coteafs.selenium.config.ConfigUtil.appSetting;
import static com.github.wasiqb.coteafs.selenium.pages.action.LoginPageAction.PASS;
import static com.github.wasiqb.coteafs.selenium.pages.action.LoginPageAction.USER_ID;

import org.testng.annotations.BeforeClass;
import org.testng.annotations.Test;

import com.github.wasiqb.coteafs.selenium.core.BrowserTest;
import com.github.wasiqb.coteafs.selenium.pages.MainPage;
import com.github.wasiqb.coteafs.selenium.pages.action.LoginPageAction;

public class SeleniumTest extends BrowserTest {
    @BeforeClass
    public void setupMethod () {
        final MainPage main = new MainPage ();
        main.onDriver ()
            .navigateTo (appSetting ().getUrl ());
    }

    @Test
    public void testSignIn () {
        final LoginPageAction login = new LoginPageAction ();
        login.addInputValue (USER_ID, appSetting ().getParams ()
                .get ("user"))
            .addInputValue (PASS, appSetting ().getParams ()
                .get ("password"))
            .perform ();
    }
}

Basic synchronous run

Following is a simple testng.yaml file for running the tests on Chrome browser locally, on grid and on BrowserStack in sync.

name: Local Suite
tests:
  - name: Test Local
    preserveOrder: true
    parameters: {
      test.browser: local
    }
    classes:
      - name: com.github.wasiqb.coteafs.selenium.SeleniumTest
        includedMethods:
          - testLogin
          - testCheckboxes
          - testDropDownBox
  - name: Test Grid
    parameters: {
      test.browser: grid
    }
    classes:
      - name: com.github.wasiqb.coteafs.selenium.SeleniumTest
        includedMethods:
          - testLogin
  - name: Test BrowserStack Chrome
      preserveOrder: true
      parameters: {
        test.browser: bs_chrome
      }
      classes:
        - name: com.github.wasiqb.coteafs.selenium.SeleniumTest
          includedMethods:
            - testLogin
            - testCheckboxes
            - testDropDownBox

• test.browser: Here, the browser config key is used to tell the framework which browser config needs to be executed.

Running on local browsers or on Selenium Grid

Run the tests using following command,

$ mvn clean install -Dsuite-xml=testng.yaml

Running on BrowserStack or any other cloud solution

Run the tests using following command,

$ mvn clean install -Dsuite-xml=testng.yaml -DCLOUD_USER=<cloud_user> -DCLOUD_KEY=<cloud_key>