Documentation

Documentation

In order to better understand what is webdriver, we recommend reading this document (opens in a new tab).

1. Sessions

1.1 Is Ready

Check if ChromeDriver is running.
Usually, this method is executed at the beginning of the script.

Command

is_ready

Example

#!/usr/bin/env bash
source ./lib/core.sh
 
if [ "$(is_ready)" != 'true' ]; then
  printf "\e[35m[ERROR] chromedriver is not running.\e[m\n"
  exit
fi

1.2 New Session

Creates a new WebDriver session.

Command

new_session

Example

#!/usr/bin/env bash
source ./lib/core.sh
 
sessionId=$(new_session)
BASE_URL=${ROOT}/session/${sessionId}
 
# ${ROOT} is defined in core.sh
# you can use ${BASE_URL} to exec WebDriver API
# ex.) curl -s -X GET ${BASE_URL}/url

You can set args for chrome options. new_session $@.

# headless
sessionId=$(new_session --headless)
# headless and lang=es
sessionId=$(new_session --headless --lang=es)

1.3 Delete Session

Close the session.

Command

delete_session

Example

#!/usr/bin/env bash
# create a new session in ./lib/selenium.sh
source ./lib/selenium.sh
 
# open the page
navigate_to 'https://www.google.com'
 
# close the session
delete_session

2. Timeouts

2.1 Get Timeouts

Return the active session’s timeouts configuration. The configuration detail is here (opens in a new tab).

Command

get_timeouts

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
timeConfig=$(get_timeouts)
 
### output ###
# {
#   "implicit": 0,
#   "pageLoad": 300000,
#   "script": 30000
# }

2.2 Set Timeouts

Set timeouts configuration.

Command

set_timeouts ${script} ${pageLoad} ${implicit}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
script=1000
pageLoad=2000
implicit=3000
set_timeouts ${script} ${pageLoad} ${implicit}
 
get_timeouts
 
### output ###
# {
#   "implicit": 3000,
#   "pageLoad": 2000,
#   "script": 1000
# }

2.3 Set Timeout Script

Set script timeouts.

Command

set_timeout_script ${value}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
set_timeout_script 1000
 
get_timeouts
 
### output ###
# {
#   "implicit": 0,
#   "pageLoad": 300000,
#   "script": 1000
# }

2.4 Set Timeout PageLoad

Set pageLoad timeouts.

Command

set_timeout_pageLoad ${value}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
set_timeout_pageLoad 2000
 
get_timeouts
 
### output ###
# {
#   "implicit": 0,
#   "pageLoad": 2000,
#   "script": 30000
# }

2.5 Set Timeout Implicit

Set implicit timeouts.

Command

set_timeout_implicit ${value}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
set_timeout_implicit 3000
 
get_timeouts
 
### output ###
# {
#   "implicit": 3000,
#   "pageLoad": 300000,
#   "script": 300000
# }

3. Navigation

3.1 Navigate To

Open the url.

Command

navigate_to ${url}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'

3.2 Get Current Url

Get the current url.

Command

get_current_url

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
currentUrl=$(get_current_url)
# https://www.google.com/

3.3 Get Title

Get the page title.

Command

get_title

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
title=$(get_title)
# Google

3.4 Back

Invoking window.history.back.

Command

back

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
# open google top
navigate_to 'https://www.google.com'
 
# no page
back

3.5 Forward

Invoking window.history.forward.

Command

forward

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
# open google top
navigate_to 'https://www.google.com'
 
# no page
back
 
# re-open google top
forward

3.6 Refresh

Refresh the current page.

Command

refresh

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
refresh

4. Element Retrieval

4.1 Find Element

You can use find_element method to find a element.

Command

find_element ${property} ${value}

The ${property} is following:

  • 'id'
  • 'name'
  • 'css selector'
  • 'link text'
  • 'partial link text'
  • 'tag name'
  • 'class name'
  • 'xpath'

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
# Open the apage.
navigate_to 'https://www.google.com'
 
# get the element of the search box.
searchBox=$(find_element 'name' 'q')
 
# You can perform various actions on the element you just retrieved. ex.) `send_keys`
send_keys $searchBox "animal\n"

4.2 Find Element By Id

Example usage:

<html>
<body>
  <p id="welcome">Hi, there!</p>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'welcome')

4.3 Find Element By Name

Example usage:

<html>
<body>
  <input name="username" type="text" />
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'name' 'username')

4.4 Find Element By Css Selector

Example usage:

<html>
<body>
  <p class="content">Site content goes here.</p>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'css selector' 'p.content')

4.5 Find Element By Link Text

Example usage:

<html>
<body>
  <a href="login.html">Login</a>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'link text' 'Login')

4.6 Find Element By Partial Link Text

Example usage:

<html>
<body>
  <a href="login.html">Login</a>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'partial link text' 'Log')

