Main concepts

Flows

TagUI automates your actions by running flows, which are just text files with the .tag file extension.

You can run a flow in the Command Prompt/Terminal like this:

tagui my_flow.tag

TagUI looks for my_flow.tag in your current working directory. You can also provide the full path to your flow:

tagui c:\tagui\samples\1_google.tag

You can also run flows on a fixed schedule.

Run by double-click

You can create a shortcut file with:

tagui my_flow.tag -deploy

or using the shortcut -d:

tagui my_flow.tag -d

This creates a shortcut (my_flow.cmd) to run your flow just by double clicking the shortcut. The shortcut is in the same folder as your flow, but you can move it to your desktop or anywhere else for easy access.

If you want to create the shortcut file with options like headless (-h), you can just add them in the same line like this:

tagui my_flow.tag -h -d

Note

If you move your flow file to another folder, you will need to create a new shortcut file.

Run from a URL

You can also run a flow directly from a URL:

tagui https://raw.githubusercontent.com/kelaberetiv/TagUI/master/flows/samples/1_google.tag

Hide the browser

You can run web flows without showing the web browser by running TagUI with the headless option.

tagui my_flow.tag -headless

or using the shortcut -h:

tagui my_flow.tag -h

This allows you to continue using your desktop normally while the flow is running, but it will not work if your flow uses visual automation, because visual automation reads and clicks what is on your screen.

Steps

Flows are made out of steps. Below are some common steps. You can see all the steps in the step reference.

click

One of the most common steps is click. You can use it to click on a web element:

click Getting started

This command tells TagUI to try to click on any element which has “Getting started” as its “id”, “name”, “class” or “title” attributes (How to find an element’s attributes), or as a last resort, has “Getting started” in its text.

This method usually works for targeting what you want, but you can be more explicit by providing an XPath. XPath is a powerful way to choose which web element you want to target. Use it like this:

click //a[@class="icon icon-home"]

You can also click on a certain point on your screen:

click (500,300)

Here, 500 and 300 are x-y coordinates. This command clicks on a point which is 500 pixels from the left of your screen and 300 pixels from the top of your screen. A good way to discover which coordinates to input is to use the mouse_xy() helper function in live mode.

Lastly, you can use visual automation to click where it matches a previously saved image. This command looks for button.png in the same folder as your flow, then looks for a similar image on your screen, and clicks it:

click button.png

It’s often a good idea to keep your flows and images organised. You can create a folder (eg. named images) for your images and use the image like this instead:

click image/button.png

visit

You can visit a webpage simply by entering the url:

https://somewebsite.com

type

You can type into web inputs. This command finds the element “some-input” in the same way as for the click step and types “some-text” into it:

type some-input as some-text

You can use [clear] to clear the input and [enter] to hit the Enter key:

type some-input as [clear]some-text[enter]

You can also use an image as the target, just like with the click step:

type some-input.png as some-text

assign

You can assign values into variables. This makes them easier to reference and work with.

This example uses the count() helper function, counts the number of elements found with id/name/text with ‘row’ in them and assigns it to a variable row_count for later use:

row_count = count('row')

read

The read step allows you to save text from web elements or from the screen into a variable.

This command finds the element “some-element” and saves its value into a variable called “some-variable”:

read some-element to some-variable

read can also use visual automation and OCR to read text from a region of your screen. The output from this may not be completely accurate as it relies on OCR.

This command reads all the text in the rectangle formed between the points (300,400) and (500,550):

read (300,400)-(500,550) to some-variable

You can also use XPath to read some attribute values from web elements. This command reads the id attribute from the element:

read //some-element/@some-attribute to some-variable

Identifiers

You have probably noticed that different steps have different ways that they target elements, called identifiers. Let’s look at the different types of identifiers.

Note

The DOM and XPath identifiers only work for Chrome. To automate other browsers, use the Point/Region and Image identifiers.

DOM

click Getting started

This matches an element in the DOM (Document Object Model) of the web page, matching either the id, name, class attributes or the text of the element itself.

XPath

click //body/div[1]/nav/div/div[1]/a

This matches the XPath of an element in the web page. It is a more explicit and powerful way of targeting web elements.

Note

You can use CSS selectors too in place of XPath, but XPath is preferred.

Point

click (200,500)

This matches the point on the screen 200 pixels from the left of the screen and 500 pixels from the top of the screen. This uses visual automation.

Region

read (300,400)-(500,550) to some-variable

This matches the rectangle formed between the two points (300,400) and (500,550). See Point. This uses visual automation.

Image

click button.png

This matches any area on the screen that looks similar to an image file button.png (in the folder of the flow). You first need to take a screenshot of button.png. This uses visual automation.

click image/button.png

This allows you to look for button.png within the image folder.

Live mode

We recommend using live mode when you want to write your own flows or try out some step. In Command Prompt/Terminal:

tagui live

This starts up a live session, where you can run steps one line at a time and immediately see the output.

If statements

You may want your flow to do something different depending on some factors. You can use an if statement to do this.

For example, if the URL contains the word “success”, then we want to click some buttons:

if url() contains "success"
  click button1.png
  click button2.png

url() is a helper function that gets the url of the current webpage. Note that the other lines are indented, ie. there are spaces (or tabs) in front of them. This means that they are in the if block. The steps in the if block will only be run if the condition is met, ie. the url contains the word “success”.

Note

Before v6, you need to use { and } to surround your if block.

From v6 onwards, the curly braces {} are optional.

Another common case is to check if some element exists. Here, we say that “if some-element doesn’t appear after waiting for the timeout, then visit this webpage”.

if !exist('some-element')
  https://tagui.readthedocs.io/

The ! negates the condition and comes from JavaScript, which TagUI code eventually translates to.

In this next example, we check if a variable row_count, which we assigned a value earlier, is equal to 5:

if row_count equals 5
  some steps

Here’s how we check if it is more than or less than 5:

if row_count more than 5
  some steps
if row_count less than 5
  some steps

Loops

You can use loops to do the same thing many times within the same flow. In order to run one flow many times with different variables, the standard way is to use datatables.

In this example, we repeat the steps within the curly braces { and } a total of 20 times:

for n from 1 to 20
  some steps

Helper functions

Helper functions are useful JavaScript functions which can get values to use in your steps.

Each helper function is followed by brackets (). Some helper functions take inputs within these brackets.

You can see all the helper functions in the reference.

csv_row()

Turns some variables into csv text for writing to a csv file. It takes variables as its input, surrounded by square brackets [] (which is actually a JavaScript array).

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

clipboard()

Gets text from the clipboard:

dclick pdf_document.png
wait 3 seconds
keyboard [ctrl]a
keyboard [ctrl]c
text_contents = clipboard()

You can also give it an input, which puts the input onto the clipboard instead. This can be useful for pasting large amounts of text directly, which is faster than using the type step:

long_text = "This is a very long text which takes a long time to type"
clipboard(long_text)
click text_input
keyboard [ctrl]v
keyboard [enter]

mouse_x(), mouse_y()

Gets the mouse’s x or y coordinates.

This is useful for modifying x or y coordinates with numbers for using in steps like read and click.

The example below clicks 200 pixels to the right of element.png:

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

mouse_xy()

In live mode, you can use find out the coordinates of your mouse using echo `mouse_xy()` so that you can use the coordinates in your flows:

echo `mouse_xy()`