Reference

Use this section to look up information on steps, helper functions and run options you can use. You can explore using the navigation headers.

Steps

The steps you can use in TagUI are listed here.

Mouse and Keyboard

click

Left clicks on the identifier.
Can use DOM, XPath, Point, Image identifiers.
click [DOM/XPath/Point/Image]

Examples

click Main concepts
click //nav/div/div[2]/ul/li[4]/ul/li[1]/a
click (500,200)
click button.png

rclick

Right clicks on the identifier.
Can use DOM, XPath, Point, Image identifiers.
rclick [DOM/XPath/Point/Image]

See click for examples.

dclick

Double left clicks on the identifier.
Can use DOM, XPath, Point, Image identifiers.
dclick [DOM/XPath/Point/Image]

See click for examples.

hover

Moves mouse cursor to the identifier.
Can use DOM, XPath, Point, Image identifiers.
hover [DOM/XPath/Point/Image]

See click for examples.

type

Types into a web input. You can use [clear] to clear the field and [enter] to hit the Enter key.
Can use DOM, XPath, Point, Image identifiers.
type [DOM/XPath/Point/Image] as [text to type]

Examples

type search-term as John Wick
type //input[@name="search"] as John Wick
type (500,200) as John Wick
type input_field.png as John Wick

type search-term as [clear]John Wick[enter]
type //input[@name="search"] as [clear]John Wick[enter]
type (500,200) as [clear]John Wick[enter]
type input_field.png as [clear]John Wick[enter]

keyboard

Enters keystrokes directly.

keyboard [keys]

You can use the following special keys:

  • [clear]
  • [shift] [ctrl] [alt] [cmd] [meta] [enter]
  • [win] [space] [tab] [esc] [backspace] [delete]
  • [up] [down] [left] [right] [pageup] [pagedown]
  • [home] [end] [insert] [f1] .. [f15]
  • [printscreen] [scrolllock] [pause] [capslock] [numlock]

Examples

keyboard [win]run[enter]
keyboard [printscreen]
keyboard [ctrl]c
keyboard [tab][tab][tab][enter]

keyboard [cmd][space]
keyboard safari[enter]
keyboard [cmd]c

mouse

Explicitly sends a mouse event at the current mouse position.
In most cases, you want you use click instead.
mouse down
mouse up

Web

visit

Visits the provided URL.

[URL]

Examples

https://google.com

select

Selects a dropdown option in a web input.
Can use DOM, XPath identifiers.
select [DOM/XPath of select input element] as [option value]

Examples

select variant as blue

table

Saves html table data to a csv file. This only works for simple, neat HTML tables.
Uses XPath identifier only.
table [XPath] to [filename.csv]

Examples

table //table[1] to exchange-rates.csv

frame

Modifies the next steps to use the DOM or XPath in a frame or subframe.

frame [frame name]
  [steps]

frame [frame name] | [subframe name]
  [steps]

Examples

frame navigation
  click Products

frame main | register
  click Register

download

Downloads a file at a URL and saves it.
Saves to the flow’s folder by default, but you can also provide a full path to save to.
download [file url] to [filename]

Examples

download https://github.com/kelaberetiv/TagUI/releases/download/v5.11.0/TagUI_Windows.zip to tagui.zip

upload

Uploads file to a website.
Can use DOM, XPath identifiers.
upload [DOM/XPath of upload input element] as [filename]

Examples

upload //input[@name="attach"] as report.csv

api

Call a web API and save the response to the variable api_result.

api https://some-api-url

Examples

api https://api.github.com/repos/kelaberetiv/TagUI/releases
js obj = JSON.parse(api_result)
js author = obj[0].author.login

Using Variables

read

Gets some text or value and stores it in a variable.
Can use DOM, XPath, Region, Image identifiers.
read [DOM/XPath/Region/Image] to [variable]

When you provide a Region or Image identifier, TagUI uses OCR (Optical Character Recognition) to read the characters from the screen.

Examples

read //p[@id="address"] to address

read //p[@id="address"]/@class to address-class

read (500,200)-(600,400) to id-number

read frame.png to email

assign

Saves text to a variable.

[variable] = [value]
When using text in the value, surround the text in quotes, like “some text”.
This is actually treated by TagUI as JavaScript, so you can assign numbers to variables or use other JavaScript functions.
The variable name needs to be a single word and cannot start with a number.

Examples

count = 5
username = "johncleese"
fullname = firstname + lastname

File Saving/Loading

write

Saves a new line of text to an existing file.

write [text] to [filename]
write [`variable`] to [filename]

Examples

write firstname,lastname to names.csv
write `fullreport` to report.txt

dump

Saves text to a new file.

dump [text] to [filename]
dump [`variable`] to [filename]

See dump for examples.

load

Loads file content to a variable.

load [filename] to [variable]

Examples

load report.txt to report

snap

Saves a screenshot of the whole page, an element or a region.
Can use DOM, XPath, Region, Image identifiers.
snap [DOM/XPath/Region/Image/page] to [filename]

If you use page as the identifier, it takes a screenshot of the whole webpage.

Examples

snap logo to logo.png

snap page to webpage.png

Showing output

echo

Shows some output on the command line.

echo [text]
echo [`variable`]

Examples

echo Flow has started
echo The user is `username`

show

Shows element text directly on the command line.
Can use DOM, XPath identifiers.
show [DOM/XPath]

Examples

show review-text

check