4.7 Find Element By Tag Name

Example usage:

<html>
<body>
  <h1>Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'tag name' 'h1')

4.8 Find Element By Class Name

Example usage:

<html>
<body>
  <h1 class="title">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'class name' 'title')

4.9 Find Element By Xpath

Example usage:

<html>
<body>
  <div id="contents">
    <p>welcome</p>
    <p>here</p>
  </div>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'xpath' '//*[@id="contents"]/p[1]')

4.10 Find Elements

To find multiple elements, you can use find_elements method.

Command

find_elements ${property} ${value}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
# Open the apage.
navigate_to 'https://www.google.com/?gl=us&hl=en&gws_rd=cr&pws=0'
 
elements=$(find_elements 'tag name' 'a')
 
for element in ${elements[@]};do
  get_text ${element}
done
 
### output ###
# About
# Store
# Gmail
# Images
# 
# Sign in
# 
# 
# Advertising
# Business
# How Search works
# Carbon neutral since 2007
# Privacy
# Terms

4.11 Find Element From Element

Example usage:

<html>
<body>
  <div id="container">
    <h1>Welcome</h1>
  </div>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
container=$(find_element 'id' 'container')
title=$(find_element_from_element ${container} 'tag name' 'h1')
get_text ${title}
 
### output ###
# Welcome

4.12 Find Elements From Element

Example usage:

<html>
<body>
  <div id="container">
    <h2>Welcome1</h2>
    <h2>Welcome2</h2>
  </div>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
container=$(find_element 'id' 'container')
titles=$(find_element_from_element ${container} 'tag name' 'h2')
for title in ${titles[@]}; do
  get_text ${title}
done
 
### output ###
# Welcome1
# Welcome2

4.13 Get Active Element

Get a active element.

Command

get_active_element

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
# The top page of google has the search box in focus.
searchBox=$(get_active_element)

5. Element State

5.1 Get Attribute

Example usage:

<html>
<body>
  <h1 id="title" style="color:red;">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'title')
get_attribute ${element} 'style'
### output ###
# color:red;

5.2 Get Property

Example usage:

<html>
<body>
  <input id="username" type="text">
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
input=$(find_element 'id' 'username')
send_keys $input 'hoge'
get_property ${input} 'value'
### output ###
# hoge

5.3 Get Css Value

Example usage:

<html>
<body>
  <style>
    h1 {
      display: block;
    }
  </style>
  <h1 id="container">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'container')
get_css_value ${element} 'display'
### output ###
# block

5.4 Get Text

Example usage:

<html>
<body>
  <h1 id="container">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'container')
get_text ${element}
### output ###
# Welcome

5.5 Get Tag Name

Example usage:

<html>
<body>
  <h1 id="container">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'container')
get_tag_name ${element}
### output ###
# h1

5.6 Get Rect

Example usage:

<html>
<body>
  <h1 id="container">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'container')
get_rect ${element}
### output ###
# {
#   "height": 37,
#   "width": 784,
#   "x": 8,
#   "y": 8
# }

5.7 Is Element Enabled

Example usage:

<html>
<body>
  <h1 id="container">Welcome</h1>
</body>
<html>

Command usage:

#!/usr/bin/env bash
...
element=$(find_element 'id' 'container')
is_element_enabled ${element}
### output ###
# true

6. Element Interaction

6.1 Send Keys

Set text to the input element.

Command

send_keys ${inputElement} ${text}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
searchBox=$(find_element 'name' 'q')
 
# Input to the search box and enter.
send_keys ${searchBox} "animal\n"

6.2 Click

Click the element.

Command

click ${element}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
searchBox=$(find_element 'name' 'q')
 
click ${searchBox}

6.3 Element Clear

Set an empty string to input element.

element_clear ${element}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
searchBox=$(find_element 'name' 'q')
 
send_keys $searchBox 'hoge'
 
element_clear ${searchBox}
# 'hoge' is removed

7. Document

7.1 Exec Script

Execute Javascript codes.

Command

exec_script ${value}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
exec_script "alert('hoge')"

7.2 Screenshot

Screenshot the current page.

Command

screenshot
# or
screenshot ${path}

Default the screenshot saved to./screenshot.png.

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
screenshot ./lib/hoge.png
 
#
# $ tree
# .
# ├── demo.sh
# ├── lib
# │   ├── core.sh
# │   ├── hoge.png # <-- saved!
# │   ├── selenium.sh
# │   └── util.sh

8. Cookies

8.1 Get All Cookies

Command

get_all_cookies

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
get_all_cookies
### output ###
# {
#   "domain": ".google.com",
#   "expiry": 1679734375,
#   "httpOnly": false,
#   "name": "OGPC",
#   "path": "/",
#   "sameSite": "Lax",
#   "secure": false,
#   "value": "19027681-1:"
# }
# {
#   "domain": ".google.com",
#   "expiry": 1692953573,
#   "httpOnly": true,
# ...

