Documentation
In order to better understand what is webdriver, we recommend reading this document .
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
fi1.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}/urlYou 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_session2. Timeouts
2.1 Get Timeouts
Return the active session’s timeouts configuration. The configuration detail is here .
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)
# Google3.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
back3.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
forward3.6 Refresh
Refresh the current page.
Command
refresh
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://www.google.com'
refresh4. 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
# Terms4.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 ###
# Welcome4.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
# Welcome24.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 ###
# hoge5.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 ###
# block5.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 ###
# Welcome5.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 ###
# h15.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 ###
# true6. 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 removed7. 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.sh8. 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
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_cookies9. Context
9.1 Get Window Handle
Command
get_window_handle
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
get_window_handle
### output ###
# CDwindow-FDE2D85F1C439C4AA3817A3000F122129.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-96116C7F4548CB8B155F8821B6DEFDEB9.3 New Window
Create a new tab.
Command
new_window
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
new_window9.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 $newWindow9.6 Switch To Frame
Switch to iframe.
More information is here .
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 $buttontest.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_frameExample
#!/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_frame9.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_window9.11 Minimize Window
Hide window.
Command
minimize_window
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
minimize_window9.12 Fullscreen Window
Set window to fullscreen.
Command
fullscreen_window
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
fullscreen_window10. Alerts
10.1 Get Alert Text
Get the text from an active alert dialog.
Command
get_alert_text
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
exec_script "alert('Hello!')"
text=$(get_alert_text)
# Hello!10.2 Send Alert Text
Send text to an active alert (prompt dialog).
Command
send_alert_text ${value}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
exec_script "prompt('Enter your name:')"
send_alert_text "shellnium"
accept_alert10.3 Accept Alert
Accept (click OK on) an alert dialog.
Command
accept_alert
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
exec_script "alert('Hello!')"
accept_alert10.4 Dismiss Alert
Dismiss (click Cancel on) an alert dialog.
Command
dismiss_alert
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
exec_script "confirm('Are you sure?')"
dismiss_alert11. Document (additional)
11.1 Element Screenshot
Take a screenshot of a specific element.
Command
element_screenshot ${elementId}
# or
element_screenshot ${elementId} ${path}Default the screenshot saved to ./screenshot.png.
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://www.google.com'
logo=$(find_element 'css selector' 'img#hplogo')
element_screenshot $logo ./logo.png11.2 Get Page Source
Get the HTML source of the current page.
Command
get_page_source
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://www.google.com'
source=$(get_page_source)
echo "$source"
### output ###
# <!DOCTYPE html><html itemscope="" itemtype="http://schema.org/WebPage" lang="en">...12. Actions
Shellnium provides convenience wrappers for W3C WebDriver Actions .
Mouse Actions
12.1 Mouse Move To
Move the mouse cursor to an element.
Command
mouse_move_to ${elementId}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
element=$(find_element 'css selector' '.menu-item')
mouse_move_to $element12.2 Hover
Hover over an element. This is an alias for mouse_move_to.
Command
hover ${elementId}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
dropdown=$(find_element 'css selector' '.dropdown')
hover $dropdown
# The dropdown menu will appear12.3 Double Click
Double-click on an element.
Command
double_click ${elementId}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
element=$(find_element 'id' 'editable')
double_click $element
# Selects a word by double-clicking12.4 Right Click
Right-click (context menu) on an element.
Command
right_click ${elementId}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
element=$(find_element 'id' 'target')
right_click $element
# Opens the context menu12.5 Drag and Drop
Drag an element from source to target.
Command
drag_and_drop ${sourceElementId} ${targetElementId}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
source=$(find_element 'id' 'draggable')
target=$(find_element 'id' 'droppable')
drag_and_drop $source $targetKeyboard Actions
12.6 Key Press
Press and release a single key.
Command
key_press ${key}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
# Press the Enter key
key_press "$KEY_ENTER"
# Press the Escape key
key_press "$KEY_ESCAPE"12.7 Key Down
Hold a key down. Use with key_up to release.
Command
key_down ${key}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
# Hold Shift key
key_down "$KEY_SHIFT"
# ... perform other actions while Shift is held ...
key_up "$KEY_SHIFT"12.8 Key Up
Release a held key.
Command
key_up ${key}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
key_down "$KEY_CONTROL"
key_press "a"
key_up "$KEY_CONTROL"
# This selects all text (Ctrl+A)12.9 Send Key Combo
Send a key combination (modifier + key).
Command
send_key_combo ${modifier} ${key}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
# Ctrl+A (select all)
send_key_combo "$KEY_CONTROL" "a"
# Ctrl+C (copy)
send_key_combo "$KEY_CONTROL" "c"
# Ctrl+V (paste)
send_key_combo "$KEY_CONTROL" "v"Low-Level Actions API
12.10 Perform Actions
Execute low-level W3C WebDriver Actions . Accepts a JSON string describing the actions to perform.
Command
perform_actions ${actions_json}Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
element=$(find_element 'id' 'target')
# Move mouse to element and click
actions='{"actions":[{"type":"pointer","id":"mouse","parameters":{"pointerType":"mouse"},"actions":[{"type":"pointerMove","duration":100,"origin":{"ELEMENT":"'$element'"},"x":0,"y":0},{"type":"pointerDown","button":0},{"type":"pointerUp","button":0}]}]}'
perform_actions "$actions"12.11 Release Actions
Release all held keys and pointer buttons.
Command
release_actions
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://example.com'
key_down "$KEY_SHIFT"
# ... actions with shift held ...
release_actions
# All keys and buttons are now released13. Key Constants
Shellnium provides key constants for use with send_keys, key_press, key_down, key_up, and send_key_combo.
| Constant | Key |
|---|---|
KEY_BACKSPACE | Backspace |
KEY_TAB | Tab |
KEY_RETURN | Return |
KEY_ENTER | Enter |
KEY_SHIFT | Shift |
KEY_CONTROL | Control |
KEY_ALT | Alt |
KEY_ESCAPE | Escape |
KEY_SPACE | Space |
KEY_PAGE_UP | Page Up |
KEY_PAGE_DOWN | Page Down |
KEY_END | End |
KEY_HOME | Home |
KEY_ARROW_LEFT | Left Arrow |
KEY_ARROW_UP | Up Arrow |
KEY_ARROW_RIGHT | Right Arrow |
KEY_ARROW_DOWN | Down Arrow |
KEY_INSERT | Insert |
KEY_DELETE | Delete |
KEY_F1 | F1 |
KEY_F12 | F12 |
KEY_META | Meta / Command |
Example
#!/usr/bin/env bash
source ./lib/selenium.sh
navigate_to 'https://www.google.com'
searchBox=$(find_element 'name' 'q')
# Type text and press Enter
send_keys $searchBox "panda${KEY_ENTER}"
# Press Tab to move focus
send_keys $searchBox "${KEY_TAB}"
# Select all with Ctrl+A
send_key_combo "$KEY_CONTROL" "a"