Shows some output on the command line based on a condition.

check [condition] | [text if true] | [text if false]

Examples

check header_home_text equals to "Home" | "header text is correct" | "header text is wrong"

Custom code

js

Runs JavaScript code explicitly. TagUI has direct access to the JavaScript variables.

js [JavaScript statement]

js begin
[JavaScript statements]
js finish

Examples

js obj = JSON.parse(api_result)
dump `obj` to result.json

js begin
obj = JSON.parse(api_result)
randomInteger = Math.floor(Math.random() * Math.floor(5)) + 1
js finish
dump `obj` to result.json

py

Runs Python code and saves the stdout to the variable py_result as a string.

py [Python statement]

py begin
[Python statements]
py finish

Examples

py result = 2 + 3
py print(result)
echo `py_result`

py begin
import random
random_integer = random.randint(1,6)
print(random_integer)
py finish
echo `py_result`

run

Runs a command in Command Prompt or Terminal and saves the stdout to the variable run_result.

run [shell command]

Examples

run mkdir new_directory

vision

Runs Sikuli code.

vision [Sikuli statement]

vision begin
[Sikuli statements]
vision finish

Examples

vision click("button1.png")

dom

Runs code in the browser dom and saves the stdout to the variable dom_result.

dom [JavaScript statement to run in the DOM]

dom begin
[JavaScript statements to run in the DOM]
dom finish

Examples

dom intro = document.getElementById("intro")

r

Runs R statements and saves the stdout to the variable r_result.

r [R statement]

r begin
[R statements]
r finish

Miscellaneous

wait

Explicitly wait for some time.

wait [seconds to wait]
wait [seconds to wait] s
wait [seconds to wait] seconds

Examples

wait 5.5
wait 10 s
wait 20 seconds

timeout

Changes the auto-wait timeout when waiting for web elements to appear.

timeout [seconds to wait before timeout]

Examples

timeout 300

ask

Prompts user for input and saves the input as the variable ask_result.

ask [prompt]

Examples

ask What is the date of the receipt? (in DD-MM-YYYY)
type search as `ask_result`

live

Wait for user confirmation before continuing. The user must enter “done” before the flow continues.

live

tagui

Runs another TagUI flow. Checks the flow’s folder.

tagui [flow file]
tagui [folder/flow file]

Examples

tagui update-forex.tag
tagui flows/update-forex.tag

comment

Adds a comment.

// [comment]

Examples

// updates the forex rates

Run options

You can use the below options when running tagui.

For example, the command below runs my_flow.tag without showing the web browser, while storing the flow run result in tagui_report.csv.

tagui my_flow.tag -headless -report

-deploy or -d

Deploys a flow, creating a shortcut which can be double-clicked to run the flow. If the flow file is moved, a new shortcut must be created. The flow will be run with all the options used when creating the shortcut.

-headless or -h

Runs the flow with an invisible Chrome web browser (does not work for visual automation).

-nobrowser or -n

Runs without any web browser, for example to perform automation only with visual automation.

-report or -r

Tracks flow run result in tagui/src/tagui_report.csv and saves html logs of flows execution.

-speed or -s

Runs a datatable flow, skipping the default 3s delay and restarting of Chrome between datatable iterations.

-quiet or -q

Runs without output to command prompt except for explicit output (echo, show, check steps and errors etc).

my_datatable.csv

Uses the specified csv file as the datatable for batch automation. See datatables.

input(s)

Add your own parameter(s) to be used in your automation flow as variables p1 to p9.

See other deprecated options.

Helper functions

csv_row()

Formats an array for writing to csv file.

Examples

read name_element to name
read price_element to price
read details_element to details
write `csv_row([name, price, details])` to product_list.csv

count()

Gets the number of elements matching the identifier specified. Note that the identifier needs to be in single quotes ''.

Examples

rows = count('table-rows')

clipboard()

Puts text onto the clipboard, or gets the clipboard text (if no input is given).

Examples

clipboard('some text')
keyboard [ctrl]v

keyboard [ctrl]c
contents = clipboard()

url()

Gets the URL of the current web page.

Examples

if url() contains 'success'
  click button1

title()

Gets the title of the current web page.

Examples

if title() contains 'Confirmation'
  click button1

text()

Gets all text content of the current web page.

Examples

if text() contains 'success'
  click button1

timer()

Gets the time elapsed in seconds in between each running of this function.

Examples

timer()
click button1
click button2
click button3
echo timer()

exist()

Waits until the timeout for an element to exist and returns a JavaScript true or false depending on whether it exists or not.
Note that the identifier is surrounded by quotes.
Can use DOM, XPath, Image identifiers.
exist('[DOM/XPath/Image]')

Examples

if exist('//table')
  click button1

present()

Same as exist() except that it does not wait until the timeout and immediately returns true or false.
Note that the identifier is surrounded by quotes.
Can use DOM, XPath, Image identifiers.

Examples

if present('//table')
  click button1

mouse_xy()

Gets the x, y coordinates of the current mouse position.
Particularly useful in live mode.

Examples

echo `mouse_xy()`

mouse_x()

Gets the x coordinate of the current mouse position as a number, eg 200.

Examples

hover element.png
x = mouse_x() + 200
y = mouse_y()
click (`x`,`y`)

mouse_y()

Gets the y coordinate of the current mouse position as a number, eg 200.

Examples

hover element.png
x = mouse_x() + 200
y = mouse_y()
click (`x`,`y`)