8.2 Get Named Cookie

Command

get_named_cookie "$name"

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
get_named_cookie "OGPC"
### output ###
# {
#   "domain": ".google.com",
#   "expiry": 1679734849,
#   "httpOnly": false,
#   "name": "OGPC",
#   "path": "/",
#   "sameSite": "Lax",
#   "secure": false,
#   "value": "19027681-1:"
# }

8.3 Add Cookie

Command

add_cookie "$cookie_value"

The $cookie_value is a JSON. The JSON keys is following:

  • name (required)
  • value (required)
  • path
  • domain
  • expiry
  • secure
  • httpOnly
  • sameSite

The reference is https://www.w3.org/TR/webdriver/#cookies (opens in a new tab)

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
cookie_value='{"name": "hoge", "value": "Hello World!"}'
add_cookie "$cookie_value"
 
# check the cookie
get_named_cookie "hoge"
### output ###
# {
#   "domain": "www.google.com",
#   "expiry": 1711701594,
#   "httpOnly": false,
#   "name": "hoge",
#   "path": "/",
#   "sameSite": "Lax",
#   "secure": true,
#   "value": "Hello World!"
# }

8.4 Delete Cookie

Command

delete_cookie "$name"

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
delete_cookie "OGPC"
 
# check the cookie
get_named_cookie "OGPC"
### output ###
# {
#   "message": "no such cookie\n  (Session info: chrome=110.0.5481.100)\n  (Driver info: chromedriver=110.0.5481.77 (65ed616c6e8ee3fe0ad64fe83796c020644d42af-refs/branch-heads/5481@{#839}),platform=Mac OS X 12.5.0 arm64)"
# }

8.5 Delete All Cookies

Command

delete_all_cookies

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'https://www.google.com'
 
delete_all_cookies

9. Context

9.1 Get Window Handle

Command

get_window_handle

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
get_window_handle
### output ###
# CDwindow-FDE2D85F1C439C4AA3817A3000F12212

9.2 Get Window Handles

Command

get_window_handles

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
newWindow=$(new_window)
get_window_handles
### output ###
# CDwindow-865D9DCFC26B4DE003F428C5C182E06A
# CDwindow-96116C7F4548CB8B155F8821B6DEFDEB

9.3 New Window

Create a new tab.

Command

new_window

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
new_window

9.4 Delete Window

Close the tab.

Command

delete_window ${window}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
oldWindow=$(get_window_handle)
new_window
delete_window ${oldWindow}

9.5 Switch To Window

Switch to the tab.

Command

switch_to_window ${window}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
newWindow=$(new_window)
switch_to_window $newWindow

9.6 Switch To Frame

Switch to iframe.

More information is here (opens in a new tab).

Command

switch_to_frame ${id}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'file:///Users/$YOU/shellnium/test.html'
 
switch_to_frame 'exampleFrame'
button=$(find_element 'id' 'countButton')
click $button

test.html

<!DOCTYPE html>
<html lang="en">
<body>
  <iframe id="exampleFrame" src="./frame.html">
</body>
</html>

frame.html

<!DOCTYPE html>
<html lang="en">
<body>
  <script>
    function countUp() {
      var elm = document.getElementById('count')
      var count = parseInt(elm.innerText)
      elm.innerText = count + 1
    }
  </script>
  <button id="countButton" onclick="countUp()">click me</button>
  <span id="count">1</span>
</body>
</html>

9.7 Switch To Parent Frame

Switch to parent frame.

Command

switch_to_parent_frame

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
navigate_to 'file:///Users/$YOU/shellnium/test.html'
 
# switch to iframe
switch_to_frame 'exampleFrame'
button=$(find_element 'id' 'countButton')
click $button
 
# back to main window
switch_to_parent_frame

9.8 Get Window Rect

Get current window rect.

Command

get_window_rect

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
get_window_rect
 
### output ###
# {
#   "height": 767,
#   "width": 1200,
#   "x": 22,
#   "y": 47
# }

9.9 Set Window Rect

Command

set_window_rect ${x} ${y} ${width} ${height}

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
x=50
y=100
width=500
height=600
 
set_window_rect ${x} ${y} ${width} ${height}
### output ###
# {
#   "height": 600,
#   "width": 500,
#   "x": 50,
#   "y": 100
# }

9.10 Maximize Window

Increase the window to the maximum available size without going full-screen.

Command

maximize_window

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
maximize_window

9.11 Minimize Window

Hide window.

Command

maximize_window

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
minimize_window

9.12 Fullscreen Window

Set window to fullscreen.

Command

fullscreen_window

Example

#!/usr/bin/env bash
source ./lib/selenium.sh
 
fullscreen_window
Getting Started