Skip to Content
Documentation

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 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 .

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')

Example usage:

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

Command usage:

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

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, # ...

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:" # }

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!" # }

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 .

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

minimize_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

10. 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_alert

10.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_alert

10.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_alert

11. 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.png

11.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 $element

12.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 appear

12.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-clicking

12.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 menu

12.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 $target

Keyboard 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 released

13. Key Constants

Shellnium provides key constants for use with send_keys, key_press, key_down, key_up, and send_key_combo.

ConstantKey
KEY_BACKSPACEBackspace
KEY_TABTab
KEY_RETURNReturn
KEY_ENTEREnter
KEY_SHIFTShift
KEY_CONTROLControl
KEY_ALTAlt
KEY_ESCAPEEscape
KEY_SPACESpace
KEY_PAGE_UPPage Up
KEY_PAGE_DOWNPage Down
KEY_ENDEnd
KEY_HOMEHome
KEY_ARROW_LEFTLeft Arrow
KEY_ARROW_UPUp Arrow
KEY_ARROW_RIGHTRight Arrow
KEY_ARROW_DOWNDown Arrow
KEY_INSERTInsert
KEY_DELETEDelete
KEY_F1F1
KEY_F12F12
KEY_METAMeta / 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"
Last updated on