Block reference / UI Interaction

Read element

Read an element's text, description, id, position or state, or count how many match.

Only inWarpX Phone

Read element takes something off the screen and into the workflow: a price, an order number, a username, whether a switch is on. It reads the element the app describes, so the value is exact, with no OCR involved. For text drawn into a picture, use Read text (OCR).

Read element reads the price's text, $49.00, into the table.
The Read element block's settings, filled in as in the example below.

Settings

Selector

The element to act on. Inspect opens the Inspector for the phone picked in the editor's toolbar: pick the element, then Use in block for its locator, which still finds the element after the app changes, or Use XPath. You can also write an XPath such as //android.widget.Button[@text='Sign in'], or plain text, which means the element whose text is exactly that; Verify looks for it on the phone now and says whether it found one, several or none.

Example//android.widget.TextView[@resource-id='com.example.shop:id/price']
Read

Text, Description (the content description screen readers use), View id, Bounds, Checked, Selected, Enabled, Exists (true / false) or How many match.

ExampleText
Assign to variable

Also stores the value read in a workflow variable.

ExampleChecked
Variable namewhen Assign to variable is on

The variable to write. Later blocks read it as {{variables.price}}; start the name with $push: to add to a list instead of replacing it.

Exampleprice
Insert to table

Writes the value read into the workflow's table, one row per run of the block. Offered once the workflow's table has columns.

ExampleChecked
Select columnwhen Insert to table is on

The table column to write to. Later blocks read the latest row as {{table.$last.price}}.

Exampleprice
Wait up to (ms)when Read is not Exists (true / false) or How many match

How long to keep looking for the element before the block fails, in milliseconds, up to 120000. The default is 5000.

Example5000
Scroll to find element (times)when Read is not Exists (true / false) or How many match

When the element is not on screen, scroll the screen's main list and look again, up to this many times (at most 50). 0 does not scroll. It stops early when the list cannot move any further.

Example0
Delay (ms)

A pause after the block finishes, before the next block starts. Write one number such as 1000, or a range such as 1000,3000 for a random pause in that range on each run.

Example0

Every block also has the shared block settings — a description, Disable block and what to do on an error, and Finding elements on a phone explains selectors, Inspect and Verify in more depth. Fields that take text accept data from earlier blocks.

What it hands on

Hands on the value as {{prevBlockData}}, and writes it to the variable and the table column when asked. View id reads like com.example.shop:id/price; Bounds is left,top,right,bottom in the screen's pixels; Checked, Selected, Enabled and Exists (true / false) are true or false; How many match is a number, up to 200.

Example: Record each product's price

  1. Start
  2. Loop data
  3. Touch
  4. Read element
  5. Press Back
  6. Loop breakpoint
Where Read element sits in the example workflow.
  1. Pick the phone in the editor's toolbar and open a product in the shop app.
  2. Add a Read element block, click Inspect, pick the price and press Use XPath.
  3. Leave Read on Text, tick Insert to table and pick a price column.
  4. Put it in a Loop data with a Touch that opens each product and a Press Back after it.
  5. Press Run, then open Table: one price per product, such as $49.00.

Good to know

  • Exists (true / false) and How many match look once and never fail. Every other choice waits for the element and fails when it does not show.
  • With several matches, the first is read. Use How many match to count rows, such as the items in a cart.
  • Element blocks read the screen through the WarpX agent, which the Devices page installs on the phone. Without it the block fails with AGENT_NOT_INSTALLED.
  • What Selector accepts: anything starting with / or (/ is an XPath, evaluated as full XPath 1.0 over the screen's elements with the attributes Appium uses (text, resource-id, content-desc, class, package, bounds and flags such as clickable), so contains() and starts-with() work. Text starting with { or [ is read as JSON: the locator Use in block writes, or a selector such as {"res": "com.example.shop:id/search_box"}. Anything else is the exact, case-sensitive text of an element. There is no text= or id= shorthand: text=Sign in looks for an element whose text is text=Sign in.
  • When the block fails, it leaves by its fallback output if one is connected: a phone block comes with On error set to Execute fallback. With nothing connected there, the workflow's On workflow error setting decides.

See also

  • Read text (OCR) — Read the text in an area of the phone's screen, by OCR.
  • Element exists — Whether an element is on the phone's screen: true or false.
  • Element action — Tap, click, long-press, type into, clear, scroll or focus an element.